The course: build a kernel, chapter by chapter
In this course you write an x86-64 kernel in Rust from nothing, the same way YAK was built: one small, working step at a time. Every chapter ends with a kernel that boots in QEMU and passes its own tests.
How it works
- Each chapter has a page here (what we build, why, the code with explanations) and a folder in the
repository,
course/:course/01-boot/,course/02-tests/, … Each folder is a complete project – the state of the kernel at the end of that chapter. - Follow along: start with an empty directory and type the code from the chapter pages. When you are stuck, compare with the chapter's folder.
- Or jump in anywhere: copy a chapter folder and continue from there. Every folder builds on its own.
- In every folder,
make runboots the kernel in a QEMU window andmake testboots it headless and checks its output – the same check the project's CI runs on every chapter. - The finished kernel of the project (the "reference kernel") is much bigger than the course so far; the walkthroughs explain it as it is today.
What you need
- The host tools from the quick start (QEMU, xorriso, make, gcc, git, python3; from
chapter 17 on also dosfstools and mtools, which make the test disks) and Rust via rustup. Each chapter folder contains a
rust-toolchain.toml; rustup installs the exact compiler version. - Some Rust: ownership,
struct/impl, traits, modules. No previous kernel or assembly knowledge – the chapters explain what the hardware expects.
Chapters
| # | Chapter | You end up with |
|---|---|---|
| 1 | Booting with Limine | a kernel that boots and prints to the serial port |
| 2 | Testing without an operating system | make test running unit tests inside the kernel |
| 3 | Text on the screen | a framebuffer console with its own font renderer |
| 4 | GDT and TSS | our own segments and a safe stack for double faults |
| 5 | Interrupts and exceptions | exception handlers – a page fault reports itself, a double fault survives a broken stack |
| 6 | Hardware interrupts and the timer | the PIC moved to vector 32, a 100 Hz timer, sleep_ms that waits in hlt |
| 7 | The keyboard | keys from the PS/2 keyboard on the screen – IRQ 1, a ring buffer, a scancode decoder; the end of part I |
| 8 | Physical memory | Limine's memory map and a bitmap frame allocator, reached through the higher-half direct map |
| 9 | Paging | translate, map and unmap on the live page tables, and kernel stacks whose overflow hits a guard page |
| 10 | The heap | a free-list allocator behind #[global_allocator] on pages mapped with map – Box, Vec and String in the kernel; the end of part II |
| 11 | A first shell | a prompt, a line editor, words with quotes and a table of commands – the kernel answers what you type; part III |
| 12 | ACPI and the APIC | the MADT read from the ACPI tables, the I/O APIC routing timer and keyboard, and the local APIC timer measured against the PIT; part IV |
| 13 | Threads and a scheduler | kernel threads with their own stacks, a context switch in assembly, preemption by the APIC timer, and waiting that blocks instead of spinning |
| 14 | The other CPUs | the other cores started through a real-mode trampoline (INIT/STARTUP IPIs), each with its own GDT, TSS and stack, running jobs sent with run_on |
| 15 | One scheduler for all CPUs | every CPU runs threads from one queue: a timer and an idle thread per CPU, the scheduler lock held through the switch, waiting that cannot lose a wake-up; the end of part IV |
| 16 | PCI and a SATA disk | every PCI device listed at boot, and an AHCI driver that reads sectors from a SATA disk by DMA; part V |
| 17 | Reading FAT32 | files and directories from a FAT32 volume made by mkfs.fat and mtools: cluster chains, long names, ls and cat |
| 18 | Writing FAT32 | new files, appended data, directories and removal, written in a safe order – fsck.fat finds nothing, mtools reads what the kernel wrote |
| 19 | A block cache, and the disk's interrupt | a write-through sector cache (394 disk commands for a file become 196, then 0) and MSI from the SATA controller, so disk commands sleep in wait_for; the end of part V |
| 20 | Ring 3 and the first system call | code in ring 3 that can only compute and ask: user segments, RSP0 per thread, USER pages, iretq, int 0x80 with write and exit, faults that end the program, not the kernel; part VI |
For now the course ends with chapter 20 (my decision of 2026-11-06; the plan for chapters 21–36 is in
docs/ROADMAP.md). The pilot (chapters 1–4) gets a round of feedback from readers, and the chapters
after it change with what they report. If you get stuck, use the issue form
I got stuck in a course chapter;
if something was unclear even though it worked, use
Feedback on the course.
That is exactly the feedback the pilot is for – CONTRIBUTING.md says more.