How snu-csl/xv6-riscv-snu works
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: fs.c FS stack · Makefile Makefile · main.c Kernel init · ls.c User tools
Components 17
Repository
Top-level build and project orchestration
- Makefile · Compiles kernel and user programs, builds the disk image, and launches QEMU
Makefile
Kernel
RISC-V xv6 kernel subsystems
- Boot code · Early CPU startup and low-level trap/privilege transitions
kernel/start.c - Kernel init · Main kernel initialization and startup of the first process
kernel/main.c - Process mgmt · Fork/exit/wait, sleep/wakeup, and CPU scheduling
kernel/proc.c - Syscalls · System call dispatch and filesystem/process syscall handlers
kernel/syscall.c - VM + traps · Page tables, trap handling, and user/kernel mode transitions
kernel/vm.c - Exec loader · Loads ELF binaries and builds a new user address space
kernel/exec.c - FS stack · Filesystem, logging, buffer cache, and file abstraction
kernel/fs.c - Drivers · Console, UART, PLIC, and virtio block device support
kernel/virtio_disk.c - Locks · Spinlocks and sleeplocks protecting shared kernel state
kernel/spinlock.c - Kernel lib · Shared kernel utilities, types, and headers used across subsystems
kernel/string.c
User space
Init, shell, utilities, and user runtime
- Init · First user process that starts the shell
user/init.c - Shell · Interactive shell and command execution environment
user/sh.c - User tools · Core user commands and xv6 test utilities
user/ls.c - User runtime · User library, allocator, printf, and syscall stubs
user/ulib.c
Build tools
Filesystem image generation and boot packaging
- mkfs · Creates the initial filesystem image used by the OS
mkfs/mkfs.c
Validation
Tests and stress workloads
- Tests · System tests and stress programs for process and filesystem behavior
test-xv6.py
Connections 25
- 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