kernel/defs.h

Struct names used in the prototypes

These lines declare struct tags without their contents (incomplete types). That is all a prototype needs to mention a pointer such as struct buf*: the compiler does not need to know a struct’s size or fields to pass a pointer to it. Each full definition lives in its own header (kernel/buf.h, kernel/proc.h, kernel/file.h, …), which only the files that look inside the struct include. Without these lines, a tag first seen inside a prototype’s parameter list would be a different, local type in each prototype, and calls would not type-check.

struct cpu is not in the list but is used on line 92. That one is safe because it appears in a return type at file scope, which declares the tag for the whole file.

Line 1, // clang-format off, tells the code formatter not to re-flow the aligned columns below. There is no matching clang-format on; it stays off to the end of the file.

bio.c: the buffer cache

kernel/bio.c keeps in-memory copies of disk blocks, the buffer cache. bread returns a locked buffer holding a block’s contents, bwrite writes it to disk, and brelse releases it. bpin and bunpin keep a buffer in the cache while the log needs it. binit runs once at boot.

console.c: the console device

kernel/console.c turns the UART into the console: consoleintr receives each typed character from uartintr and does line editing (cooked input); consputc outputs one character for printk. consoleinit is called from main.

exec.c: load a program

kexec replaces the current process’s memory with a program loaded from a file (exec). The kernel versions carry a k prefix (kexec, kexit, kfork, kwait, kkill), which keeps them apart from the user-level functions of the same name.

file.c: open files

kernel/file.c manages the table of open files, the objects that file descriptors refer to. filealloc, filedup and fileclose manage their reference counts; fileread, filewrite and filestat dispatch to pipes, devices or inodes. Their uint64 arguments are user addresses, as passed to the system call.

fs.c: inodes and directories

kernel/fs.c is the file system proper: inodes (ialloc, ilock, iput, readi, writei…), directories (dirlookup, dirlink) and path name lookup (namei, nameiparent). fsinit reads the superblock and recovers the log; it is called by the first process (forkret), not by main, because it may sleep.

kalloc.c: physical pages

kernel/kalloc.c is the page allocator: kalloc returns one free 4096-byte page of physical memory (or 0), and kfree gives one back. kinit fills the free list at boot.

log.c: crash-safe transactions

kernel/log.c implements the write-ahead log. File system code brackets each operation with begin_op and end_op, and writes modified blocks with log_write instead of bwrite, so that an operation either happens completely or not at all, even if the machine crashes. initlog runs from fsinit.

pipe.c: pipes

kernel/pipe.c implements pipes: pipealloc creates a pipe and the two open files for its ends; piperead and pipewrite move data, sleeping when the pipe is empty or full.

printk.c: kernel printing

printk is the kernel’s printf, writing to the console; panic prints a message and stops the kernel; printkinit sets up the lock that keeps lines from different harts apart. Both prototypes carry an attribute; see the line notes.

proc.c: processes and scheduling

kernel/proc.c owns the process table. The groups:

• identity: cpuid, mycpu, myproc;
• the process life cycle behind system calls: kfork, kexit, kwait, kkill, killed, setkilled, growproc;
• page tables for a process: proc_pagetable, proc_freepagetable, and proc_mapstacks for the kernel stacks;
• scheduling: scheduler, sched, yield, and the sleep and wakeup functions sleep_prepare, sleep and wakeup;
• boot: procinit and userinit;
• helpers for code that may copy to either user or kernel memory (either_copyout, either_copyin), and procdump for debugging (Ctrl-P).

Note the split sleep: in this version a sleeper calls sleep_prepare(chan) while holding its own lock, releases that lock, and then calls sleep(), as in sys_pause. Older xv6 versions had a single sleep(chan, lock).

swtch.S: the context switch

swtch saves the current kernel thread’s callee-saved registers into one struct context and loads another, switching between a process’s kernel thread and the scheduler (context switch). It is written in assembly in kernel/swtch.S; this prototype lets C code call it.

spinlock.c: spinlocks

Spinlocks: acquire waits in a loop until the lock is free, release frees it, holding checks whether this CPU holds it. push_off and pop_off disable and re-enable interrupts in a nested way; acquire and release use them so that an interrupt handler on the same CPU can never wait for a lock its own CPU holds.

sleeplock.c: sleep locks

Sleep locks can be held for a long time, such as across a disk read, because a process waiting for one sleeps instead of spinning. Used for inodes and buffers.

string.c: memory and string helpers

The kernel has no C library, so kernel/string.c supplies the few functions it needs. safestrcpy is xv6’s own: unlike strncpy, it always NUL-terminates the destination. The size parameters are uint or int rather than the standard size_t.

syscall.c: argument fetching and dispatch

The helpers that read system call arguments (argint, argaddr, argstr) and copy from user addresses (fetchaddr, fetchstr), used by the sys_* functions in kernel/sysproc.c and kernel/sysfile.c; and syscall itself, called by usertrap. Note that argint and argaddr return void: they cannot fail.

trap.c: the clock and trap setup

Two variables and three functions. ticks and tickslock are shared with kernel/sysproc.c (sys_pause, sys_uptime). trapinit and trapinithart are called from main; prepare_return is called from forkret in kernel/proc.c as well as from usertrap.

usertrap, kerneltrap and devintr are not declared here: they are only called from assembly or from trap.c itself.

uart.c: the serial port

The UART driver in kernel/uart.c: uartinit configures the chip, uartintr handles its interrupts (called from devintr), uartwrite sends a buffer of characters (sleeping while the UART is busy), and uartputc_sync sends one character by busy-waiting, which works even with interrupts off; consputc uses it, so printk and panic can always print.

vm.c: page tables

kernel/vm.c manages page tables:

• the kernel’s: kvminit, kvminithart, kvmmap;
• building and walking any page table: mappages, walk, walkaddr, ismapped;
• a process’s user memory: uvmcreate, uvmalloc, uvmdealloc, uvmcopy (for fork), uvmfree, uvmunmap, uvmclear (for the stack guard page);
• copying between kernel and user memory: copyout, copyin, copyinstr;
• vmfault, which maps a lazily allocated page on first use.

In this version the copy functions take an extra uint64 after the page table: the process size p->sz, which they pass to vmfault so it can tell valid lazy addresses from bad ones.

plic.c: the interrupt controller

The PLIC driver in kernel/plic.c: plicinit and plicinithart at boot, plic_claim and plic_complete around each device interrupt in devintr.

virtio_disk.c: the disk

The virtio disk driver in kernel/virtio_disk.c: virtio_disk_init at boot, virtio_disk_rw to read or write one buffer (called by the buffer cache; it sleeps until the disk finishes), and virtio_disk_intr, called from devintr when the disk signals completion.

Number of elements in an array

NELEM gives the number of elements of an array: its total size in bytes divided by the size of one element. It is evaluated at compile time. It only works on a real array, not on a pointer: for a pointer, sizeof(x) is 8, the size of the pointer. syscall uses it to bounds-check the system call number, and sys_exec to bound the argv array.