# duc-hust-et1/os-project architecture

> Architecture diagram of the GitHub repository duc-hust-et1/os-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/duc-hust-et1/os-project
- Repository: https://github.com/duc-hust-et1/os-project

## Overview

This is an xv6-riscv teaching kernel fork focused on kernel threads and a user-level thread library. The principal workflow is a user program creating and joining threads through the user API and kernel syscall boundary; the kernel schedules them while managing shared address spaces and process lifetime. The repository also retains xv6 boot, virtual memory, filesystem, and device-I/O subsystems. The README describes the thread capabilities, while sampled source confirms boot initialization; unsampled syscall and device call paths are not inferred.

Main entry points: [`kernel/main.c`](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/main.c) (Kernel Initialization), [`kernel/proc.c`](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/proc.c) (Process and Threads), [`user/user.h`](https://github.com/duc-hust-et1/os-project/blob/riscv/user/user.h) (User API), [`kernel/syscall.c`](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/syscall.c) (Syscall Boundary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Kernel Boot"]
  node_boot_init["Kernel Initialization<br/>[main.c]"]
  node_trap["Trap Handling<br/>[trap.c]"]
end

subgraph group_threading["Thread Runtime"]
  node_syscall["Syscall Boundary<br/>[syscall.c]"]
  node_proc["Process and Threads<br/>[proc.c]"]
end

subgraph group_memory["Memory Management"]
  node_addrspace["Address Spaces<br/>[addrspace.c]"]
  node_vm["Virtual Memory<br/>[vm.c]"]
  node_alloc["Physical Allocator<br/>[kalloc.c]"]
end

subgraph group_storage["Filesystem and Devices"]
  node_sysfile["File Syscalls<br/>[sysfile.c]"]
  node_file["Open Files<br/>[file.c]"]
  node_fs["Filesystem<br/>[fs.c]"]
  node_bio["Block Cache<br/>[bio.c]"]
  node_disk["Virtual Disk<br/>[virtio_disk.c]"]
end

subgraph group_userland["User Programs"]
  node_user_api["User API<br/>[user.h]"]
  node_thread_api["Thread API<br/>[thread.h]"]
  node_thread_lib["Thread Library<br/>[thread.c]"]
  node_thread_tests["Thread Tests<br/>[threadtest.c]"]
  node_parallel["Parallel Benchmark<br/>[parallel_sum.c]"]
  node_user_tests["User Tests<br/>[usertests.c]"]
  node_shell["Command Shell<br/>[sh.c]"]
end

node_user(("User"))

node_boot_init -->|"initializes"| node_proc
node_boot_init -->|"initializes"| node_trap
node_boot_init -->|"initializes"| node_vm
node_boot_init -->|"initializes"| node_fs
node_boot_init -->|"initializes"| node_file
node_user -.->|"runs commands"| node_shell
node_shell -.->|"uses syscalls"| node_user_api
node_user -.->|"runs tests"| node_thread_tests
node_thread_tests -->|"exercises"| node_thread_lib
node_parallel -->|"uses"| node_thread_lib
node_thread_lib -->|"implements"| node_thread_api
node_thread_api -->|"extends"| node_user_api
node_user_api -.->|"invokes"| node_syscall
node_syscall -.->|"dispatches clone/join"| node_proc
node_proc -->|"shares address space"| node_addrspace
node_proc -.->|"manages mappings"| node_vm
node_user_tests -->|"exercises"| node_user_api
node_syscall -.->|"dispatches file calls"| node_sysfile
node_sysfile -->|"uses open files"| node_file
node_file -.->|"accesses inodes"| node_fs
node_fs -.->|"reads and writes blocks"| node_bio
node_bio -.->|"submits I/O"| node_disk
node_vm -.->|"allocates pages"| node_alloc

click node_boot_init "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/main.c"
click node_trap "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/trap.c"
click node_syscall "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/syscall.c"
click node_proc "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/proc.c"
click node_user_api "https://github.com/duc-hust-et1/os-project/blob/riscv/user/user.h"
click node_thread_api "https://github.com/duc-hust-et1/os-project/blob/riscv/user/thread.h"
click node_thread_lib "https://github.com/duc-hust-et1/os-project/blob/riscv/user/thread.c"
click node_thread_tests "https://github.com/duc-hust-et1/os-project/blob/riscv/user/threadtest.c"
click node_parallel "https://github.com/duc-hust-et1/os-project/blob/riscv/user/parallel_sum.c"
click node_user_tests "https://github.com/duc-hust-et1/os-project/blob/riscv/user/usertests.c"
click node_shell "https://github.com/duc-hust-et1/os-project/blob/riscv/user/sh.c"
click node_addrspace "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/addrspace.c"
click node_vm "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/vm.c"
click node_alloc "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/kalloc.c"
click node_sysfile "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/sysfile.c"
click node_file "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/file.c"
click node_fs "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/fs.c"
click node_bio "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/bio.c"
click node_disk "https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/virtio_disk.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_boot_init,node_trap,node_user toneBlue
class node_syscall,node_proc toneAmber
class node_addrspace,node_vm,node_alloc toneMint
class node_sysfile,node_file,node_fs,node_bio,node_disk toneRose
class node_user_api,node_thread_api,node_thread_lib,node_thread_tests,node_parallel,node_user_tests,node_shell toneIndigo
```

## Components

### Kernel Boot

- [Kernel Initialization](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/main.c): `kernel/main.c`
- [Trap Handling](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/trap.c): `kernel/trap.c`

### Thread Runtime

- [Syscall Boundary](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/syscall.c): `kernel/syscall.c`
- [Process and Threads](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/proc.c): `kernel/proc.c`

### Memory Management

- [Address Spaces](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/addrspace.c): `kernel/addrspace.c`
- [Virtual Memory](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/vm.c): `kernel/vm.c`
- [Physical Allocator](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/kalloc.c): `kernel/kalloc.c`

### Filesystem and Devices

- [File Syscalls](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/sysfile.c): `kernel/sysfile.c`
- [Open Files](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/file.c): `kernel/file.c`
- [Filesystem](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/fs.c): `kernel/fs.c`
- [Block Cache](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/bio.c): `kernel/bio.c`
- [Virtual Disk](https://github.com/duc-hust-et1/os-project/blob/riscv/kernel/virtio_disk.c): `kernel/virtio_disk.c`

### User Programs

- [User API](https://github.com/duc-hust-et1/os-project/blob/riscv/user/user.h): `user/user.h`
- [Thread API](https://github.com/duc-hust-et1/os-project/blob/riscv/user/thread.h): `user/thread.h`
- [Thread Library](https://github.com/duc-hust-et1/os-project/blob/riscv/user/thread.c): `user/thread.c`
- [Thread Tests](https://github.com/duc-hust-et1/os-project/blob/riscv/user/threadtest.c): `user/threadtest.c`
- [Parallel Benchmark](https://github.com/duc-hust-et1/os-project/blob/riscv/user/parallel_sum.c): `user/parallel_sum.c`
- [User Tests](https://github.com/duc-hust-et1/os-project/blob/riscv/user/usertests.c): `user/usertests.c`
- [Command Shell](https://github.com/duc-hust-et1/os-project/blob/riscv/user/sh.c): `user/sh.c`

### Other components

- **User**

## Connections

- Kernel Initialization → Process and Threads: initializes (evidence: `kernel/main.c`)
- Kernel Initialization → Trap Handling: initializes (evidence: `kernel/main.c`)
- Kernel Initialization → Virtual Memory: initializes (evidence: `kernel/main.c`)
- Kernel Initialization → Filesystem: initializes (evidence: `kernel/main.c`)
- Kernel Initialization → Open Files: initializes (evidence: `kernel/main.c`)
- User → Command Shell: runs commands
- Command Shell → User API: uses syscalls (evidence: `user/sh.c`)
- User → Thread Tests: runs tests
- Thread Tests → Thread Library: exercises (evidence: `user/threadtest.c`)
- Parallel Benchmark → Thread Library: uses (evidence: `user/parallel_sum.c`)
- Thread Library → Thread API: implements (evidence: `user/thread.c`)
- Thread API → User API: extends (evidence: `user/thread.h`)
- User API → Syscall Boundary: invokes (evidence: `README`)
- Syscall Boundary → Process and Threads: dispatches clone/join (evidence: `README`)
- Process and Threads → Address Spaces: shares address space (evidence: `kernel/proc.c`)
- Process and Threads → Virtual Memory: manages mappings
- User Tests → User API: exercises (evidence: `user/usertests.c`)
- Syscall Boundary → File Syscalls: dispatches file calls
- File Syscalls → Open Files: uses open files (evidence: `kernel/sysfile.c`)
- Open Files → Filesystem: accesses inodes
- Filesystem → Block Cache: reads and writes blocks
- Block Cache → Virtual Disk: submits I/O
- Virtual Memory → Physical Allocator: allocates pages