kernel/syscall.c

C · 151 lines · annotated 100% · kernel · upstream

About this file

The system call dispatcher, and the helpers every system call uses to read its arguments.

When a user program executes ecall, usertrap recognizes a system call and calls syscall here. By then uservec has saved all of the program’s registers in its trapframe, so the kernel finds there what the program left in its registers: the system call number in a7 and up to six system call arguments in a0–a5. syscall uses the number to pick a function from the table syscalls, calls it, and writes its return value into the trapframe’s a0, which userret loads into the program’s a0 on the way back.

The first half of the file is the argument helpers: argint, argaddr and argstr read argument n; fetchaddr and fetchstr read a value or a string from a user address. They exist because arguments come from an untrusted program: an “address” may point anywhere, so the kernel never dereferences it directly, and copies through the process’s page table instead.

Read before: kernel/trap.c. Read next: kernel/sysproc.c and kernel/sysfile.c, where the sys_* functions live.

Show notes inline

1#include "types.h"
2#include "param.h"
3#include "memlayout.h"
4#include "riscv.h"
5#include "spinlock.h"
6#include "proc.h"
7#include "syscall.h"
8#include "defs.h"
9
10// Fetch the uint64 at addr from the current process.
11int
12fetchaddr(uint64 addr, uint64 *ip)
13{
14  struct proc *p = myproc();
15  if (addr >= p->sz ||
16      addr + sizeof(uint64) > p->sz) // both tests needed, in case of overflow
17    return -1;
18  if (copyin(p->pagetable, p->sz, (char *)ip, addr, sizeof(*ip)) != 0)
19    return -1;
20  return 0;
21}
22
23// Fetch the nul-terminated string at addr from the current process.
24// Returns length of string, not including nul, or -1 for error.
25int
26fetchstr(uint64 addr, char *buf, int max)
27{
28  struct proc *p = myproc();
29  if (copyinstr(p->pagetable, p->sz, buf, addr, max) < 0)
30    return -1;
31  return strlen(buf);
32}
33
34static uint64
35argraw(int n)
36{
37  struct proc *p = myproc();
38  switch (n) {
39  case 0:
40    return p->trapframe->a0;
41  case 1:
42    return p->trapframe->a1;
43  case 2:
44    return p->trapframe->a2;
45  case 3:
46    return p->trapframe->a3;
47  case 4:
48    return p->trapframe->a4;
49  case 5:
50    return p->trapframe->a5;
51  }
52  panic("argraw");
53  return -1;
54}
55
56// Fetch the nth 32-bit system call argument.
57void
58argint(int n, int *ip)
59{
60  *ip = argraw(n);
61}
62
63// Retrieve an argument as a pointer.
64// Doesn't check for legality, since
65// copyin/copyout will do that.
66void
67argaddr(int n, uint64 *ip)
68{
69  *ip = argraw(n);
70}
71
72// Fetch the nth word-sized system call argument as a null-terminated string.
73// Copies into buf, at most max.
74// Returns string length if OK (not including nul), -1 if error.
75int
76argstr(int n, char *buf, int max)
77{
78  uint64 addr;
79  argaddr(n, &addr);
80  return fetchstr(addr, buf, max);
81}
82
83// Prototypes for the functions that handle system calls.
84extern uint64 sys_fork(void);
85extern uint64 sys_exit(void);
86extern uint64 sys_wait(void);
87extern uint64 sys_pipe(void);
88extern uint64 sys_read(void);
89extern uint64 sys_kill(void);
90extern uint64 sys_exec(void);
91extern uint64 sys_fstat(void);
92extern uint64 sys_chdir(void);
93extern uint64 sys_dup(void);
94extern uint64 sys_getpid(void);
95extern uint64 sys_sbrk(void);
96extern uint64 sys_pause(void);
97extern uint64 sys_uptime(void);
98extern uint64 sys_open(void);
99extern uint64 sys_write(void);
100extern uint64 sys_mknod(void);
101extern uint64 sys_unlink(void);
102extern uint64 sys_link(void);
103extern uint64 sys_mkdir(void);
104extern uint64 sys_close(void);
105extern uint64 sys_sync(void);
106
107// An array mapping syscall numbers from syscall.h
108// to the function that handles the system call.
109static uint64 (*syscalls[])(void) = {
110  // clang-format off
111  [SYS_fork]    = sys_fork,
112  [SYS_exit]    = sys_exit,
113  [SYS_wait]    = sys_wait,
114  [SYS_pipe]    = sys_pipe,
115  [SYS_read]    = sys_read,
116  [SYS_kill]    = sys_kill,
117  [SYS_exec]    = sys_exec,
118  [SYS_fstat]   = sys_fstat,
119  [SYS_chdir]   = sys_chdir,
120  [SYS_dup]     = sys_dup,
121  [SYS_getpid]  = sys_getpid,
122  [SYS_sbrk]    = sys_sbrk,
123  [SYS_pause]   = sys_pause,
124  [SYS_uptime]  = sys_uptime,
125  [SYS_open]    = sys_open,
126  [SYS_write]   = sys_write,
127  [SYS_mknod]   = sys_mknod,
128  [SYS_unlink]  = sys_unlink,
129  [SYS_link]    = sys_link,
130  [SYS_mkdir]   = sys_mkdir,
131  [SYS_close]   = sys_close,
132  [SYS_sync]    = sys_sync,
133  // clang-format on
134};
135
136void
137syscall(void)
138{
139  int num;
140  struct proc *p = myproc();
141
142  num = p->trapframe->a7;
143  if (num > 0 && num < NELEM(syscalls) && syscalls[num]) {
144    // Use num to lookup the system call function for num, call it,
145    // and store its return value in p->trapframe->a0
146    p->trapframe->a0 = syscalls[num]();
147  } else {
148    printk("%d %s: unknown sys call %d\n", p->pid, p->name, num);
149    p->trapframe->a0 = -1;
150  }
151}

Lines 1–8

Headers

kernel/syscall.h provides the SYS_* numbers used as table indices below; kernel/proc.h provides struct proc and the trapframe layout.

Lines 10–21

fetchaddr(): read 8 bytes from user memory

Reads one uint64 at user virtual address addr into *ip, returning 0 on success and -1 if the address is not valid memory of the current process. Its one caller is sys_exec, which uses it to read the user’s argv array, one pointer at a time (kernel/sysfile.c:474).

The range check comes first. A process owns the addresses from 0 up to p->sz, so all 8 bytes must lie below p->sz. Line 16 alone would check that, except for overflow: if addr were close to 2⁶⁴, addr + 8 would wrap around to a small number and pass. Line 15 rejects such an addr, so, as the comment says, both are needed.

copyin then does the copy. It translates the address through the process’s page table, refuses pages without PTE_U (such as the trapframe and trampoline pages), and, if the page is a lazily allocated one not yet mapped, maps it first via vmfault. A direct *(uint64 *)addr would be wrong: the kernel runs with its own page table, in which addr means something else entirely.

Line 14

The current process (myproc); its sz and page table describe the memory it owns.

Lines 15–16

Reject unless all 8 bytes [addr, addr+8) lie inside the process’s memory [0, p->sz). See the block note for why both tests.

Line 18

Copy 8 bytes from user address addr into *ip, through the process’s page table (copyin).

Lines 23–32

fetchstr(): copy a string from user memory

Copies the NUL-terminated string at user address addr into the kernel buffer buf, at most max bytes including the NUL. Callers: argstr (path names for open, mkdir and friends) and sys_exec (each argv string, kernel/sysfile.c:484).

There is no explicit range check here: copyinstr does it page by page, failing for any page that is not valid user memory below p->sz. It also fails if no NUL appears within max bytes, so buf is always properly terminated on success, which makes the strlen on line 31 safe.

Line 29

Copy at most max bytes, stopping after the NUL; fails on a bad address or a missing NUL (copyinstr).

Line 31

Success: return the length, not counting the NUL.

Lines 34–54

argraw(): the nth argument register, as saved

Returns the raw 64-bit value the user program had in register an at the moment of ecall. The calling convention passes a C function’s first arguments in a0, a1, …; a user program calls a system call stub like any C function, and the stub (user/usys.pl) does not touch them, so they are still there when uservec saves them into the trapframe.

Only six registers are supported, which is enough for every xv6 system call. n is always a constant chosen by kernel code, never by the user, so an out-of-range n is a kernel bug: panic. The return -1 after it is never reached (panic is declared noreturn) and only keeps the function’s shape conventional.

static: used only by the helpers below.

Line 40

The saved a0: argument 0, as stored by kernel/trampoline.S:73.

Line 52

Kernel code asked for an argument beyond a5.

Lines 56–61

argint(): an integer argument

Stores argument n in *ip as an int. The assignment converts the 64-bit register value to 32 bits, keeping the low half, which is how a C int argument is passed in a 64-bit register.

Nothing is checked, and nothing can be: any integer is a possible argument. Each system call validates the values it receives (a file descriptor in range, a size not negative…). So argint returns nothing.

Line 60

Truncate the saved 64-bit register to an int.

Lines 63–70

argaddr(): a pointer argument

Stores argument n in *ip as a 64-bit user address. As the comment says, it is not checked here, because the address is only ever used through copyin, copyout or copyinstr, which check it on every access. A check here would be redundant.

Line 69

Store the raw 64-bit value; checked later, on use.

Lines 72–81

argstr(): a string argument

Combines the two steps for a string argument: read the pointer with argaddr, then copy the string with fetchstr. Returns the string length, or -1 if the pointer was bad or the string too long. Used for every path name, for example in sys_open (kernel/sysfile.c:338).

Line 79

Read argument n as a user address.

Line 80

Copy the string from that address into buf.

Lines 83–105

The system call functions

Declarations of the 22 handler functions, so the table below can name them. They are defined in three files: kernel/sysproc.c (exit, getpid, fork, wait, sbrk, pause, kill, uptime), kernel/sysfile.c (the file system calls and pipe), and kernel/log.c (sys_sync).

Every handler has the same type, uint64 (void): no parameters (each fetches its own arguments with argint and friends) and a 64-bit result that goes back to the user in a0. Giving them all the same type is what lets one table hold them all. (The extern is redundant on function declarations.)

Lines 107–134

The dispatch table

syscalls is an array of function pointers. Read the declaration from the name outwards: syscalls[] is an array, (*...) of pointers, (void) to functions taking no arguments, uint64 and returning a uint64.

It is filled with designated initializers: [SYS_fork] = sys_fork puts sys_fork at index SYS_fork (1). The table therefore lines up with kernel/syscall.h whatever order the lines are in. The highest index is SYS_sync (22), so the array has 23 entries; entry 0 is not named, so it is a null pointer, and syscall rejects number 0.

static: only syscall uses it. The clang-format off/on comments tell the code formatter to leave the aligned columns alone.

Line 109

Declare the table: an array of pointers to functions uint64 f(void), size taken from the initializers.

Line 111

Index 1 (SYS_fork) holds sys_fork. Each following line pairs a number from kernel/syscall.h with its handler.

Lines 136–141

syscall(): run the requested system call

Called by usertrap (kernel/trap.c:68) with interrupts enabled, on the process’s kernel stack. The process is the one that executed ecall.

Lines 142–146

Look up and call the handler

The number comes from the saved a7, where the user stub put it (li a7, SYS_...). It is untrusted, so it is checked before being used as an index: it must be positive, less than the table size (NELEM gives the number of elements), and the entry must not be null. Without these checks a bad number would make the kernel read a “function pointer” from outside the array and jump to it.

Line 146 calls the handler through the table and stores its result in the trapframe’s a0. That is how every system call returns its value: userret reloads the user’s a0 from this slot (kernel/trampoline.S:149), and the user stub’s ret hands it to the C caller as the return value.

For sys_exec the saved a0 slot has a second use: on success it holds argc, which becomes the first argument of the new program’s main.

Line 142

The system call number, from the user’s a7. Converting the uint64 to int keeps the low 32 bits.

Line 143

Validate the untrusted number before indexing the table.

Line 146

Call the handler and make its result the user’s a0.

Lines 147–151

Unknown system call

Print the process ID, its name and the bad number, and return -1 to the program. The process is not killed. a0 is a uint64, so -1 is stored as 0xffffffffffffffff; most user stubs are declared to return int (user/user.h), and the low 32 bits read as -1.

Line 148

printk the complaint.

Line 149

Return -1 to the program.