Why system calls are traps, not calls
4 min readA user program cannot touch hardware directly, and it must not be allowed to. If any process could read the disk or reprogram the timer itself, one bug would corrupt the whole machine and one hostile program would read every file. So the processor runs ordinary programs in a restricted mode, and reserves a privileged mode for the kernel. A A system call, or syscall, is a controlled request from a user program to the kernel to perform a privileged operation, such as reading a file or creating a process. is the one legal way across that line.
The previous lesson followed xv6 from power-on to the shell and ended exactly where this one begins: the shell makes a write(1, "hi", 2) call and bytes appear on the console. Between that C call and the bytes is a journey through the hardware's trap machinery, the kernel's trap handler, a dispatch table and a kernel function, then back out again. This lesson traces every step of that journey, and then makes you repeat it yourself by adding two system calls to xv6.
The word that matters here is trap. A trap is any event that makes the processor stop the current instruction stream and jump to a fixed kernel handler: a system call, an illegal instruction, or a device interrupt. A system call is only one kind of trap, but it shares the same front door with page faults and timer interrupts. That is the first reason a system call is not a function call: a function call jumps to an address the caller chooses, inside its own code, with no change of privilege. A trap jumps to a fixed address that only the kernel configured, and it raises the privilege level on the way in, lowering it again on the way out.
The second difference is who polices it. A function call can jump anywhere and pass any pointer. A system call can only pass a number that selects one entry of a table the kernel controls, and every argument that is a pointer is checked before the kernel follows it. Those two properties, a fixed entry point and a validated interface, are what keep the kernel in charge.
Real systems use the same shape with different hardware. On an ARM board, a user program enters the kernel with the svc instruction and carries the number in register x8 on AArch64; on x86-64 it is the syscall instruction and rax. RISC-V, which xv6 uses, uses ecall and register a7. The instruction differs, but the design is universal: one instruction to cross, one register to say which service, and a kernel table that maps numbers to handlers.
The user side: usys.pl, the stub and register a7
4 min readWhen you write read(fd, buf, n) in an xv6 user program, you are not directly executing a trap. You are calling a tiny wrapper that xv6 generated for you. In user/user.h there is a prototype int read(int, void*, int);, but the body is not written by hand. It comes from a script, user/usys.pl, which the Makefile runs at build time to produce an assembly file user/usys.S.
The script is short and its output is mechanical. For each name in a list, it emits three instructions. Here is the shape of the generator and the stub it produces for read:
# the shape of user/usys.pl (abridged)
sub entry {
my $name = shift;
print ".global $name\n";
print "${name}:\n";
print " li a7, SYS_$name\n";
print " ecall\n";
print " ret\n";
}
entry("read");
# the stub this generates, user/usys.S
.global read
read:
li a7, SYS_read
ecall
ret
That is the entire user-side implementation of a system call. A A user stub is the tiny generated function that loads a system call number into a register, executes the trap instruction, and returns whatever the kernel left in a0. Three things happen in order. First, li a7, SYS_read loads the system call number A system call number is the integer that identifies which kernel service is requested; the user places it in a7 and the kernel uses it to index its dispatch table. into register a7. The SYS_read name is a macro defined in kernel/syscall.h, which usys.S includes. Second, ecall switches to supervisor mode and jumps to the trap handler. Third, when the kernel has finished and returned to user mode, ret returns from the stub with the result already sitting in a0.
Why a7? The RISC-V calling convention uses registers a0 through a7 for arguments. A system call may take up to six arguments, which occupy a0 through a5. The kernel needs one more register for the number, so it takes a7, the first register the convention leaves free. This is a deliberate ABI choice, not an accident: on the kernel side, syscall() knows to read the number from a7 and the arguments from a0 through a5, which is exactly what the C compiler would have put in those registers anyway if the stub had been a normal function.
ecall is the RISC-V environment call. Executed in user mode, it raises a trap whose cause code is 8 and delivers it to supervisor mode, at the address in the stvec control register. The hardware does very little: it saves the current program counter into sepc, records the previous mode in the sstatus SPP bit, sets the cause in scause, clears the interrupt-enable bit, and jumps. It does not switch page tables, does not switch stacks, and saves no general registers. The kernel's trap entry must do all of that itself, which is the subject of the next section.
Note that the stub does not check errors and does not set any errno variable. It is a pure pass-through. Whatever the kernel leaves in a0 is what the caller receives. xv6 deliberately has no errno; user code tests return values directly, for example if(fd < 0). Linux wraps this pass-through in the C library, and a later section contrasts the two conventions.
Through the trap: usertrap and usertrapret
4 min readThe previous lesson built the trampoline and followed the first ecall in detail, so this section only connects the dots you already have and names the two functions that do the deciding. When ecall fires, the hart is still using the user page table and the user's registers, and it jumps to uservec on the trampoline page. uservec saves all 32 registers into the The trapframe is the per-process page where uservec saves all 32 user registers on entry, and from which userret restores them on the way out., switches to the kernel page table and stack, and calls usertrap in kernel/trap.c, the C function that decides what kind of trap just happened.
usertrap first checks the sstatus SPP bit to be sure the trap really came from user mode, and switches stvec to point at kernelvec so that a trap while inside the kernel goes to the kernel's own handler rather than back to uservec. It saves the user program counter from sepc into the trapframe. Then it reads scause and dispatches:
- If
scauseis 8, this is a system call. It advances the saved program counter by four bytes, so the user resumes after theecallinstead of repeating it, and callssyscall(). - Otherwise it asks
devintrwhether a device interrupted, and if not, the trap is an exception from user code, and the process is killed.
The rest of the path out is usertrapret, which the previous lesson already described: it re-points stvec back at uservec, prepares the trapframe fields the next trap will need, sets sepc to the saved user program counter, and calls userret on the trampoline. userret switches satp back to the user page table, restores the 32 registers, and executes sret, which drops to user mode at the saved sepc.
Here is the whole path as one sequence:
User code calls the stub: the generated function has loaded the number into a7 and executes ecall.
Hardware traps: the processor saves pc to sepc, records user mode in SPP, sets scause to 8, jumps to the stvec address.
uservec runs: on the trampoline page, it saves all registers to the trapframe and switches to the kernel page table and stack.
usertrap dispatches: it points stvec at kernelvec, sees scause 8, advances the saved pc by 4, and calls syscall().
syscall() runs the handler: it reads the number from a7 and calls the matching kernel function.
usertrapret prepares the return: it restores stvec to uservec, fills the trapframe's kernel fields, sets sepc and sstatus.
userret switches back: on the trampoline, it loads the user page table into satp and restores the registers.
sret returns: the hart drops to user mode at the instruction after ecall, with the result in a0.
One subtlety worth naming, because it is a classic trap-and-exit bug: usertrap advances the program counter only for system calls. A page fault must resume at the faulting instruction so it can be retried; a system call must resume at the next instruction or it would loop forever. That single p->trapframe->epc += 4 is the difference.
Going deeperThe brief window before stvec is switched
There is a moment at the start of usertrap when the hart is executing in the kernel but stvec still holds the address of uservec. If a device interrupt arrived in that window, the hardware would route it to uservec, which assumes the user page table is still active, and the kernel would corrupt itself. The reason this window is safe is that the RISC-V hardware clears the interrupt-enable bit in sstatus when it takes a trap, and usertrap does not re-enable interrupts until after it has set stvec to kernelvec. On a multi-hart machine this per-hart ordering matters, because each hart has its own stvec and its own copy of sstatus.
syscall(): the table of function pointers
2 min readAt the heart of dispatch is kernel/syscall.c, and at the heart of that file is a single static array. Each element is a function pointer, and the array is indexed by system call number. Here is its shape:
// kernel/syscall.c (abridged): the dispatch table
static uint64 (*syscalls[])(void) = {
[SYS_fork] sys_fork,
[SYS_exit] sys_exit,
[SYS_wait] sys_wait,
[SYS_pipe] sys_pipe,
[SYS_read] sys_read,
[SYS_kill] sys_kill,
[SYS_exec] sys_exec,
[SYS_fstat] sys_fstat,
[SYS_chdir] sys_chdir,
[SYS_dup] sys_dup,
[SYS_getpid] sys_getpid,
[SYS_sbrk] sys_sbrk,
[SYS_sleep] sys_sleep,
[SYS_uptime] sys_uptime,
[SYS_open] sys_open,
[SYS_write] sys_write,
[SYS_mknod] sys_mknod,
[SYS_unlink] sys_unlink,
[SYS_link] sys_link,
[SYS_mkdir] sys_mkdir,
[SYS_close] sys_close,
};
The [SYS_fork] syntax is a designated initialiser: it says "put sys_fork at the array index whose value is SYS_fork", where SYS_fork is the number 1 from kernel/syscall.h. This is why the numbering must agree between the two files. In the standard xv6-riscv tree, the built-in system calls are numbered 1 through 21, so the table has 22 slots and slot 0 is left empty, holding a null pointer.
The dispatcher itself is small:
// the shape of syscall() in kernel/syscall.c
void
syscall(void)
{
int num;
struct proc *p = myproc();
num = p->trapframe->a7;
if(num > 0 && num < NELEM(syscalls) && syscalls[num]) {
p->trapframe->a0 = syscalls[num]();
} else {
printf("%d %s: unknown sys call %d\n",
p->pid, p->name, num);
p->trapframe->a0 = -1;
}
}
Three details here carry the whole design. First, the number comes from the trapframe's saved a7, not from the live register; by the time syscall() runs, uservec has saved all the user's registers to the trapframe, and the kernel may have clobbered the live registers meanwhile. Second, the bounds check is num > 0 and num < NELEM(syscalls): it rejects zero, which is not a valid number, and anything past the end of the table. Third, the table slot itself is checked for a non-null pointer before it is called, so a hole in the table is caught instead of causing a jump to address zero.
The handler takes no arguments and returns a uint64, yet you will see handlers such as sys_read reading arguments with helper functions. That is the next two sections: the arguments are not passed through the C calling convention at all, but fished out of the trapframe, and the return value is written back into the trapframe's a0 where userret will restore it.
Going deeperThe same table in a production kernel
Linux keeps the identical structure, at much larger scale, as sys_call_table. Each architecture owns its copy, indexed by the architecture's own numbering, and the handler functions are declared asmlinkage, which means "take the arguments from the registers the entry code left them in, not from the normal stack convention". Linux handlers are written with macros like SYSCALL_DEFINE3 that expand to asmlinkage long sys_read(...). The number itself is part of the architecture's ABI and, once assigned, can never change or be recycled, because compiled programs have it baked in; a removed call gets a placeholder that returns -ENOSYS. xv6 gives you the same lesson in miniature: change one number and every program you already compiled is wrong.
Reading arguments safely: argint, argaddr, argfd, argstr
3 min readA system call handler such as sys_write needs its three arguments, but it cannot read them from C parameters because it is declared to take none. Instead it calls small accessor functions that read the saved registers out of the current process's trapframe. The base function is argraw, which maps an argument index to a register:
// kernel/syscall.c (abridged): the raw argument accessor
static uint64
argraw(int n)
{
struct proc *p = myproc();
switch (n) {
case 0: return p->trapframe->a0;
case 1: return p->trapframe->a1;
case 2: return p->trapframe->a2;
case 3: return p->trapframe->a3;
case 4: return p->trapframe->a4;
case 5: return p->trapframe->a5;
}
panic("argraw");
return -1;
}
On top of that one function, xv6 builds four typed helpers, each adding one layer of meaning:
int argint(int n, int *ip); // the nth argument as an int
int argaddr(int n, uint64 *ip); // the nth argument as an address
int argfd(int n, int *pfd, struct file **pf); // nth argument as an open file
int argstr(int n, char *buf, int max); // nth argument as a string
argint and argaddr are nearly identical and simply store argraw(n) through a pointer; the split exists to make intent explicit in the caller, one saying "this is a number" and the other "this is a user address". argfd is the first one that validates: it reads an integer, checks that it is in range and that the process's open-file table actually has a struct file there, and returns that file. This is the first line of defence against a program passing descriptor 9999 or -3 and expecting the kernel to follow it. argstr reads an address and then calls fetchstr, which copies a null-terminated string out of user memory, the subject of the next section.
The reason handlers read arguments this way, rather than as ordinary C parameters, goes back to the trap. The kernel is entered by a trap, not a call, so no C calling convention applies at the boundary. The only reliable record of what the user passed is the trapframe that uservec filled. Accessing it through named functions keeps every handler correct and makes the marshalling explicit in one place.
argaddr returns a number, not a validated pointer you may follow. That number is a virtual address in the user's page table, which is not the table currently loaded, and the address may be invalid or may point at kernel memory from the user's point of view. Writing code like char *s = (char*)argraw(0); return strlen(s); is the single most common and most dangerous mistake in system call work. The only correct way to read user memory is through copyin and friends, which walk the user page table and check the result.
copyin and copyout: crossing the boundary with data
4 min readThe trapframe carries six integers across the boundary, which is enough for numbers and addresses but not for a filename or the contents of a buffer. Those live in user memory, and the kernel needs a safe way to read and write them. That is what copyin and copyout is the kernel function that copies bytes from a kernel buffer to a user virtual address, translating through the user page table and failing if the address is invalid. do. copyin moves bytes from user memory into a kernel buffer; copyout moves bytes from a kernel buffer back to user memory. The sysinfo system call you will write depends on copyout to hand its result struct back.
Why is this machinery necessary at all? The reason is the page table. When the kernel is running, satp holds the kernel page table, whose mappings are not the same as the user's. A user address such as 0x1f0 means "the second page of this process's address space", and only the process's own page table knows which physical page that is, or whether it is mapped at all. The kernel cannot simply load or store from that address; the store would be interpreted through the kernel table and land in the wrong place, or fault. Worse, the user might pass an address that is not mapped, or one it has no right to touch, and a blind dereference would let a buggy or hostile program make the kernel read or write arbitrary physical memory.
copyout solves both problems by translating each page itself. Here is its shape, walking the destination in page-sized pieces:
// kernel/vm.c (abridged): the shape of copyout
int
copyout(pagetable_t pagetable, uint64 dstva, char *src, uint64 len)
{
uint64 n, va0, pa0;
while(len > 0){
va0 = PGROUNDDOWN(dstva);
pa0 = walkaddr(pagetable, va0);
if(pa0 == 0)
return -1;
n = PGSIZE - (dstva - va0);
if(n > len)
n = len;
memmove((void *)(pa0 + (dstva - va0)), src, n);
len -= n;
src += n;
dstva = va0 + PGSIZE;
}
return 0;
}
The key line is pa0 = walkaddr(pagetable, va0). It walks the user's page table in software to find the physical page behind the virtual address, and returns zero if the address is not mapped. A zero result makes copyout fail with -1 rather than crash, and the handler then returns an error to the caller. After translation, memmove copies into the physical address directly, which is safe because the kernel page table maps all of physical memory at its physical addresses, the direct mapping the boot lesson set up.
A string uses the same machinery through fetchstr, which calls copyinstr to copy until it finds a null byte or hits the limit, protecting the kernel against a buffer with no terminator. Every filename in xv6, from exec("/init") to open("console"), crosses the boundary this way.
Going deeperWhy copyin walks the page table in software
You might ask why copyout does the translation itself instead of temporarily switching satp and letting the hardware translate the user address. Two answers. First, a software walk can validate the result: walkaddr returns an explicit failure for an unmapped address, which turns a potentially fatal fault into a clean error return. Second, switching page tables around every string copy is exactly the expensive, racy operation the trampoline exists to make rare. Linux takes the opposite engineering trade-off in many places: it maps the current process's user pages into the kernel address space and lets the hardware translate, but it still runs the copy through copy_from_user and copy_to_user, which check the address range and can fault in a controlled way, returning -EFAULT to the system call. The principle is identical even though the mechanism differs: user memory is always copied through a checked path, never dereferenced raw.
The return value: int in the kernel, errno in user space
3 min readEvery xv6 system call handler returns an int (stored in a uint64 slot), and the meaning is a convention: zero or positive for success, negative for an error. The handler writes that value into p->trapframe->a0, and because userret restores a0 from the trapframe, the user's stub sees the same value and its ret hands it straight back to the caller. There is no separate error channel and no errno variable anywhere in xv6. A user program simply tests the result, as user/sh.c does: a failed open returns -1 and the shell prints an error.
Linux keeps the same single-number channel but adds one layer on the user side. In the kernel, sys_read and its peers return negative error codes directly, such as -ENOENT or -EFAULT, which are small negative numbers in the range -1 down to -4095. The C library wrapper, whether glibc or musl, checks the raw return: if it falls in that small-negative range, the wrapper negates it into the errno is the per-thread variable where the C library stores the code of the most recent error, set from the kernel's negative return value. variable and returns -1 to the caller; if it is zero or positive, the wrapper leaves errno untouched and returns the value. This is why a Linux program tests if(fd < 0) and then reads errno, while an xv6 program only tests if(fd < 0). The kernel's convention is the same in both; what differs is whether anything translates it.
The small-negative range is a deliberate ABI choice on Linux: an error is always a value between -1 and -4095, and a genuine success value is always zero or positive, so the wrapper can tell them apart without an extra status flag. An xv6 kernel has no such formal bound; it simply uses -1 for almost every failure and the occasional distinct code, and relies on the fact that no successful call returns a negative number. One more Linux detail: its handlers are declared to return long, not int, so the type matches the full 64-bit register the value travels through. When you write your own handlers, keep to that convention: return a meaningful negative number on every failure, and do not invent positive "error" values.
Adding a system call: the trace example
4 min readThis is the section where the lesson turns hands-on, and it is the checklist you will reuse for every lab from here on. The example is trace, the first part of the MIT system-call lab: a call that takes a bitmask of system call numbers and makes the kernel print each traced call, with its return value, as it happens. The implementation is small, which is the point; the value is in learning the five places that must agree.
Declare it for user code in user/user.h: add
int trace(int);so user programs can call it.Generate the stub in user/usys.pl: add the name to the list so usys.S gets
li a7, SYS_trace; ecall; ret.Give it a number in kernel/syscall.h: add
#define SYS_trace 22, the next free number.Add the handler to the table in kernel/syscall.c: add
[SYS_trace] sys_trace,to the syscalls[] array.Implement the handler in kernel/sysproc.c: write
sys_trace, reading its argument with argint.
Then write a user program that calls it and add that program to the UPROGS list in the Makefile so it is compiled and linked into the file system image. Let me take each step in turn, showing the edits.
In user/user.h, alongside the existing prototypes, add the declaration a user program will see:
// user/user.h (new line)
int trace(int);
In user/usys.pl, add trace to the list of names the script emits stubs for. The stub then appears in the generated usys.S exactly as the previous sections showed, with the number coming from kernel/syscall.h.
In kernel/syscall.h, assign the next free number. The 21 built-in calls occupy 1 through 21, so the new one is 22:
// kernel/syscall.h (new line)
#define SYS_trace 22
In kernel/syscall.c, add one line to the table and, because the table grew, the NELEM(syscalls) check automatically accepts the new index:
// kernel/syscall.c: add to the syscalls[] array
[SYS_trace] sys_trace,
Finally, implement the handler in kernel/sysproc.c, the home of process-related calls. It reads its single argument and stores it on the current process:
// kernel/sysproc.c (new function)
uint64
sys_trace(void)
{
int mask;
argint(0, &mask);
myproc()->trace_mask = mask;
return 0;
}
This requires a field to store the mask. Add int trace_mask; to struct proc in kernel/proc.h, initialise it to zero in allocproc, and copy it from parent to child in fork so a trace follows a process across forks. The handler is deliberately trivial; the interesting logic lives in syscall(), which must consult the mask on every dispatch, and that is the next section.
The real discipline is that all five edits must agree. If you add the number in syscall.h but forget the table line, syscall() sees a null slot and prints "unknown sys call 22". If you forget the prototype in user.h but add the stub, user programs fail to compile with an implicit-declaration warning and, on modern compilers, an error. If the number in syscall.h disagrees with the table position, the kernel silently calls the wrong handler. None of these produces a loud message at the point you made the mistake; each surfaces somewhere else, later.
The course builds a pinned revision of xv6, and some upstream revisions have renamed system call implementations with a k prefix, for example kexec instead of exec, and may shape syscall() slightly differently. If a name in this lesson does not match your tree, trust your tree: open kernel/syscall.c, kernel/syscall.h and kernel/sysproc.c and follow the pattern you find there. The five-file structure and the numbering discipline are the same regardless of naming.
trace's mask logic, and sysinfo from the kernel's counters
5 min readTwo system calls, trace and sysinfo, together exercise every idea in this lesson. trace needs the dispatcher to observe itself; sysinfo needs the kernel to count its own memory and processes and copy a struct out to user space.
trace: observing the dispatcher
The trace mask is a bitmask: bit n set means "print system call number n". The check belongs in syscall(), because that function sees every call, and it must happen after the handler runs so the return value is available. The shape of the addition:
// inside syscall(), replacing the simple call
if(num > 0 && num < NELEM(syscalls) && syscalls[num]) {
p->trapframe->a0 = syscalls[num]();
if((p->trace_mask >> num) & 1)
printf("%d: syscall %s -> %d\n",
p->pid, syscall_name(num), p->trapframe->a0);
} else {
p->trapframe->a0 = -1;
}
A helper maps a number to a printable name, using a second array indexed the same way as syscalls[]. The two arrays must stay in the same order, which is one more reason the numbering discipline matters. Because fork copies trace_mask, a shell that traces a range and then runs a program sees the program's calls too, which is how the lab's trace 32 grep hello README style of command works: grep inherits the mask and reports its own read calls.
sysinfo: counting memory and processes
The second call fills a struct in the kernel and copies it out. Define the struct once, in a new header kernel/sysinfo.h so both sides share the layout:
// kernel/sysinfo.h
struct sysinfo {
uint64 freemem; // free physical memory, in bytes
uint64 nproc; // number of live processes
};
Counting free memory means walking the The free list is the kernel allocator's linked list of unused physical pages, threaded through the pages themselves, with a lock protecting the head. that kinit built during boot. Counting processes means scanning the The process table is the fixed array of process structures, NPROC entries long, each holding one process's state and fields. and counting the entries that are not UNUSED. Both helpers live on the kernel side:
// kernel side: count free pages by walking the freelist
uint64
count_free_mem(void)
{
uint64 n = 0;
struct run *r;
acquire(&kmem.lock);
for(r = kmem.freelist; r; r = r->next)
n += PGSIZE;
release(&kmem.lock);
return n;
}
// kernel side: count live processes by scanning the table
uint64
count_process(void)
{
uint64 n = 0;
struct proc *p;
for(p = proc; p < &proc[NPROC]; p++) {
acquire(&p->lock);
if(p->state != UNUSED)
n++;
release(&p->lock);
}
return n;
}
The locks are not decorative. The freelist is modified by every kalloc and kfree on every hart, so walking it without kmem.lock could follow a pointer while another hart unlinks it. The process table likewise changes as processes are created and freed. Taking the lock per entry makes the count a consistent-enough snapshot, though not a perfect one: between the two helpers the world can change, so freemem and nproc describe slightly different instants. That is acceptable for a status report and is exactly the kind of approximation a real free or top output also contains.
Finally the handler ties it together, reading the user's pointer with argaddr and copying the filled struct out with copyout:
// kernel/sysproc.c: the sysinfo handler
uint64
sys_sysinfo(void)
{
struct sysinfo info;
uint64 addr;
struct proc *p = myproc();
argaddr(0, &addr);
info.freemem = count_free_mem();
info.nproc = count_process();
if(copyout(p->pagetable, addr, (char *)&info, sizeof(info)) < 0)
return -1;
return 0;
}
Note the full loop of the lesson in one function: argaddr reads the argument, the helpers walk kernel data under locks, and copyout carries the result back through the user page table. To expose it to user code you repeat the five-file checklist, assigning SYS_sysinfo the number 23, declaring struct sysinfo; and int sysinfo(struct sysinfo *); in user/user.h, adding the stub in usys.pl, the table line in syscall.c, and the handler. The lab then provides a sysinfotest program that checks the reported values against reality.
Going deeperThe snapshot is not a guarantee
Do not assume the two fields in sysinfo were measured at the same moment. A timer interrupt can fire between count_free_mem returning and count_process starting, another process can fork, and the second number then describes a world where one more process exists than the first number's memory picture did. The kernel does not pause the machine to take a census, because pausing is exactly what a fast, low-latency kernel avoids. The same caveat applies to Linux's /proc/meminfo and /proc/stat: they report the values as read, one file at a time, and a process that samples them rapidly sees small inconsistencies. For a teaching kernel and for most monitoring, that is the right trade-off; for a real accounting guarantee you would need a global lock held across the whole census, which no production kernel does.
Building argv for exec, and the mistakes that bite
3 min readThe last advanced exercise pulls the threads together with a user program. The goal is an xargs-style program: read lines from standard input, treat each line as a command plus arguments, and run it with exec. Writing even a small version forces you to handle two things you have only seen from the kernel side so far: building an argument vector in user memory, and passing it to exec so it lands on the new program's stack.
exec expects a null-terminated array of char *, each pointing to a null-terminated string, all of which must live in the calling process's user memory. The kernel copies the strings and pointers out with copyinstr-style walks and writes them onto a fresh user stack for the new image. If any pointer is invalid or not null-terminated, exec fails. The construction is therefore a memory-layout exercise:
// the shape of an argument vector for exec
char *eargv[MAXARG];
eargv[0] = "echo";
eargv[1] = buf; // a word read from input, still in user memory
eargv[2] = 0; // the null terminator marks the end
if(exec(eargv[0], eargv) < 0) {
fprintf(2, "exec failed\n");
exit(1);
}
A full xargs also has to split a line into words and decide when a line is empty, which is ordinary string handling. The kernel-relevant part is the last three lines: the vector must be terminated by a null pointer, the strings must be in user memory and null-terminated, and exec replaces the current image so the code after a successful exec never runs. The if only catches failure.
The lab this lesson prepares ends with one entirely new system call of your own choosing, which is the same five-file exercise a third time, and this program is the natural way to test it. But before you write it, know the four mistakes that catch almost everyone the first time, and how to diagnose each.
The unknown-call print. Symptom: your program runs but every call to your new syscall prints unknown sys call N and returns -1. Cause: the number in kernel/syscall.h does not match the position in the syscalls[] table, or the table line is missing. Diagnose: grep SYS_ kernel/syscall.h and compare against the table order in kernel/syscall.c; the index N in the message is the number the kernel actually looked up. Fix: make the #define value equal the table slot, or add the missing [SYS_x] sys_x, line.
Build fails at assembly. Symptom: the build dies inside usys.S with an undefined SYS_x. Cause: you added the name to usys.pl but not the #define to kernel/syscall.h. Diagnose: the assembler error names the exact missing symbol. Fix: add the number to syscall.h and rebuild, which regenerates usys.S.
Implicit declaration in user code. Symptom: compiling your user program warns or errors that trace or sysinfo is implicitly declared. Cause: the prototype is missing from user/user.h. Diagnose: read the compiler's message, which points at the call site. Fix: add the prototype, and the forward struct sysinfo; declaration for sysinfo.
Garbage from copyout. Symptom: sysinfo returns but the struct's fields hold nonsense, or the call returns -1. Cause: you passed a bad address, copied the wrong size, or copied before filling the struct. Diagnose: check that you call argaddr before using the pointer, fill every field, and pass sizeof(info) to copyout, and that the user side declares the struct with the same layout. Fix: keep the struct definition in one shared header so both sides compile the same layout, which is the reason kernel/sysinfo.h exists.
The common thread in all four is that the failure shows up far from the edit that caused it. The discipline is always the same: make all five edits before the first build, then read the first error message as a pointer back to the file you missed.
Try it
1 min readOpen the lab and implement trace first: make the five edits, copy the mask through fork, add the printing to syscall(), and verify with the provided trace test. Then implement sysinfo with freemem and nproc, walking the freelist and the process table under their locks, and verify with the sysinfo test. Finish by adding one system call of your own choosing, with its own user program added to UPROGS, and use your xargs-style program or the shell to exercise it. Open the practice pack when you want questions that check what your own machine printed.
Key takeaways
- A system call is a privilege-mode switch driven by ecall, not an ordinary function call; the same trap path serves page faults and interrupts.
- usys.pl generates a three-instruction stub for every call, li a7, SYS_x; ecall; ret, so the number travels in a7 and the result comes back in a0.
- syscall() indexes an array of function pointers with the number in a7; keeping user.h, usys.pl and syscall.h in sync is what makes dispatch correct.
- The kernel reads arguments with argint, argaddr, argfd and argstr, and must use copyin/copyout rather than dereferencing user pointers.
- Handlers return an int and negative means error; Linux's C library turns a small negative kernel return into errno, while xv6 passes it through raw.
- Adding a syscall is five coordinated edits plus a user program; trace shows the whole path and sysinfo exercises copying a struct out.
- Counting free memory walks the kmem freelist under its lock, and counting processes scans the proc table; both answers are snapshots, not exact values.
Reflect
- Explain to a colleague, in two sentences: recall the order of a system call's journey from the ecall instruction through the kernel handler and back to user code.
- Which objective are you least sure about? Re-read that section, then do its exercise in the practice pack.
- What surprised you when you ran the commands yourself?
On a real board
Repeat the key commands on your Raspberry Pi or lab board over SSH or the serial console. Note anything that behaves differently from your PC, such as missing tools, a BusyBox shell or a read-only filesystem.
References and further reading
- Official docsxv6-riscv source repository (MIT PDOS)
- Official docsMIT 6.1810 lab: system calls (trace and sysinfo)
- SpecificationThe RISC-V Instruction Set Manual, Volume II: Privileged Architecture
- Man pagesyscalls(2) man page
- Man pageerrno(3) man page
- Official docsLinux kernel documentation: adding syscalls
Official documentation first. Links checked when the lesson was published.