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

01 – From power-on to /bin/sh

Try it: make run and watch the serial output in the terminal; make debug + make gdb and break kmain to step through it.

1. Firmware and Limine

The firmware (BIOS or UEFI/OVMF) starts Limine from the ISO that run-qemu.sh builds. Limine reads limine.conf, loads the kernel ELF to the higher half (0xffffffff80000000, see linker.ld), switches to 64-bit long mode with paging on, and fills in the answers to our requests – static structs in boot.rs such as BASE_REVISION (memory map, framebuffer, HHDM offset, RSDP). Then it jumps to kmain.

At this point interrupts are off, we run on Limine's stack and Limine's page tables.

2. kernel::init – one subsystem after another

init brings the machine up in an order where each step only needs the ones before it:

  1. serial::init – COM1, so that everything after it can print.
  2. The Limine protocol check (BASE_REVISION) before any response is read.
  3. gdt::init – our own segments and the TSS (with the double fault stack), fpu::init, enable_protection (SMEP/SMAP), interrupts::init – the IDT with all exception handlers.
  4. mem::init – frame allocator from the memory map (pmm.rs), our page table code (paging.rs), the kernel heap (heap.rs). From here on alloc (Vec, Box, …) works.
  5. syscall::init – the MSRs for syscall/sysret.
  6. irq::init – ACPI tables, local APIC timer, I/O APIC routing for keyboard and COM1.
  7. console::init – text on the framebuffer.
  8. task::init – the scheduler; the code running now becomes thread 0.
  9. init_storage – PCI scan, AHCI disk; mount_root – FAT32.
  10. enable_interrupts – from now on the timer preempts threads.
  11. smp::init – wakes the other cores (INIT/SIPI, trampoline); they join the scheduler.
  12. net::init – e1000, DHCP.

3. Our own stack, then give memory back

Back in kmain, the kernel allocates a stack with a guard page (alloc_stack) and switches to it (switch_stack) – Limine's stack has no guard page, an overflow there would silently corrupt memory. On the new stack, kernel_main calls reclaim_bootloader_memory: page tables that still live in bootloader memory are copied, every CPU switches to the copy, and the old regions go back to the frame allocator (≈ 13 MiB).

4. The first process

run_init reads /bin/sh from the disk and calls spawn_with:

  • elf::parse checks the ELF header and collects the loadable segments;
  • AddressSpace::new creates a page table whose upper half is the kernel's;
  • elf::load maps each segment with the right permissions (code not writable, data not executable);
  • 4 stack pages below USER_STACK_TOP are mapped, the argument block is copied to the top;
  • spawn_user creates a kernel thread that will leave for ring 3, and the Process entry (files, cwd, environment, heap) is added to the table.

run_init then waits for the shell to end – if it ever does, the kernel shell (Shell) takes over.

5. Into ring 3

The scheduler picks the new thread. It starts in thread_start, which sees the user_entry and calls enter_user. The assembly enter_user_mode pushes a fake interrupt frame (user SS, RSP, RFLAGS with IF, user CS, RIP), clears every register so no kernel value leaks, and executes iretq – the CPU is now in ring 3 at the ELF entry point.

That entry point is _start in ulib: it aligns the stack and calls the program's main (declared with entry!). The shell prints its prompt with a write syscall – the first time a user program asks the kernel for something.

Things to try

  • make debug, make gdb, break kernel::process::spawn_with, continue: inspect the ELF segments being mapped.
  • mv /bin/sh /bin/sh.off; exit in the running system: run_init returns and the kernel shell starts (kernel:/>); after a reboot, run_init cannot find /bin/sh at all. mv /bin/sh.off /bin/sh in the kernel shell puts it back.