Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 run boots the kernel in a QEMU window and make test boots 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

#ChapterYou end up with
1Booting with Liminea kernel that boots and prints to the serial port
2Testing without an operating systemmake test running unit tests inside the kernel
3Text on the screena framebuffer console with its own font renderer
4GDT and TSSour own segments and a safe stack for double faults
5Interrupts and exceptionsexception handlers – a page fault reports itself, a double fault survives a broken stack
6Hardware interrupts and the timerthe PIC moved to vector 32, a 100 Hz timer, sleep_ms that waits in hlt
7The keyboardkeys from the PS/2 keyboard on the screen – IRQ 1, a ring buffer, a scancode decoder; the end of part I
8Physical memoryLimine's memory map and a bitmap frame allocator, reached through the higher-half direct map
9Pagingtranslate, map and unmap on the live page tables, and kernel stacks whose overflow hits a guard page
10The heapa free-list allocator behind #[global_allocator] on pages mapped with map – Box, Vec and String in the kernel; the end of part II
11A first shella prompt, a line editor, words with quotes and a table of commands – the kernel answers what you type; part III
12ACPI and the APICthe 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
13Threads and a schedulerkernel threads with their own stacks, a context switch in assembly, preemption by the APIC timer, and waiting that blocks instead of spinning
14The other CPUsthe 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
15One scheduler for all CPUsevery 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
16PCI and a SATA diskevery PCI device listed at boot, and an AHCI driver that reads sectors from a SATA disk by DMA; part V
17Reading FAT32files and directories from a FAT32 volume made by mkfs.fat and mtools: cluster chains, long names, ls and cat
18Writing FAT32new files, appended data, directories and removal, written in a safe order – fsck.fat finds nothing, mtools reads what the kernel wrote
19A block cache, and the disk's interrupta 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
20Ring 3 and the first system callcode 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.