# 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.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](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](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](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. **[halting.md](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.

Cutting across all of these:

- **[arch.md](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.

## How the pieces relate

The boot flow ties them together: UEFI runs the loader ([efi.md](efi.md)), which
queries the **GOP** to pick a graphics mode ([gop.md](gop.md)), hands the kernel a
**framebuffer** to draw into ([framebuffer.md](framebuffer.md)) and a **memory
map** of physical RAM ([memory-map.md](memory-map.md)); the kernel runs — its
CPU-specific bits behind the [arch](arch.md) boundary — and when it has finished,
or panics, it **halts** ([halting.md](halting.md)).

## Source map

| Area | Code |
|------|------|
| Bootloader (UEFI app) | `src/efi.zig` → `BOOTX64.efi` |
| Kernel entry, panic, memory-map read-out | `src/main.zig` |
| Shared loader↔kernel contract (`BootInfo`, `Framebuffer`, `MemoryMap`, ABI) | `src/root.zig` |
| Framebuffer text console | `src/console.zig` |
| Arch-specific kernel code (`halt`, linker script) | `src/arch/x86_64/` |
| Build + `run-efi` (QEMU/OVMF) | `build.zig` |