danos/docs/README.md

danos documentation

Notes on how danos boots and draws, written to explain the why behind the code rather than restate it. Roughly in the order things happen at runtime:

1. efi.md — EFI / the boot process. How UEFI firmware finds and runs the bootloader, what the loader gathers before ExitBootServices, how it loads the kernel ELF, and the ABI contract for the jump into the kernel. Start here.
2. gop.md — the Graphics Output Protocol. How UEFI exposes graphics modes (unlike fixed VGA modes), how we detect the monitor's native resolution from EDID and switch to it, and the pixel formats we accept or reject.
3. framebuffer.md — the framebuffer. What the linear framebuffer the loader hands over actually is, and what pitch (stride) means versus width — the detail you have to get right to avoid a skewed image.
4. memory-map.md — the memory map. How the loader learns what physical RAM exists and hands it to the kernel in danos's own neutral format, rather than leaking UEFI's memory descriptors across the boundary.
5. frame-allocator.md — the physical frame allocator. The bitmap allocator that hands out and reclaims 4 KiB physical frames from that map — the primitive page tables and the heap are built on.
6. interrupts.md — interrupts and exceptions. The GDT, IDT and TSS, the exception stubs, and the handler that reports a CPU fault in red instead of letting it triple-fault into a silent reset.
7. paging.md — the kernel's page tables. Building our own 4-level page tables, identity-mapping the low 4 GiB, and switching CR3 off the firmware's tables onto ours.
8. device-interrupts.md — device interrupts. The Local APIC and its timer — the kernel's first interrupt that is handled and returned from, giving it a heartbeat.
9. heap.md — the kernel heap. A growable free-list allocator built on the VMM, exposed as a std.mem.Allocator so std containers work — dynamic allocation for the kernel.
10. scheduling.md — the scheduler. Fixed-priority preemptive multitasking: kernel threads, the context switch, O(1) priority selection, and blocking (sleep, wait queues) — the leap to a running system.
11. ipc.md — inter-process communication. Bounded blocking message-passing channels, then synchronous call/reply between processes over endpoints — the backbone the microkernel's isolated servers talk over.
12. syscall.md — system calls. How ring 3 asks the kernel for something: the syscall/sysret fast path, the trap frame, and why the table is deliberately tiny.
13. drivers.md — writing a driver. The payoff: a driver is an ordinary ring-3 process that claims a device, maps its registers, and sleeps until its hardware interrupts it. The claim is the capability; irq_ack is the unmask.
14. driver-model.md — buses, classes and host controllers. How real driver stacks factor into three shapes, how families share code, and the proposed ABI for the three primitives still missing (capability passing, DMA + memory barriers, MSI).
15. halting.md — halting. Why a kernel can't just "exit", and how while (true) hlt parks the CPU safely once there's nothing left to do.

Start with the north star:

• vision.md — the vision. danos is a learning-by-doing microkernel: minimal kernel, drivers/services isolated in user space, chosen for resilience (restartable components). Win condition: runs on the author's PC and both Raspberry Pis, ideally with a GUI. Real-time is an option to explore, not a requirement. The why that shapes everything below.
• resilience.md — resilience. A design note (not built yet) on fault isolation + live restart — the reincarnation-server + capability model that makes "if I break it, I can restart it" real. danos's core motivation.

Cutting across all of these:

• arch.md — the architecture split. How CPU-specific code is kept behind a build-time arch module so the generic kernel never names x86_64, leaving room for other systems (e.g. an AArch64 Raspberry Pi) later.
• arm.md — ARM targets. The Raspberry Pi landscape the arch split is aiming at: arm (32-bit, Pi Zero W) vs aarch64 (64-bit, Pi 3-5), UEFI vs device-tree boot, and what each layer needs.
• discovery.md — device discovery. A design note on learning what hardware exists via ACPI (x86) or device tree (ARM) behind one neutral device model — when to build it, and how to keep it architecture-agnostic.
• acpi.md — finding the ACPI tables. The concrete x86 locator chain: how the loader captures the RSDP, hands its physical address across in BootInfo, and how the platform derives the RSDT/XSDT from it and walks the SDTs.
• smp.md — multiple cores. A design/research note on how microkernels (L4, seL4) handle SMP — big kernel lock vs per-CPU vs multikernel — and how the right choice depends on whether danos is chasing real-time or resilience.
• coding-standards.md — coding standards. The naming rule the tree follows: non-acronyms are spelled out in full (message, not msg), files are kebab-case, code follows Zig's case conventions, and the handful of exceptions (POSIX/C ABI names, init/len/ptr, acronyms).
• sysv.md — the calling convention. What "the kernel is SysV" means, and why the loader→kernel boundary has to pin it (the RDI-vs-RCX handoff).
• testing.md — testing. How the kernel is tested by booting it in QEMU and asserting on its serial output — reproducibly, and structured so the same tests run across architectures.
• logging.md — logging. The multi-sink diagnostic log (serial, 0xE9 debugcon, file later) kept separate from the framebuffer display, plus the robustness path: optional framebuffer, POST-code checkpoints, and a persistent panic breadcrumb so the kernel survives — and can be diagnosed — with no output.

How the pieces relate

The boot flow ties them together: UEFI runs the loader (efi.md), which queries the GOP to pick a graphics mode (gop.md), hands the kernel a framebuffer to draw into (framebuffer.md) and a memory map of physical RAM (memory-map.md); the kernel turns that map into a frame allocator (frame-allocator.md), installs its descriptor tables so CPU faults are caught (interrupts.md), builds its own page tables and switches onto them (paging.md), brings up the heap for dynamic allocation (heap.md), starts the scheduler (scheduling.md) and the timer that preempts it (device-interrupts.md) — with tasks blocking, sleeping and passing messages over IPC channels — runs, its CPU-specific bits behind the arch boundary, and when idle, or on a panic, it halts (halting.md).

Above that line the microkernel proper begins: discovery (discovery.md, acpi.md) learns what hardware exists, ring-3 processes ask the kernel for things through the small syscall table, isolated servers reach each other over IPC endpoints (ipc.md), and a driver claims a device, maps its registers, and sleeps until the hardware interrupts it — which is the whole reason for the arrangement (vision.md).

Source map

Area	Code
Boot methods (one per way of booting the kernel)	src/boot/ — efi.zig (UEFI) → BOOTX64.efi
Kernel entry, panic, bring-up	src/kernel/main.zig
Shared loader↔kernel contract (BootInfo, Framebuffer, MemoryMap, Syscall, ABI)	src/root.zig
Physical frame allocator	src/kernel/pmm.zig
Kernel heap (std.mem.Allocator)	src/kernel/heap.zig
Scheduler (fixed-priority preemptive; blocking, wait queues)	src/kernel/scheduler.zig
Big kernel lock + interrupt-safe critical sections	src/kernel/sync.zig
IPC channels between kernel threads (message passing)	src/kernel/ipc.zig
IPC endpoints: cross-address-space call/reply, handles, notifications	src/kernel/ipc-synchronous.zig
User processes: ELF loading, address spaces, the syscall table	src/kernel/process.zig
Device tree + claim capability + device_register containment	src/kernel/device-service.zig
IRQ-as-IPC: routing a device interrupt to a driver's endpoint	src/kernel/irq.zig
Hardware discovery (ACPI/device tree) behind one neutral device model	src/device/
Framebuffer text console (mirrors to serial)	src/kernel/console.zig
In-kernel test cases	src/kernel/tests.zig
Arch-specific kernel code (halt, GDT/IDT/TSS, exception + interrupt stubs, page tables, APIC/IO-APIC/timer, serial, linker script)	src/kernel/arch/x86_64/
User runtime library (rt): syscalls, heap, stdio, IPC, device access	lib/
User-space programs shipped in the initrd (init, vfs, hpetd leaf driver, busd bus driver)	sbin/
Build + run-x86-64 (QEMU/OVMF)	build.zig
QEMU integration test harness	test/qemu_test.py