README

What xv6 is

Unix Version 6 (“v6”) is the version of Unix that Dennis Ritchie and Ken Thompson’s group at Bell Labs released in 1975, for the PDP-11 minicomputer. It was small enough to read in full, and it shaped the design of most later Unix-like systems: processes created with fork and exec, everything as files, a shell that is an ordinary program.

xv6 rewrites a system with v6’s structure from scratch: the same kinds of system calls (fork, exec, pipe, open, read…) and a similar inode-based file system, but for a modern multiprocessor RISC-V machine, with locking, and in C instead of the 1970s dialect v6 used. “ANSI C” here means standard C; in practice the Makefile compiles it as C99 with GNU extensions (-std=gnu99), for things such as inline assembly and __attribute__.

Where the idea came from, and who built it

John Lions’s Commentary is a famous book that prints the entire v6 kernel source with a line-by-line explanation, written in the 1970s for Lions’s operating-systems course at the University of New South Wales. For years it was the standard way to learn how a real kernel works. xv6 was created at MIT to play the same role with a modern machine and modern C; the site you are reading follows the same line-by-line idea.

The course page https://pdos.csail.mit.edu/6.1810/ (MIT 6.1810, Operating System Engineering) also links the companion textbook, xv6: a simple, Unix-like teaching operating system, by Russ Cox, Frans Kaashoek and Robert Morris, which explains the design chapter by chapter. Reading a chapter of the book alongside the matching files here is a good way to study.

The named contributors worked on particular parts: Russ Cox on context switching (kernel/swtch.S, scheduler) and locking (kernel/spinlock.c), Cliff Frey and Xiao Yu on multiprocessor (“MP”) support.

Bug reports and patches

A list of people who reported bugs or sent fixes over the years, most of them students and teachers using xv6 in courses. It is a reminder that even a small teaching kernel has had many subtle bugs, found by readers who studied the code closely.

Where to send errors

Frans Kaashoek and Robert Morris maintain xv6 at MIT. Today the source lives on GitHub at https://github.com/mit-pdos/xv6-riscv, where issues and pull requests are the usual way to report problems. Note the stated policy: xv6 exists for teaching, so changes that make it simpler or clearer are welcome, while new features mostly are not. That is why so many parts of xv6 are deliberately minimal (a fixed-size process table, one directory level created by mkfs, no file permissions); 6.1810’s labs ask students to add such features themselves.

How to build and run it

You need two things on your computer:

• a RISC-V cross-compiler / toolchain: a gcc, linker and related tools that run on your machine but produce RISC-V code. The README points at building one from source with riscv-gnu-toolchain (“newlib” is the bare-metal C library that build uses, meaning the tools target programs without an operating system). Packaged versions work too: the Makefile tries several prefixes, among them riscv64-unknown-elf-, riscv64-elf- (Homebrew on macOS) and riscv64-linux-gnu- (Debian and Ubuntu) (Makefile:39).
• QEMU built for the riscv64-softmmu target, which is the program qemu-system-riscv64, an emulator for a whole RISC-V computer. The Makefile requires at least version MIN_QEMU_VERSION.

Then make qemu builds the kernel, the user programs and fs.img, and boots xv6 in your terminal. Ctrl-A then X quits QEMU. The CI configuration shows the exact Ubuntu packages, and the compiler package for macOS (riscv64-elf-gcc); on macOS you also need QEMU (brew install qemu).