# snu-csl/xv6-riscv-snu architecture

> Architecture diagram of the GitHub repository snu-csl/xv6-riscv-snu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snu-csl/xv6-riscv-snu
- Repository: https://github.com/snu-csl/xv6-riscv-snu

## Overview

1. **Overall shape**
   This repository is a small monolithic operating system, xv6, targeting **RISC-V**. The code is split into three main areas: the **kernel** (`kernel/`), the **user-space programs** (`user/`), and the **filesystem image builder** (`mkfs/`). The top-level `Makefile` ties these together into a bootable image run under **QEMU** with a RISC-V cross-toolchain.

2. **Boot and early initialization**
   Boot starts in assembly (`kernel/start.c`, `kernel/entry.S`) and transitions into C initialization in `kernel/main.c`. From there the kernel brings up memory management, device interrupts, process tables, and the filesystem before starting the first user process. The `kernel.ld` and `kernelvec.S`/`trampoline.S` files define low-level linker, trap, and privilege-mode transition behavior.

3. **Process model and scheduling**
   Process management lives primarily in `kernel/proc.c` and `kernel/proc.h`. This subsystem handles process creation, forking, exit/wait, sleeping/wakeup, and context switching (`kernel/swtch.S`). xv6 uses a simple scheduler inside the kernel rather than any user-level runtime. The process layer is one of the main boundaries: it owns execution state, but delegates I/O, filesystem, and memory operations to other subsystems through system calls.

4. **System call boundary**
   User programs do not call kernel functions directly; they enter through the syscall interface in `kernel/syscall.c`, `kernel/sysproc.c`, and `kernel/sysfile.c`. The user-side stubs are generated/declared via `user/usys.pl` and exposed through `user/user.h`. This is the core user/kernel boundary: arguments are copied across, validated, and dispatched to kernel handlers.

5. **Virtual memory and trap handling**
   Memory management is centralized in `kernel/vm.c` and `kernel/vm.h`, with architecture-specific details in `kernel/riscv.h` and `kernel/memlayout.h`. The trap path (`kernel/trap.c`, `kernel/kernelvec.S`, `kernel/trampoline.S`) handles transitions between user and kernel mode for syscalls, interrupts, and exceptions. This subsystem governs address translation, page tables, and safe switching between user processes and kernel execution.

6. **Filesystem stack**
   xv6’s filesystem is implemented in `kernel/fs.c`, `kernel/bio.c`, `kernel/log.c`, `kernel/file.c`, and the inode/log/buffer support types in `kernel/fs.h`, `kernel/buf.h`, `kernel/file.h`. The design is layered: the buffer cache sits below the filesystem, the write-ahead log protects consistency, and the file layer presents open files to syscalls. Most user-visible persistence flows through this stack, not directly to the disk driver.

7. **Storage and device I/O**
   Block storage is backed by `kernel/virtio_disk.c` and `kernel/virtio.h`, indicating a **Virtio block device** model typically provided by QEMU. Interrupt routing is managed by `kernel/plic.c`. Console and serial I/O use `kernel/uart.c` and `kernel/console.c`. These drivers are thin, hardware-facing boundaries that feed data to higher-level kernel services such as the filesystem and shell.

8. **Synchronization and concurrency**
   The kernel is multiprocessor-aware and uses simple locking primitives: `kernel/spinlock.c`, `kernel/sleeplock.c`, and associated headers. These locks protect shared structures such as process tables, buffers, and filesystem metadata. Concurrency is mostly kernel-internal; user space sees it indirectly through process scheduling, pipes, and shared filesystem state.

9. **Kernel services exposed to user space**
   Additional OS services are implemented in dedicated files: pipes in `kernel/pipe.c`, strings/memory utilities in `kernel/string.c` and `kernel/printf.c`, and standard stat/open flags in `kernel/fcntl.h` and `kernel/stat.h`. The kernel is intentionally compact, so many “services” are small, direct implementations rather than layered frameworks.

10. **User-space environment**
   `user/` contains the standard xv6 userland: shell (`sh.c`), core utilities like `cat`, `ls`, `echo`, `grep`, `wc`, `mkdir`, `rm`, `ln`, `kill`, plus test and stress programs. `user/init.c` is the first user process, which typically launches the shell. `user/ulib.c`, `user/umalloc.c`, and `user/printf.c` provide the user runtime support needed by these programs.

11. **Executable loading and launch**
   User binaries are linked with `user/user.ld` and loaded by the kernel via `kernel/exec.c`, which parses ELF files (`kernel/elf.h`). The flow is: filesystem stores the binary image, `exec` reads it, builds a new address space, and transfers control into user mode. This is a key data path connecting filesystem, VM, and process management.

12. **Filesystem image creation and build pipeline**
   `mkfs/mkfs.c` creates the initial filesystem image used by xv6. The build system compiles kernel and user binaries, packages them into an image, and boots the result in QEMU. The README explicitly notes the need for a **RISC-V GNU toolchain** and **qemu-riscv64-softmmu**, making the repo’s runtime environment part of the architecture.

13. **Testing and stress validation**
   `test-xv6.py` and user programs like `usertests.c`, `stressfs.c`, `logstress.c`, `grind.c`, and the fork/orphan/zombie tests exercise the kernel’s process, filesystem, and synchronization behavior. These are not separate subsystems, but they are important for understanding the intended boundaries and invariants of the OS.

14. **Architectural summary**
   The repository is a single-address-space kernel plus separate user-space binaries, with the main data flow running from **user programs → syscalls → kernel services → device/filesystem drivers → hardware via QEMU**. The strongest boundaries are user/kernel mode, trap handling, and the filesystem/logging/storage stack. The codebase is deliberately minimal, so the architecture is easy to map directly from files to responsibilities.

Main entry points: [`kernel/fs.c`](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/fs.c) (FS stack), [`Makefile`](https://github.com/snu-csl/xv6-riscv-snu/tree/riscv/Makefile) (Makefile), [`kernel/main.c`](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/main.c) (Kernel init), [`user/ls.c`](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/user/ls.c) (User tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_makefile["Makefile<br/>build orchestration"]
end

subgraph group_kernel["Kernel"]
  node_boot_start["Boot code<br/>boot/trap setup<br/>[start.c]"]
  node_kernel_main["Kernel init<br/>init sequence<br/>[main.c]"]
  node_proc["Process mgmt<br/>process scheduler<br/>[proc.c]"]
  node_syscalls["Syscalls<br/>user/kernel boundary<br/>[syscall.c]"]
  node_vm_trap["VM + traps<br/>memory/trap control<br/>[vm.c]"]
  node_exec["Exec loader<br/>ELF launch<br/>[exec.c]"]
  node_fs_stack[("FS stack<br/>filesystem layer<br/>[fs.c]")]
  node_drivers["Drivers<br/>device I/O<br/>[virtio_disk.c]"]
  node_sync["Locks<br/>synchronization<br/>[spinlock.c]"]
  node_kernel_lib["Kernel lib<br/>support code<br/>[string.c]"]
end

subgraph group_user["User space"]
  node_user_init["Init<br/>first process<br/>[init.c]"]
  node_user_shell["Shell<br/>command interpreter<br/>[sh.c]"]
  node_user_utils["User tools<br/>utilities<br/>[ls.c]"]
  node_user_lib["User runtime<br/>C runtime<br/>[ulib.c]"]
end

subgraph group_build["Build tools"]
  node_mkfs["mkfs<br/>image builder<br/>[mkfs.c]"]
end

subgraph group_validation["Validation"]
  node_tests["Tests<br/>validation workloads<br/>[test-xv6.py]"]
end

node_makefile -->|"builds kernel"| node_boot_start
node_makefile -->|"builds userland"| node_user_utils
node_makefile -->|"builds image tool"| node_mkfs
node_makefile -.->|"runs validation"| node_tests
node_boot_start -->|"hands off"| node_kernel_main
node_kernel_main -->|"starts scheduler"| node_proc
node_kernel_main -->|"mounts fs"| node_fs_stack
node_kernel_main -->|"initializes devices"| node_drivers
node_proc -->|"serves calls"| node_syscalls
node_syscalls -->|"crosses boundary"| node_vm_trap
node_vm_trap -->|"supports launch"| node_exec
node_exec -->|"reads binaries"| node_fs_stack
node_exec -->|"installs address space"| node_vm_trap
node_fs_stack -->|"writes blocks"| node_drivers
node_fs_stack -->|"protects state"| node_sync
node_drivers -->|"uses locks"| node_sync
node_user_init -->|"starts shell"| node_user_shell
node_user_shell -->|"uses runtime"| node_user_lib
node_user_utils -->|"uses runtime"| node_user_lib
node_user_utils -->|"invokes kernel"| node_syscalls
node_tests -.->|"exercises"| node_user_utils
node_mkfs -->|"creates image"| node_fs_stack
node_user_lib -->|"makes calls"| node_syscalls
node_kernel_lib -.->|"shared support"| node_proc
node_kernel_lib -.->|"shared support"| node_fs_stack

click node_makefile "https://github.com/snu-csl/xv6-riscv-snu/tree/riscv/Makefile"
click node_boot_start "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/start.c"
click node_kernel_main "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/main.c"
click node_proc "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/proc.c"
click node_syscalls "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/syscall.c"
click node_vm_trap "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/vm.c"
click node_exec "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/exec.c"
click node_fs_stack "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/fs.c"
click node_drivers "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/virtio_disk.c"
click node_sync "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/spinlock.c"
click node_kernel_lib "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/string.c"
click node_user_init "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/user/init.c"
click node_user_shell "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/user/sh.c"
click node_user_utils "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/user/ls.c"
click node_user_lib "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/user/ulib.c"
click node_mkfs "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/mkfs/mkfs.c"
click node_tests "https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/test-xv6.py"

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_makefile toneBlue
class node_boot_start,node_kernel_main,node_proc,node_syscalls,node_vm_trap,node_exec,node_fs_stack,node_drivers,node_sync,node_kernel_lib toneAmber
class node_user_init,node_user_shell,node_user_utils,node_user_lib toneMint
class node_mkfs toneRose
class node_tests toneIndigo
```

## Components

### Repository

Top-level build and project orchestration

- [Makefile](https://github.com/snu-csl/xv6-riscv-snu/tree/riscv/Makefile): build orchestration · Compiles kernel and user programs, builds the disk image, and launches QEMU · `Makefile`

### Kernel

RISC-V xv6 kernel subsystems

- [Boot code](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/start.c): boot/trap setup · Early CPU startup and low-level trap/privilege transitions · `kernel/start.c`
- [Kernel init](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/main.c): init sequence · Main kernel initialization and startup of the first process · `kernel/main.c`
- [Process mgmt](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/proc.c): process scheduler · Fork/exit/wait, sleep/wakeup, and CPU scheduling · `kernel/proc.c`
- [Syscalls](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/syscall.c): user/kernel boundary · System call dispatch and filesystem/process syscall handlers · `kernel/syscall.c`
- [VM + traps](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/vm.c): memory/trap control · Page tables, trap handling, and user/kernel mode transitions · `kernel/vm.c`
- [Exec loader](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/exec.c): ELF launch · Loads ELF binaries and builds a new user address space · `kernel/exec.c`
- [FS stack](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/fs.c): filesystem layer · Filesystem, logging, buffer cache, and file abstraction · `kernel/fs.c`
- [Drivers](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/virtio_disk.c): device I/O · Console, UART, PLIC, and virtio block device support · `kernel/virtio_disk.c`
- [Locks](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/spinlock.c): synchronization · Spinlocks and sleeplocks protecting shared kernel state · `kernel/spinlock.c`
- [Kernel lib](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/kernel/string.c): support code · Shared kernel utilities, types, and headers used across subsystems · `kernel/string.c`

### User space

Init, shell, utilities, and user runtime

- [Init](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/user/init.c): first process · First user process that starts the shell · `user/init.c`
- [Shell](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/user/sh.c): command interpreter · Interactive shell and command execution environment · `user/sh.c`
- [User tools](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/user/ls.c): utilities · Core user commands and xv6 test utilities · `user/ls.c`
- [User runtime](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/user/ulib.c): C runtime · User library, allocator, printf, and syscall stubs · `user/ulib.c`

### Build tools

Filesystem image generation and boot packaging

- [mkfs](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/mkfs/mkfs.c): image builder · Creates the initial filesystem image used by the OS · `mkfs/mkfs.c`

### Validation

Tests and stress workloads

- [Tests](https://github.com/snu-csl/xv6-riscv-snu/blob/riscv/test-xv6.py): validation workloads · System tests and stress programs for process and filesystem behavior · `test-xv6.py`

## Connections

- Makefile → Boot code: builds kernel · Compiles and links the kernel image
- Makefile → User tools: builds userland · Builds user binaries included in the image
- Makefile → mkfs: builds image tool · Compiles the filesystem image builder
- Makefile → Tests: runs validation · Drives test and stress execution
- Boot code → Kernel init: hands off · Transfers control into C initialization
- Kernel init → Process mgmt: starts scheduler · Initializes process state and launches the first process
- Kernel init → FS stack: mounts fs · Brings up filesystem state during boot
- Kernel init → Drivers: initializes devices · Sets up console, interrupt, and disk devices
- Process mgmt → Syscalls: serves calls · Process operations are invoked through syscalls
- Syscalls → VM + traps: crosses boundary · Syscalls and traps move between user and kernel modes
- VM + traps → Exec loader: supports launch · Trap and VM machinery enable loading and entering user programs
- Exec loader → FS stack: reads binaries · Loads executables from the filesystem
- Exec loader → VM + traps: installs address space · Creates and switches user page tables
- FS stack → Drivers: writes blocks · Persists data through the block device driver
- FS stack → Locks: protects state · Uses locks around buffers, inodes, and log state
- Drivers → Locks: uses locks · Driver paths coordinate with kernel synchronization
- Init → Shell: starts shell · Init launches the command interpreter
- Shell → User runtime: uses runtime · Shell depends on user-space support code
- User tools → User runtime: uses runtime · Utilities link against the user library and stubs
- User tools → Syscalls: invokes kernel · User programs enter the kernel through syscalls
- Tests → User tools: exercises · Tests run user programs and stress system behavior
- mkfs → FS stack: creates image · Builds the initial filesystem contents consumed by the kernel
- User runtime → Syscalls: makes calls · Library stubs route into kernel system calls
- Kernel lib → Process mgmt: shared support · Kernel support code is used across major subsystems
- Kernel lib → FS stack: shared support · Utility types and helpers support filesystem code
