Extending YAK
Recipes for the four most common changes. Each one ends with the tests that prove it works – a change without a test
is not finished. Run make check before every commit.
Add a system call
Example in the tree: uname (syscall 52), added by following exactly these steps.
- Number – in
syscall.rs, modulenr: add a doc comment with the signature and the result, and the next free number. Never reuse or renumber: user programs on existing disks use the numbers. - Dispatch – one arm in
dispatch:nr::UNAME => sys_uname(a0, a1),. The arguments arrive asa0…a4(RDI, RSI, RDX, R10, R8). - Implementation – a
fn sys_<name>(…) -> SysResultnext to its relatives. The rules every syscall follows:- Never dereference a user pointer. Use
copy_from_user,copy_to_user,copy_struct_to_user,user_path. They check the range against the page tables and copy under the process lock (bugs #12, #14). An unchecked access is a kernel crash waiting for the wrong argument. - Errors are negative
errnovalues (Err(errno::EFAULT)); add a new code to moduleerrnoand to the messages ofimpl Display for Errorinfs.rsif you need one. - Check first, then change state. A call that fails should leave nothing half-done (bug #13).
- Bound every loop by something the kernel owns, never by a user-supplied length alone (bug #11).
- Blocking calls wait with
wait_forand give up whensignal_pendingis true (EINTR), so Ctrl+C andkillstill work. - Do not hold the process table lock (
with_current) while blocking or doing disk I/O.
- Never dereference a user pointer. Use
- User side – in
sys.rs: the same number aspub const, bumpSYSCALL_COUNT, and a safe wrapper (pub fn uname(buf: &mut [u8]) -> i64). Higher-level helpers belong in the otherulibmodules (fs,process, …). - Robustness test – add the call to
syscheck: its bad-pointer loop (every pointer argument × every bad pointer and length must return an error) and, if it never blocks, the random phase listRANDOM_OK.SYSCALL_COUNTmoves the "unknown number" checks automatically. - Functional test – call it from a program (step 2 of "Add a user program") and check the output in the integration test, or write checks into a self-test program.
- Document – a row in the syscall table in
docs/DESIGN.md.
Add a user program
- Create
user/src/bin/<name>.rs(oruser/src/bin/<name>/main.rsfor several files), starting likeuname.rs:#![no_std] #![no_main] use ulib::println; ulib::entry!(main); fn main(args: ulib::Args) -> i32 { println!("hi"); 0 }extern crate alloc;if you needVec/String(the heap is ready beforemain). The first line is a//!comment with a usage line –helpand readers rely on it. - Nothing to register: the Makefile finds every program (
USER_PROGRAMS),make userbuilds it, and every disk image gets it in/bin(scripts/mkdisk.sh,scripts/install-user.sh). Type its name in the shell. - Test it: a
run("<name>", "args")with assertions inuserspace.rs, and an E2E step ine2e-shell.pyif it matters at the shell prompt.
Add a test
| Kind | Where | Runs | Use it for |
|---|---|---|---|
| unit test | #[test_case] fn …() in a #[cfg(test)] mod tests of the module | cargo test --lib inside the kernel | functions and subsystems with the real hardware of QEMU |
| integration test | new file kernel/tests/<name>.rs (copy page_fault.rs for an own kmain), plus [[test]] name = "<name>" harness = false in kernel/Cargo.toml if it must fault or exit itself | its own kernel image | boot-time behaviour, faults, memory reclaim, real programs |
| user self-test | a program like pipetest.rs: print FAIL: … per failed check, exit code = number of failures | from the integration test and E2E | syscalls from user space |
| E2E step | a tuple (keys, expected, forbidden) in STEPS of e2e-shell.py | make e2e, make e2e-uefi | what a user types and sees |
All of them run headless with a 30 s timeout per kernel (KERNEL_TEST_TIMEOUT). A test that needs more than one CPU
should return early when smp::online_count() is 1, so KERNEL_SMP=1 make test stays green. Timing assertions need
a generous margin – the suite also runs under make stress on a loaded machine.
For a bug fix: write the test first, watch it fail on the old code, then fix (see docs/BUGS.md – every entry names its test).
Add a shell built-in
Built-ins are commands that must run inside the shell process (they change its state: cd, export, exit).
Everything else should be a program.
- Add
(name, usage, help)toBUILTINSinmain.rs–helpand tab completion use it. - Add an arm to the
matchinrun_stage(next to"pwd"); returnStage::Done(exit_code). - Test it in the scripted
shsessions ofuserspace.rs(injected serial input) or with an E2E step.
Write a course chapter
Chapter NN consists of the folder course/NN-slug/ and the page docs/course/NN-slug.md (listed in
docs/SUMMARY.md, in the table of docs/course/README.md and in the chapter list of the issue
form .github/ISSUE_TEMPLATE/course-stuck.yml).
- Start from the previous chapter: copy
course/(NN-1)-*/tocourse/NN-slug/and add the chapter's code. The folder must stay a complete project:Makefilewithrunandtest, a copy ofrust-toolchain.toml. make testproves the chapter's promise – it boots the kernel headless and checks its serial output (later chapters: the in-kernel test runner). A chapter without a test that fails when the new code is missing is not done.- Write the page: goal · background · the code step by step · run it · what the test checks · what can go wrong
(from
docs/BUGS.mdwhere the reference kernel hit the same problem) · experiments. Under Code: the page names the command that shows the chapter's changes:diff -ru course/(NN-1)-slug course/NN-slug. Every change a learner has to make appears on the page – including the lines that wire new code intokmain. - Code shown on the page is real code: a block written as
```rust,file=kernel/src/serial.rsmust appear line for line in that file of the chapter folder;scripts/check-course.py(inmake docs-check) fails otherwise – as it does when a chapter is missing fromSUMMARY.md, the course table or the issue form, or the page lacks itsdiffline. Blocks withoutfile=are free (output, shell commands, sketches). make coursebuilds and tests every chapter; CI runs it on every pull request.
Rules: one concept per chapter; no code the learner has not seen explained; no claim without a test or a recorded run; numbers and outputs on the page come from a real run.
When something goes wrong
docs/BUGS.md– most symptoms have happened before.make addr2line ADDR=…for a RIP from a panic;make debug+make gdbfor stepping.- Triple fault / reboot loop:
-d int,cpu_reset -D log.txton thescripts/run-qemu.shcommand line. - Interrupts not arriving:
python3 -I scripts/qemu-monitor.py <elf> 5 -- "info pic" "info lapic".