kernel/proc.h

C header · 104 lines · annotated 100% · kernel · upstream

Included by 15 files

kernel/console.c, kernel/exec.c, kernel/file.c, kernel/fs.c, kernel/pipe.c, kernel/printk.c, kernel/proc.c, kernel/sleeplock.c, kernel/spinlock.c, kernel/syscall.c, kernel/sysfile.c, kernel/sysproc.c, kernel/trap.c, kernel/uart.c, kernel/vm.c

About this file

The data structures behind processes and CPUs. Four structs and one enum:

struct context: the registers swtch saves when a kernel thread is switched out.
struct cpu: per-CPU state, one entry per hart in cpus.
struct trapframe: the page where a process’s user registers are saved when it enters the kernel (trapframe).
enum procstate: the states a process moves through.
struct proc: everything the kernel knows about one process, one entry per slot in the proc table.

The most important thing to learn here is which lock protects which field. The source states it in comments on struct proc; the notes below check those comments against how kernel/proc.c and the rest of the kernel actually use each field.

Read before: kernel/spinlock.h. Read next: kernel/proc.c and kernel/swtch.S.

Show notes inline

1// Saved registers for kernel context switches.
2struct context {
uint64 ra;
uint64 sp;
5
// callee-saved
uint64 s0;
uint64 s1;
uint64 s2;
uint64 s3;
uint64 s4;
uint64 s5;
uint64 s6;
uint64 s7;
uint64 s8;
uint64 s9;
uint64 s10;
uint64 s11;
19};
20
21// Per-CPU state.
22struct cpu {
struct proc *proc;      // The process running on this cpu, or null.
struct context context; // swtch() here to enter scheduler().
int noff;               // Depth of push_off() nesting.
int intena;             // Were interrupts enabled before push_off()?
27};
28
29extern struct cpu cpus[NCPU];
30
31// per-process data for the trap handling code in trampoline.S.
32// sits in a page by itself just under the trampoline page in the
33// user page table. not specially mapped in the kernel page table.
34// uservec in trampoline.S saves user registers in the trapframe,
35// then initializes registers from the trapframe's
36// kernel_sp, kernel_hartid, kernel_satp, and jumps to kernel_trap.
37// prepare_return() and userret in trampoline.S set up
38// the trapframe's kernel_*, restore user registers from the
39// trapframe, switch to the user page table, and enter user space.
40struct trapframe {
/*   0 */ uint64 kernel_satp;   // kernel page table
/*   8 */ uint64 kernel_sp;     // top of process's kernel stack
/*  16 */ uint64 kernel_trap;   // usertrap()
/*  24 */ uint64 epc;           // saved user program counter
/*  32 */ uint64 kernel_hartid; // saved kernel tp
/*  40 */ uint64 ra;
/*  48 */ uint64 sp;
/*  56 */ uint64 gp;
/*  64 */ uint64 tp;
/*  72 */ uint64 t0;
/*  80 */ uint64 t1;
/*  88 */ uint64 t2;
/*  96 */ uint64 s0;
/* 104 */ uint64 s1;
/* 112 */ uint64 a0;
/* 120 */ uint64 a1;
/* 128 */ uint64 a2;
/* 136 */ uint64 a3;
/* 144 */ uint64 a4;
/* 152 */ uint64 a5;
/* 160 */ uint64 a6;
/* 168 */ uint64 a7;
/* 176 */ uint64 s2;
/* 184 */ uint64 s3;
/* 192 */ uint64 s4;
/* 200 */ uint64 s5;
/* 208 */ uint64 s6;
/* 216 */ uint64 s7;
/* 224 */ uint64 s8;
/* 232 */ uint64 s9;
/* 240 */ uint64 s10;
/* 248 */ uint64 s11;
/* 256 */ uint64 t3;
/* 264 */ uint64 t4;
/* 272 */ uint64 t5;
/* 280 */ uint64 t6;
77};
78
79enum procstate { UNUSED, USED, SLEEPING, RUNNABLE, RUNNING, ZOMBIE };
80
81// Per-process state
82struct proc {
struct spinlock lock;
84
// p->lock must be held when using these:
enum procstate state; // Process state
void *chan;           // If non-zero, sleeping on chan
int killed;           // If non-zero, have been killed
int xstate;           // Exit status to be returned to parent's wait
int pid;              // Process ID
91
// wait_lock must be held when using this:
struct proc *parent; // Parent process
94
// these are private to the process, so p->lock need not be held.
uint64 kstack;               // Virtual address of kernel stack
uint64 sz;                   // Size of process memory (bytes)
pagetable_t pagetable;       // User page table
struct trapframe *trapframe; // data page for trampoline.S
struct context context;      // swtch() here to run process
struct file *ofile[NOFILE];  // Open files
struct inode *cwd;           // Current directory
char name[16];               // Process name (debugging)
104};

Lines 1–19

The registers saved by a context switch

A kernel thread that is not running is described completely by its stack and these 14 values. swtch stores them in the old context and loads them from the new one, at offsets 0, 8, …, 104, which must match the sd/ld offsets in kernel/swtch.S.

ra is where the thread resumes and sp is its stack. s0–s11 are the callee-saved registers: under the calling convention a called function must preserve them, so the code that called swtch may still need their values. The other registers are not here because the caller of swtch cannot rely on them surviving any function call anyway. See kernel/swtch.S for the full argument.

Each process has one (p->context) and each CPU has one for its scheduler thread (c->context).

Line 3

Return address: where the thread resumes when swtch executes ret. For a new process, allocproc sets it to forkret.

Line 4

Stack pointer. Points into the process’s kernel stack, or into the CPU’s boot stack for a scheduler context.

Lines 21–27

struct cpu: per-CPU state

One per hart, in cpus, indexed by the hart ID that cpuid reads from tp. mycpu returns the current one.

None of these fields has a lock, and none needs one: each CPU only ever touches its own entry, and always with interrupts off, so nothing else can run on that CPU in the middle of an update.

proc: the process running on this CPU, or 0 while the scheduler itself runs. Set and cleared by scheduler; read through myproc.
context: the scheduler thread’s saved registers. sched switches to it.
noff, intena: the nesting depth of push_off and the interrupt state before the outermost one (interrupts and spinlocks (push_off / pop_off)).

In the build, sizeof(struct cpu) is 128 bytes: mycpu computes cpus + (id << 7).

Line 23

The current process on this CPU, or null when the scheduler is running. myproc returns it.

Line 24

The scheduler thread’s saved registers. sched does swtch(&p->context, &mycpu()->context) to return to scheduler.

Line 25

How many push_off calls are not yet matched by pop_off; normally the number of spinlocks this CPU holds.

Line 26

1 if interrupts were enabled before the outermost push_off. pop_off uses it to decide whether to turn them back on; sched saves and restores it.

Line 29

The CPU array

Declares the array defined in kernel/proc.c:9, so that other files can see it. NCPU is 8, the most harts xv6 supports.

Lines 31–39

What the trapframe is for

When a user program traps into the kernel (a system call, an interrupt, a fault), uservec in kernel/trampoline.S must save all 31 user registers before it can run any C code, and it needs a few kernel values to get into the kernel at all. The trapframe holds both. Each process has its own trapframe page, allocated in allocproc; it is mapped at TRAPFRAME, just below the trampoline page page, in every user page table (proc_pagetable).

The comment is accurate for this version: uservec saves the user registers and loads kernel_sp, kernel_hartid and kernel_satp, then jumps to the address in kernel_trap (usertrap). On the way out, prepare_return fills in the kernel_* fields and userret restores the user registers. The kernel reaches the same page through p->trapframe, a physical address, which works because the kernel maps RAM at equal virtual and physical addresses.

Lines 40–45

Values the trap entry code needs

The first five slots are not user registers; they are filled in by the kernel for uservec's benefit:

kernel_satp: the kernel page table, to load into satp;
kernel_sp: the top of this process’s kernel stack;
kernel_trap: the address of usertrap;
epc: the user program counter. usertrap copies sepc here, and prepare_return copies it back before sret. It is kept here and not only in sepc because sepc would be overwritten by the next trap taken in the kernel, or by another process if this one is switched out.
kernel_hartid: the hart ID, reloaded into tp because user code may have changed tp.

The /* 0 */, /* 8 */ comments are the byte offsets that kernel/trampoline.S hard-codes; changing the order here would break it.

Line 41

The kernel’s satp value. Written by prepare_return before every return to user space.

Line 42

Top of this process’s kernel stack, p->kstack + PGSIZE. uservec loads it into sp.

Line 43

The address of usertrap, so that uservec can jump to it.

Line 44

Saved user program counter. On a system call usertrap adds 4 so the program continues after the ecall.

Line 45

The hart ID; uservec restores it into tp so cpuid works in the kernel.

Lines 46–77

The saved user registers

All 31 general-purpose registers except zero, in register-number order (ra is x1, sp x2, …, t6 x31), at offsets 40 to 280. The whole struct is 288 bytes, far less than its 4096-byte page.

The kernel reads and writes these slots to talk to the user program: a system call’s arguments come from a0–a5 and its number from a7 (system call arguments); its return value is written to a0. kfork copies the whole trapframe to the child and then sets the child’s a0 to 0; kexec sets sp, epc and a1 for the new program.

Line 79

The process states

The process state machine, in the order the enum numbers them (0 to 5):

UNUSED: a free slot. Static storage starts zeroed, and UNUSED is 0, but procinit sets it explicitly anyway.
USED: claimed by allocproc and being filled in; not yet allowed to run.
SLEEPING: waiting in sleep for a wakeup.
RUNNABLE: ready; any CPU’s scheduler may pick it.
RUNNING: currently executing on some CPU.
ZOMBIE: has exited; waits for its parent’s kwait (see zombie).

Line 79

The six process states. UNUSED is 0, so a zeroed struct proc is a free slot.

Lines 81–83

struct proc, and its lock

One slot of the process table proc (NPROC = 64 slots). The build has sizeof(struct proc) = 360 bytes.

lock is a spinlock that protects the fields on lines 86–90, and it does a second job: it is held across every context switch of this process. The scheduler acquires it before switching to the process, and the process holds it when it switches back (see scheduler, sched and yield). That keeps another CPU from picking the process while its registers are still being saved.

Line 83

The per-process spinlock, named "proc" by procinit.

Lines 85–90

Fields protected by p->lock

These fields are read or written by other processes and other CPUs: the scheduler looks at state, wakeup at chan, kkill writes killed, the parent reads xstate and pid. So every access normally holds p->lock.

The comment is true for every write. A few reads skip the lock, safely:

A process reads its own pid without the lock (sys_getpid, acquiresleep). pid changes only in allocproc (before the process first runs) and freeproc (after it has exited for good), so it cannot change under a running process.
procdump reads state and pid with no lock at all, on purpose (it is a debugging aid that must work even when locks are stuck).

Line 86

Current process state. The scheduler reads it on every pass.

Line 87

The wait channel: non-zero after sleep_prepare until a wakeup on the same address clears it. Can be left non-zero after the process stops waiting (see sleep); that is harmless.

Line 88

Set by kkill or setkilled. Read with killed; the process exits next time it passes through usertrap.

Line 89

The exit status passed to kexit, kept until the parent’s kwait copies it out.

Line 90

The PID (process ID); 0 for a free slot.

Lines 92–93

The parent pointer, protected by wait_lock

parent is protected by the global wait_lock, not by p->lock. Every write holds it: kfork sets the child’s parent, reparent hands orphans to init, and kwait clears it. Every read does too: kwait scans for its children and kexit reads p->parent to wake it.

Why a separate lock? A parent’s kwait has to examine many children’s parent fields and sleep without missing the moment one of them exits; one lock covering all parent links makes that check-then-sleep atomic. kernel/proc.c:23 explains the lock order this implies.

Line 93

The process that created this one with fork (or init, after reparent). Protected by wait_lock.

Lines 95–104

Fields private to the process

These are used by the process itself, so it needs no lock to touch them. The comment is right, with the understanding that “private” also allows two other parties at times when the process cannot be running:

kfork fills in a new child’s fields while it is still USED (not yet runnable).
The parent’s kwait calls freeproc on a ZOMBIE child, which frees trapframe and pagetable and resets sz and name. The child will never run again.
procdump reads name with no lock (debug output only).

context is special: it is written by swtch when the process is switched out, and that always happens with p->lock held.

Line 96

Virtual address of the lowest byte of this process’s kernel stack, KSTACK(i) for slot i. Set once by procinit and never changed.

Line 97

Size of the user address space in bytes: user memory is [0, sz). With lazy sbrk, not every page below sz is necessarily allocated yet.

Line 98

The user page table, built by proc_pagetable and replaced by kexec.

Line 99

Kernel pointer to this process’s trapframe page (a physical address, usable directly because of the kernel’s direct map).

Line 100

Saved kernel registers while the process is not running; see struct context above.

Line 101

Open files, indexed by file descriptor number; 0 means the descriptor is not in use. NOFILE is 16.

Line 102

The current working directory, an in-memory inode reference.

Line 103

Program name for procdump: the last path element given to kexec, at most 15 characters plus the terminating 0.