UNIX xv6 (rev8, 9/1/15) Documentation

(NOTE: The end of this page has advice on using this doxygen interface to browse the code.)

XV6 is based on Sixth Edition UNIX (UNIX V6). It is distributed from http://pdos.csail.mit.edu/6.828/2014/xv6.html.

See the Table of Contents, page 1, of xv6-rev8.pdf, for a nicely organized listing of the source files according to the subsystem of the operating system being implemented.

The code is surprisingly small (about 100 pages), yet complete. However, some of the modern operating system components that are not represented in xv6 are:

• kernel support for a network
• kernel support for threads
  (However, a user-space implementation, such as GNU's Portable Threads (GNU Pth), could be used to support a threads library.)
• a modern virtual memory system sufficient to support shared memory libraries, such as *.so files
  (But the code does use Intel x86 segments to provide independent virtual memory addresses for each process.)

For commentary on the source code, and a history of the original UNIX code, there is:

• the indexed printout of the code, xv6-rev8.pdf. See especially the "Table of Contents" on page 1 for the grouping of the files according to subsystem.
• a modern textbook/commentary on the xv6 code presented here.
• the older "Lions commentary" on the original UNIX V6, on which this xv6 code is based.
• a "Continuous UNIX commit history from 1972 until today" (in the format of a github repo).

  ---

Operating System Kernel

basic headers

     types.h param.h memlayout.h defs.h x86.h asm.h mmu.h elf.h

entering xv6

     entry.S entryother.S main.c

locks

     spinlock.h spinlock.c

processes

     vm.c proc.h proc.c swtch.S kalloc.c

system calls

     traps.h vectors.pl trapasm.S trap.c syscall.h syscall.c sysproc.c

file system

     buf.h fcntl.h stat.h fs.h file.h ide.c bio.c log.c fs.c file.c sysfile.c exec.c

pipes

     pipe.c

string operations

     string.c

low-level hardware

     mp.h mp.c lapic.c ioapic.c picirq.c kbd.h kbd.c console.c timer.c uart.c

user-level (also, see next section: "User-space source files")

     initcode.S usys.S init.c sh.c

boot loader

     bootasm.S bootmain.c

---

User-space source files:

There are also implementations of files for standard UNIX commands and for tests of the operating system. It's easy to recognize these files, since they have a main() routine, and are typically compiled as a single file. Here are all the files with: main() routines.

UNIX commands

     echo.c grep.c kill.c ln.c ls.c mkdir.c printf.c rm.c sh.c

UNIX include files (for end users, and maybe also in kernel)

     date.h stat.h fcntl.h syscall.h types.h user.h

The init process

After the kernel boots, this is the initial user-space process (pid 0). This process would traditionally fork a login process that would eventually fork a shell for the user, but this simple system directly creates a user shell (sh.c), without the need for a login.
     init.c

Test files and files for system administration

     console.c forktest.c kbd.c mkfs.c stressfs.c usertests.c zombie.c

Building the run-time library in user-space

Normally, libc.a (a static version of libc.so) is built from many *.o files (e.g., printf.o, malloc.o, string.o, etc.), which in turn are built from corresponding *.c file (e.g., using: gcc -c). xv6 doesn't build a separate libc.a. Instead the UNIX commands are directly linked against the corresponding *.o files, which normally would have been part of libc.a.

Components of libc.a

     ulib.c usys.S printf.c umalloc.c

---

Building the system

     Makefile      README

---

HELP on using the doxygen interface to browse the code.

(UNIX xv6 uses only C code. Ignore any references to classes and methods in the help items, below.)

1. Note the search box in the upper right. Try writing the name of any function, method, or global variable, and then select the specific symbol that you want to see.
2. Given an occurrence of a function or a method, click on it to to see a web page with links to the declaration of the function/method, as well as lines of code that call it. However, that web page will not show you the definition of the function/method. If you want to see its definition, then use the search box, as described above.
3. You can use the method above, to work your way up the call graph, by choosing a call to a function, and then scrolling up to to see what function called the original function. You can even follow this method recursively to find the top-level caller, which is likely to be main().
4. An alternate way to search for function, method, or global variable name is to search for it in an alphabetized index. Doxygen provides two such alphabetized indexes.
   1. If you are searching for a method, select the "Classes" tab, followed by the "Class Members" tab underneath. By default, the "All" tab will now be selected, and the "_" tab below that. The "_" tab refers to all symbols beginning with the character "_". So, you will usually need to select a different letter. For example, for a method called "foo", you'll need to select the "f" tab.
   2. If you are searching for a function, select the "Files" tab, followed by the "File Members" tab. Intuitively, doxygen views a file as another type of class. Hence, a function is a file member (member of a "class" denoted by that file).
5. When you click on a link to a line number or function definition, doxygen tries to scroll the target web page to place the desired information near the top of the web browser window. This may not happen if the line number or function definition is at the end of a file.