# AGENTS.md — NebOS (`nebos`) A from-scratch, freestanding **32-bit x86 hobby operating system** written in C and x86 assembly. Single-author project (~7,000 SLOC, no external runtime; the kernel has no libc, while ring-3 commands may link the in-tree `libc.a`). Targets i586 (first-gen Pentium); runs under QEMU or on real hardware. ## Documentation site (`docs/`) `docs/` is the static architecture site: hand-written HTML5, one shared `style.css` and a small hand-written SVG favicon, with no JavaScript, no build step and no external fonts or CDNs. Open `docs/index.html` directly (`file://` works) or serve it with `python3 -m http.server -d docs`. Keep the site in the same change as the code. Architecture changes belong in this file **and** the matching page: | Page | Covers | |------|--------| | `docs/index.html` | Overview, layer diagram, at-a-glance numbers, subsystem map | | `docs/boot.html` | BIOS/VESA, MBR, UEFI loader, kexec, boot info, image layout | | `docs/memory.html` | Address map, E820/bitmap allocator, paging, MTRR, user arenas | | `docs/cpu.html` | GDT/TSS, interrupts, ACPI/SMP, CFS-lite, BKL, idle/power | | `docs/drivers.html` | PCI, FDC/PATA/AHCI, USB core + UHCI/OHCI/EHCI/xHCI, HID, sensors | | `docs/filesystems.html` | VFS/`fs_ops`, FAT, ramfs pack, `/share`, WebDAV | | `docs/graphics.html` | VBE/shadow, damage, blit, WM, canvas ABI, ngui, images | | `docs/network.html` | netdev, ARP/ICMP/UDP/DHCP/DNS, TCP, TLS, netconsole/netkexec | | `docs/userland.html` | Ring-3 model, ELF spawn, syscalls, shell/PATH, pack, apps | | `docs/development.html` | Toolchain, make targets, hot reload, tests, debugging | Rules: - A change to a boot path, hardcoded address, scheduler/ABI, driver model, file service, graphics/WM path, protocol, syscall number, build target or reload workflow must update the corresponding page in the same change. A new subsystem needs a section on an existing page (or a new page linked from the index) and a card on `docs/index.html`. - Update `AGENTS.md` whenever the architecture or a documented invariant changes; `AGENTS.md` and `docs/` are both source-of-truth maps and must not drift. Each page's "Source map" lists the files it documents; keep it current. - Charts and diagrams are hand-written HTML/CSS or inline SVG. No JavaScript, CDN, generated asset or build step. Every charted number must come from a source constant/table; cite the defining file in the caption or source map. - Keep internal links working, the active nav item correct, the layout usable from a phone width to a wide desktop, and the site readable from `file://`. - Keep version strings in the page heads and footers in sync with `OS_NAME`/`OS_VERSION` in `version.h`. ## Build & run Toolchain: `gcc` (32-bit multilib), `as`/`ld`/`objcopy`, `mtools` (`mcopy`/`mkfs.fat`), `qemu`. ```sh make all # floppy.img usb.img final.bin root.img make run # boot floppy.img + root.img in QEMU (fallback: qemu-system-x86_64) make run-smp # same with -smp 4 (BSP + 3 APs, the Atom 330 topology) make run-usb # boot usb.img as an IDE disk make run-uhci # like `make run` but with a UHCI controller + USB mouse make run-ehci # EHCI + UHCI companion: high-speed storage on EHCI, HID on UHCI make run-ehci-asix # pass through a real ASIX AX88772 dongle on EHCI make run-net # like `make run` + a PCI NE2000 NIC on QEMU's user network (slirp; DHCP/DNS/NAT) make run-ahci # like `make run` + an ICH9 AHCI controller and a 512 MB SATA disk (sata0) make uefi # build BOOTX64.EFI and the dual-boot usb-efi.img make run-uefi # boot usb-efi.img under OVMF (x86-64 UEFI; serial log in /tmp/opencode) make test-uefi # headless OVMF boot test (greps the serial log for the boot line) make rootfs # build cmds.img (the 8 MB rootfs partition image) make nowm # diagnostic kernel with no WM; the boot console stays visible make dev # serial kernel + rootfs reload (KXE2) make kernel-dev # serial kernel-only reload (keeps the running rootfs) make net-dev # network kernel + rootfs reload (KXN2) make kernel-net-dev make flash # write the dual-boot image (legacy BIOS + UEFI) to a USB stick make test-usb # headless USB mouse/keyboard regression tests (QEMU + python3) make test-images # host image-decoder + blit tests (ASan variant: test-images-asan) make test-libc # host stress test for the ring-3 malloc make clean ``` - Build flags (in `Makefile`): `-m32 -march=i586 -ffreestanding -fno-pie -nostdlib -fno-stack-protector -mno-sse -mno-sse2 -mno-mmx -O2`. - The command pack is the system rootfs: `cmds.pack` (NBPAK1), gzip-compressed to `cmds_pack_gz.bin`, wrapped by `mkrootfs` with a one-sector `NBROOT1` header into `rootfs.bin` (floppy append) and `cmds.img` (the 8 MB USB partition image). The kernel itself no longer carries the pack; the boot path loads it into RAM and `ramfs_init` takes a private copy (`bin/` mounted at `/ramfs`). - `root.img` is a second FAT12 floppy holding the disk fallback copies of the browser/gallery (`BROWSER`, `GALLERY`) and its `DEMO.HTM`/`PIC.BMP` test page, plus a few test files; it requires `mtools` to build. - UEFI needs `x86_64-w64-mingw32-gcc` (the 64-bit loader) and, for the QEMU targets, an OVMF firmware (`OVMF=/path/to/OVMF.4m.fd` overrides the default). `make all` does not build the UEFI image, so a machine without mingw still builds the legacy floppy/USB images normally. - `usb.img` is 9 MB: partition 1 (type `0x06`, LBA 63, 1024 sectors) is the boot sector + kernel and partition 2 (type `0x7F`, LBA 1088) is the 8 MB rootfs image (`cmds.img`), 512 KB behind the boot sector. The header and the 242 KB gzip pack therefore still live in the first 1.44 MB, which even a CHS-only USB BIOS can read. The boot sector's `pack_lba` field points the VESA stage at partition 2. `usb-efi.img` (17 MB) adds an 8 MB FAT16 ESP as partition 3 (type `0xEF`, LBA 18432); `BOOTX64.EFI` embeds the kernel + gz pack. `make flash` writes the dual image; `make flash FLASH_IMG=usb.img` writes the legacy-only image. One BPB byte is cleared in the dual image (disk offset `0x7E16`, FATSize16): without that, UEFI firmware scans partition 1, sees the FAT16-looking boot sector and mounts the raw kernel blob as a volume, writing FAT/root pages over the kernel at LBA 64. `boot.S` and the BIOS never read FATSize16. `make flash` needs the mingw toolchain because it builds `usb-efi.img`. ## Boot chain 1. `boot.S` — 512-byte boot sector (FAT16 BPB). Loads contiguous kernel sectors to `0x7E00` (CHS for floppy, INT 13h AH=42h LBA for hard disk), jumps there. 2. `vesa_stage.S` — real-mode VESA stage. Probes INT 15h E820 into `0x1000`, reads the `NBROOT1` rootfs header at the boot sector's `pack_lba` field and stages the gzip pack in the low gap at `0x60000..0x9FBFF` (16 KB staging chunks at `0x3000`, `rep movsb`; no protected-mode BIOS call), picks the best VBE mode (≥16 bpp, LFB, fits VRAM, ≤1280px), writes mode info to `0x600` and the 12-dword `struct boot_info` (magic/checksum/rsdp/flags/pack range) to `0x500`, enables A20, enters protected mode, copies the pack to `PACK_HIGH_ADDR` (`0x900000`, above the VGA-shadow reserve) and rewrites the boot-info pack address before jumping to `kernel_entry` (`entry.S`, re-points ESP to the current stack top, then `kernel_main`). The copy lets the kernel image's BSS/boot stack extend past `0x60000`. The stage prints `Loading rootfs [d= lba= e=<0|1> m=]...`, then a dot after the header and one per 16 KB chunk, so a BIOS hang is localised. Drives below 0x80 use CHS (the same path the boot sector's kernel load used); fixed disks use EDD LBA. 3. `kernel.c` — `kernel_main` zeroes BSS then inits serial → memory/paging → ACPI/MADT → I/O → power → idle → processes → timer (PIT; 1 kHz busy, 100 Hz idle + IDT) → SMP AP bring-up → mouse → VGA shadow buffer → terminal. 4. `mbr.S` — MBR (USB/HDD boot); loads the active partition's boot sector (partition 1 at LBA 63). 5. **UEFI (`efi/`)** — an x86-64 PE32+ `BOOTX64.EFI` loads from the ESP. It picks a GOP mode, converts `GetMemoryMap` into the E820 map at `0x1000`, stages `kernel.bin` below 4 GB, fills `0x500` (boot info) and `0x600` (framebuffer), calls `ExitBootServices`, copies the embedded gz rootfs to the top of RAM below 128 MB, copies a 192-byte trampoline to `0x800`, leaves IA-32e mode (`CR0.PG`, `EFER.LME`, `CR4.PAE/PGE/PCIDE/SMEP/SMAP/ LA57`), copies the kernel to `0x7E00` and jumps to `kernel_entry`. The BIOS boot sector / VESA stage are not executed on this path; the legacy chain is separate (it loads the same gz pack from the rootfs image). SMP is ACPI-only: RSDP → RSDT/XSDT → MADT, then `LAPIC` + `INIT-SIPI-SIPI`. There is deliberately no Intel MP-table parser. If ACPI, a usable MADT, the CPUID APIC bit or the LAPIC is missing, `cpu_count` stays 1 and the machine boots exactly like before (8259 PIC + PIT, no APIC MSR/MMIO access). This keeps a Pentium 1 (and a Pentium II board without ACPI) on the UP path. ## Hardcoded memory map (fragile — keep in sync when editing) | Address | Purpose | |-----------|---------| | `0x500` | Boot info (`struct boot_info`, `bootinfo.h`, 12 dwords): magic/checksum, ACPI RSDP, EFI/RGBX flags, and the boot-time rootfs pack `addr`/`size`; written by `vesa_stage.S`, the UEFI loader or kexec | | `0x600` | Boot framebuffer info (`struct vga_boot_fb_info`, see `vga.h`; written by `vesa_stage.S` or the UEFI loader) | | `0x7C00` | Boot sector load address; also the UEFI handoff stack top | | `0x7E00` | Kernel load / VESA-stage entry (`kernel.ld`); the UEFI loader copies the kernel here and jumps to `kernel_entry` | | `0x800` | kexec and UEFI handoff trampoline (relocated at runtime; below the kernel) | | `0x900` | kexec/UEFI flat GDT + GDTR (built at runtime; below the kernel) | | `0x1000` | E820 memory map (`struct e820_map`, written by `vesa_stage.S` or the UEFI loader, parsed by `mm.c`); also the kexec trampoline's private stack top (grows down, below the map) | | `0x3000` | UHCI frame list (1024 × 4 B, 4 KB-aligned; `uhci.c`) | | `0x4000` | ISA DMA buffer, one sector (`disk.c`) | | `0x6000` | AP real/protected-mode trampoline (`ap_tramp.S`/`ap_tramp.ld`; SIPI vector 0x06, image ends below `0x6C00`) | | `0x6C00` | AP trampoline real-mode stack top (grows down) | | `0x6F00` | AP startup info block (CR3, stack top, C entry, CPU index) | | `0x60000` | Legacy rootfs pack staging (`vesa_stage.S`; compressed gzip data, up to `PACK_LOW_MAX` 0x3FBFF, ending below the EBDA at `0x9FC00`). Temporary: copied to `0x900000` in protected mode before the kernel starts, so the kernel BSS/boot stack may extend past this address | | `_end` | Kernel end (linker symbol; `kernel.ld` ASSERTs `__bss_start <= 0x60000` so the loaded image stays below the legacy staging gap, and `_end <= 0x90000` so the top of the staging gap and the EBDA stay untouched). BSS and the boot stack may extend past `0x60000` | | (in-image) | Bootstrap/protected-mode stack: 8 KB `.stack` NOLOAD section, `__boot_stack_top`/`__boot_stack_bottom` (travels with the kernel) | | `0x900000`| Legacy boot-time rootfs pack after `vesa_stage.S` relocates it (reserved by `mm_init` until `ramfs_init` takes its copy, then freed; process stacks and kexec staging also start here) | | `0x100000`| VGA shadow buffer (`VGA_SHADOW_BASE`, `vga.h`) | The legacy stage uses `0x3000..0x6FFF` as a 16 KB-chunk rootfs staging buffer before the kernel starts; the UHCI frame list (`0x3000`), ISA DMA buffer (`0x4000`) and AP trampoline (`0x6000`) reinitialize those addresses later. The boot-time rootfs pack placement depends on the boot path: the legacy stage stages it in the low gap `0x60000..0x9FBFF` and copies it to `0x900000` before the kernel starts, the UEFI loader puts it at the top of RAM below 128 MB, and kexec leaves it in the staging buffer (≥ `0x900000`). `mm_init` reserves `[pack_addr, pack_addr+pack_size)` from boot info when it is above the low 1 MB, so the legacy pack is protected from the frame allocator too. `ramfs_init` copies/inflates it into fresh pages and `mm_free_range()` releases the boot region when it is above the VGA shadow reserve. Everything else is dynamic: process stacks and the kexec staging buffer come from the frame allocator (≥ `0x900000`), and the fallback stack pool is a static BSS array. The UEFI loader's kernel staging buffer comes from `AllocatePages` below 4 GB and only lives until the `0x800` trampoline copies it to `0x7E00`. The kernel region itself only has one wall (`_end` below `0x90000`), so adding code no longer moves any address. ## Key files - **Multitasking**: `sched.c/h`, `process.c/h`, `tss.c/h`, `switch.S` — CFS-lite weighted fair scheduling (weight 1..16, 64-bit vruntime, 10 ms slice; WM 16, default/commands/terminals 8, kworker 4), a sorted sleep list and wait queues (no polling scans), stable per-PCB objects in a sparse `PROC_MAX` pointer table, per-CPU `struct cpu`/GDT/TSS with `%gs`-based `this_cpu()`, and a per-CPU `current` (no global `current_pid`). Idle is not a process slot; a normal `kworker` process does the housekeeping and the zombie reaper. `sched_lock` (IRQ-safe spinlock) protects the global run/sleep/wait queues and the process-table state touched by timers; `schedule()` keeps it across the stack switch and `sched_finish_switch()` (called from `switch.S` after loading the new ESP) drops it, so another CPU can never pick a process whose kernel stack this CPU is still unwinding. Excess wake-up races are handled by skipping a queued process that is still marked running on another CPU. The **big kernel lock** (`bkl_*`) is a sleeping recursive mutex: every ring-3 syscall and every kernel thread takes it, voluntary block/sleep points drop it (`sched_yield`), and long serial/network waits release it via `bkl_pause()`/`bkl_resume()`. A BKL holder is not timer-preempted, so it can safely be in the middle of kernel data structures. Kernel threads are pinned to the BSP; user processes may run on any CPU. The idle fallback uses `bkl_trylock()` (never blocks); the kworker and kernel commands take the BKL normally and release it around their sleeps. APs use their LAPIC timer (vector 0x30; 1 ms busy, 10 ms idle); the BSP keeps the 8259 PIC/PIT and is the only global-tick source. APs do not start taking user work until `smp_enable_sched()`, i.e. after device/FS setup. LAPIC IPIs (vector 0x31) request a reschedule; they must be EOIed on the target LAPIC. `SYS_PROCINFO` exposes weight/state/CPU/ticks for the ring-3 `top` command, and `sched`/`renice` plus `SYS_SCHEDINFO` expose the scheduler counters. Ring 0 is preemptible at tick boundaries unless `preempt_count` is set (FAT and the shadow flush) or the BKL is held; voluntary blocks/yields go through the `int 0x81` gate. - **SMP / ACPI**: `acpi.c/h` (RSDP → RSDT/XSDT → MADT; CPU/LAPIC list and LAPIC base; 4 MB table page mapping; malformed tables are ignored), `lapic.c/h` (xAPIC MMIO access, BSP/AP init, INIT/SIPI/IPI, calibrated periodic timer), `smp.c/h` (trampoline copy, AP stacks via `process_init_ap`, INIT-SIPI-SIPI with a second SIPI retry, per-CPU `smp_ap_main`, `smp_stop_aps`, lazy `smp_enable_sched`), `ap_tramp.S` + `ap_tramp.ld` (real → protected-mode trampoline at `0x6000`), and `spinlock.h` (the IRQ-safe spinlocks). `cpu_enable_sse()` runs on every AP: an AP starts with firmware CR4, and the SSE2 drawing fast paths #UD until OSFXSR/OSXMMEXCPT are set. - **Memory**: `mm.c/h` — INT 15h E820 detection (real-mode in `vesa_stage.S`, map at `0x1000`) + a bitmap page-frame allocator (4 KB pages). Reserves low 1 MB and an 8 MB VGA-shadow region. `kmalloc.c/h` — a power-of-two heap allocator on top of the frame allocator (used for PCBs and command context). Process stacks (≥ `0x900000`) come from the frame allocator, with an 8-stack fallback pool (a static BSS array; no fixed address). - **UEFI boot**: `bootinfo.h` (the `0x500` block and its checksum/accessors), `efi/efi.h` (minimal UEFI types and table/protocol layouts), `efi/main.c` (GOP mode choice, `GetMemoryMap` → E820, staging below 4 GB, rootfs copy, boot-info/framebuffer blocks, `ExitBootServices`), `efi/tramp.S` + `efi/tramp.ld` (the `0x800` long-mode exit, kernel copy and jump) and `efi/payload.S` (embeds `kernel.bin`, `cmds_pack_gz.bin` and the trampoline in `BOOTX64.EFI`). The legacy `vesa_stage.S` writes the same v2 boot info (with `pack_addr`/`pack_size`); `vga.c`/`panic.c` honour the RGBX flag and skip the VBE-only ATI CRTC reset / NVIDIA stolen-VRAM alias under EFI; `mouse.c` forces the software cursor; `acpi.c` prefers the passed RSDP and maps its page before validating it. - **Paging**: `paging.c/h` — identity-maps RAM (4 MB pages via CR4.PSE) + the LFB (uncacheable) and enables CR0.PG/WP. Before the switch it clears stale translation controls a BIOS protected-mode call can leave behind (`CR4.PAE/PGE/LA57/PCIDE/SMEP/SMAP` and `EFER.LME`); the X201's legacy stage used to return from `INT 15h AH=87h` with `CR4` set, and the first `CR0.PG` write then triple-faulted. The LFB PDE range is computed from the page index (a base above `0xFF000000` used to wrap `base + 16 MB` and map nothing), and `mm_init` reserves a low LFB range so the boot console cannot overwrite the page directory. Each process gets a page directory cloned from the kernel identity map (kernel stacks are mapped everywhere, so CR3 can switch on the old stack); `paging_current_cr3()` reads CR3. The kexec trampoline (`kexec_tramp.S`) clears CR0.PG before the copy so it can overwrite the old kernel's page tables safely. - **Window manager / window server**: `wm.c/h` is the kernel window server; the only WM is the ring-3 process loaded from `/ramfs/bin/wm` (`ucmd_wm.c`, `uwm_lib.c`). The kernel maps the shadow and each window's RGB565 front canvas at `WM_CONTENT_VA_BASE`, routes input, owns the cursor, kexec detection and the boot-console handoff. Every window is a canvas client; there is no in-kernel WM or terminal fallback. The WM paints the desktop, spawns the first terminal after `wm_server_boot_ready()` (set after the storage mount), and composites the canvases into the shadow. The boot console stays visible until the WM attaches (`wm_server_attach` disables it), so a missing `/ramfs/bin/wm` leaves the kernel boot log on screen and the supervisor retries. `wm_server_present` flushes the damage rects; `wm_server_key_wait/poll` provide keys. The WM keeps a front-to-back order (focused first, then descending slot); every damage rectangle is painted by subtracting the windows in front, so an occluded window is never repainted and the stack is not drawn back-to-front. A focused-window drag copies its shadow block (`usurf_copy`) and repaints only the old strips the new rectangle does not cover. The kernel hit-test uses the same order. `terminal.c` keeps the privileged kernel command registry for the ring-3 terminal (`SYS_SPAWN_KCMD` / `term_kcmd_spawn`), but the kernel terminal entry/shell and the cell-window ABI are gone. - **Window canvas API**: `gfx.c/h` allocates the RGB565 front/back canvases; `sys_wm.c` is the ABI bridge. `SYS_WIN_CREATE` gives a command its window canvas mapped RW at `USER_WIN_BASE` (`0x50000000`). `SYS_WIN_PRESENT` optionally takes a content-relative `struct wm_win_present`; the kernel copies only that rectangle into the front canvas (with interrupts off, so a half-drawn frame can never reach the screen), unions it into `canvas_dmg_*`, and `SYS_WM_INFO` returns the union to the WM. A present with `w`/`h` zero means the whole canvas. The terminal tracks dirty rows and presents only those; `uwm_lib.c` uses row-based RGB565 conversion, `rep stos`/`rep movs` fills and copies, and counts composited pixels in `usurf_pixels`. The WM writes the last two-second interval to `/share/wmstats` (`frames`, `ms`, `max`, `px`) for on-target measurement. `SYS_WIN_INFO`, `SYS_WIN_ACK_RESIZE`, `SYS_WIN_POINTER`, `SYS_WIN_EVENT`, `SYS_WIN_KEY_WAIT` and the generic `SYS_KEY_POLL` handle input. The WM composites the front canvas; presented frames carry monotonic seq counters, so the WM can never lose one. Closing a window kills its owner; the reaper frees the canvas. `clock`, `colors`, `term`, `files` and the other apps are canvas clients. The old `SYS_GFX_BEGIN/PRESENT/END` terminal-takeover service and the kernel text-canvas renderer are removed. Pointer input: `SYS_WIN_POINTER` reports the content-relative position, buttons and focus, and `SYS_WIN_EVENT` queues press/release edges with a capture window, so a click that starts in a window still gets its release after the pointer leaves. The userland `ngui.c/h` immediate-mode toolkit builds on those: clipped RGB565 primitives, buttons, text input, procedural icons and scrolling panes. `files` (`ucmd_files.c`) is its first user; `gallery` (`gallery.c`) is the live showcase of every control and primitive the toolkit exports. Buttons fire on the release edge and keep `active` until `ui->released`: inferring release from the sampled `ui->buttons` races the WM event queue and drops clicks. Text fields support mouse drag-selection, double-click select-all, Ctrl+Left/Right word jumps, Ctrl+Delete/Ctrl+Backspace word deletion and Ctrl+A select-all; typing or Backspace/Delete replaces a selection. At the end of the line Ctrl+Delete removes the word before the caret instead of doing nothing. - **Graphics**: `vga.c/h`, `vga_copy.S`, `blit.c/h`, `gpu.c`, `ati.c`, `nvidia.c`, `nv50.c`, `pci.h` — VESA LFB + shadow buffer. Drawing goes into a `struct surface` render target: `vga_target()` is the screen's shadow buffer unless the running process set an override (`vga_set_target()`, stored in the PCB so a preempted draw can never leak), and the WM's pixel operations go through the `blit` vtable (`blit.c/h`: fill/copy/blend/canvas/present/flip, software only today) so an accelerator can replace single ops without touching the WM. `vga_target_damage()` is a no-op while the target is not the screen. `cpu.c` detects SSE2 (CPUID, with the EFLAGS ID-bit probe and the CR4.OSFXSR/OSXMMEXCPT enable, since the kernel is -mno-sse) and the software fill uses an SSE2 row store when it is there -- streaming (`movntdq`, one sfence per fill) for rows that do not fit the cache, which avoids the read-for-ownership traffic that makes big fills DRAM-bound on the Atom. `gfxbench` times the fill/copy/cell/canvas/flush paths and reports the bytes the presenter really copied (`vga_present_copied`). The flush trims a shared damage list, so `vga_present_shadow()` refuses to re-enter while another process is mid-flush (a full-screen copy is long enough to be preempted). The boot log prints `blit backend: `. Drawing marks damage rectangles (a small list that merges rects when they overlap or touch, so a keystroke's cells collapse while unrelated damage stays apart); the main loop copies them to VRAM on every iteration under a byte budget (`VGA_FLUSH_BUDGET_BYTES`), no fixed frame rate. A rect that fits the budget is copied whole, so a window repaint never tears; only a bigger one (a full-screen redraw) is chunked, and its remaining rows continue after the newer damage. ATI Mach64 CRTC fixup; NVIDIA is VBE-only (never touch the legacy VGA CRTC). On the ION the framebuffer is stolen DRAM and the VBE LFB is a BAR3 window into it; the BIOS leaves a 512 MB uncacheable MTRR over the PCIe apertures, and since the lowest-numbered matching entry wins, the aperture can never be write-combining (~33 MB/s of separate PCIe writes). `nvidia_lfb_in_vram()` therefore locates the framebuffer in the stolen VRAM (marker through the LFB, page-granular scan of a cached mapping) and `vga_shadow_init()` writes through that alias once a WC MTRR covers the stolen range (only then -- a cached framebuffer would stop updating the screen). Everything else keeps the UC LFB: `paging.c` maps LFB pages cacheable only when `mtrr_set_wc()` says it covered them. `vga_fb_lfb_wc()` reports the effective path and `gfxbench` prints it. `nvidia.c` identifies the card, maps BAR0/BAR1/BAR3 and reads the MCP7x stolen-VRAM geometry; `nv50.c` probes the nv50-family display engine at boot (read-only, serial/netmon). The ION/AT3IONT-I hardware cursor is deliberately not driven: the VBIOS keeps the display engine (INTR_1 bit 8, `0x6194e8` = 0x803), EVO DMA channels never fetch until nouveau's full takeover (which re-programs the mode itself), the cursor staging registers are engine-only, and a channel that has run cannot be restarted — see the header of `nv50.c`. - **Text console**: `fbtext.c`, `font_8x8.c/h`, `io.c/h`, `screen.c/h` — 8×8 font, framebuffer glyph blitting (`fbtext_draw_cells`) and the boot-console cell buffer (`screen.c`, used by `io.c`'s fallback screen and `bootcon`). The ring-3 terminal renders its own rows into its canvas; the kernel window manager has no text-cell content path. `screen_damage_*` remains for the boot console's own bookkeeping. - **Shell**: `ucmd_term.c` is the windowed shell (rows, scrollback, Tab, builtins `cd`, `path`, `help`, `clear`). `terminal.c` keeps the privileged kernel command registry and `term_kcmd_spawn()` used through `SYS_SPAWN_KCMD`; commands are files on the terminal PATH (`/ramfs/bin` by default), so a packed command can shadow a kernel one. The in-kernel terminal entry point (`term_entry()`, `term_run()`) is gone. - **Fatal exception screen**: `panic.c/h`, `timer.S` — on a ring-0 fault, dumps vector/error code, GPRs, CRs, EIP instruction bytes and stack return-address candidates straight into the LFB (and COM1) before halting; see the panic section below. - **Filesystem**: `fat.c` (FAT12/16/32 read/write, device-parameterized), `vfs.c` (mounts every FAT device under `/`), `fatdetect.c`/`fatformat.c`, `blkdev.c` (floppy + IDE + SATA registry), `ata.c` (ATA PIO, either the legacy ports or the PCI IDE interface's native BARs — `ata_init_ports()`; multi-sector PIO waits for DRQ before every sector, since drives drop it between sectors, polls the command-block status rather than the alt-status BAR, and falls back to single-sector commands when a bridge leaves DRQ pending after a multi-sector transfer), `disk.c` (FDC + ISA DMA ch2, retries). `vfs.c` exposes an `fs_ops` vtable (FAT and the ramfs implement it) so the file service and the shell never touch `fat_*` directly; `vfs_resolve()` normalizes the path relative to the mount (drops `.` components, collapses and trims slashes) so directory paths from Tab completion ("/ramfs/bin/") work. `sys_fs.c` is the file service for ring-3 commands: whole-file read/write, index-based directory listing, mount listing, unlink/mkdir/rmdir (writes to the ramfs return a read-only error). A FAT operation sets `sys_fs_busy`, which the scheduler honours (no process switch during it): the FAT driver has static state and the floppy still needs its IRQ. So expect a brief system stall (not ticks — the PIT keeps running) while a command reads or writes a disk. Directory listings cache the first 64 entries of the last FAT directory (`fat_cache` in `vfs.c`), so the WebDAV server's index 0..N-1 sequence is one directory walk instead of N; any write/mkdir/rmdir/unlink invalidates it. - **`/share`**: `share.c/h` — writable, page-backed in-memory filesystem for network uploads (the netbooted board may have no writable disk). Entries are full relative paths (like the pack ramfs) plus explicit directory entries, so empty directories work; names are plain strings (up to 63 bytes), file data comes from `mm_alloc_pages()` and is freed on replace/delete. Limits: 64 entries and 16 MB, volatile across reboot/kexec. Mounted at `/share` by `vfs_mount_all()`, so it appears in `ls /` and the `files` GUI. `SYS_FS_STAT` exposes size/dir/read-only, and `sys_dirent` carries a display name (64 bytes) plus `raw_83` so FAT's space-padded fields and the name-string filesystems share one ABI. - **SATA/AHCI**: `ahci.c/h` — polled AHCI driver (first controller only, PCI class `01:06:01`, no IRQs, no NCQ): port bring-up with COMRESET, IDENTIFY (shared `ata_identify_parse()` with `ata.c`) and READ/WRITE DMA EXT through a page-allocated bounce buffer (nothing large in BSS). Disks are registered as `sata0`..`sataN` (named by AHCI port index) and mount like IDE disks (`sata0p1` for an MBR partition). >2 TB disks are clamped to 32-bit LBA; a disk added after boot needs a rescan (no COMRESET hotplug). - **Serial**: `serial.c`, `serial_ring_buf.c/h`, `serial_loop.c` — 16550 UART with an IRQ-driven ring buffer and the `serial test` loopback check. - **Network**: `netdev.c/h` — NIC driver registry (`struct netdev`, first probe wins; drivers: `e1000e.c` Intel e1000/PCH LAN (82540EM emulated, 82577LM/82578/82579; polled, PCI INTx disabled before MMIO, PCH D0 and no BAR sizing so the ME/AMT cannot leave the BAR undecoded; skips the global MAC reset while the link is up, because the PCH/ME wedges on the CTRL_RST access), `r8168.c` RTL8111/8168 (PCIe, polled, C+ mode, 64-entry RX ring), `ne2000.c` RTL8029 (QEMU/ISA) and `asix.c` AX88772 USB Ethernet (bulk over the USB core, so an EHCI/xHCI dongle is usable). `netdev [name]` is a kernel command that shows the active driver or switches it (`netdev asix`, `netdev e1000e`, ...); it calls the selected driver's probe and leaves the current driver untouched on failure. `net.c` — ARP + ICMP echo, IPv4/UDP send + parse helpers, shared ARP resolution (`net_arp_resolve`) and routing (`net_next_hop`), frame decode, `net_checksum()`/`net_checksum_tcp()`. `dhcp.c` — minimal DHCP client (DISCOVER → OFFER → REQUEST → ACK; runs at boot when a NIC is present, 4 s budget, keeps the static address when no server answers; `dhcp` re-runs it; learns the DNS server from option 6). `netcmd.c` — the `netinfo`/`netrecv`/`netsend`/`netip`/`dhcp`/`pong`/`ping`/`netregs` commands. `dns.c/h` — a minimal resolver (one recursive A query over UDP, name-compression aware; `netdns` shows/sets the server, `host ` resolves). `tcp.c/h` — a minimal TCP *client* (connect/send/recv/close, in-order receive with an 8 KB receive queue so data arriving during a send is never lost, one segment of retransmit; the caller owns the NIC). `curl` — the ring-3 command: `http://` or `https://` GET with DNS, ARP, a dumped status/headers/body, chunked decoding (redirects are followed, up to 5 hops); TLS 1.3 via `tls.c/h` + `tls_sha256.c`, `tls_chacha20.c`, `tls_x25519.c`, `tls_rng.c`: `TLS_CHACHA20_POLY1305_SHA256` + X25519 only, stream-oriented record layer, leaf SHA-256 fingerprint printed for a manual check. Certificates are **not verified** (phase A: encryption without authentication; a MITM is undetected) and the DRBG (`tls_rng.c`: RDTSC jitter + ticks + MAC) is deliberately weak. The crypto files are pure freestanding C and have host vectors (`make test-crypto`, `tls_test.c`); the TLS code lives in the command pack, so `make net-cmds` updates it without a kernel reload. Static IP default `192.168.178.240`, mask/gateway learned from DHCP (off-subnet traffic goes via the router). - **Hot-reload (kexec)**: `kexec.c/h`, `kexec_tramp.S`, `entry.S`, and the host-side `kexec_send.c` — reload the kernel over serial without rebooting (C-light: reuses the current framebuffer, re-runs `kernel_main`). The transfer entry is `kernel_entry` (`entry.S`), which re-points ESP before any stack use: the jumping kernel's trampoline stack address comes from the *old* build's memory map, so a reload between different maps (e.g. after the kernel region grew) would otherwise land the stack inside the new image. `netkexec.c/h` + host-side `netkexec_send.c` do the same over UDP (`make net-dev BOARD_IP=…`): the WM loop auto-detects the header, the board acks every datagram with the next expected offset, verifies the checksum and jumps. While idle the same loop answers ARP/ICMP for our IP, so the board is reachable (and MAC-resolvable) without running any command. `kexec_jump()` calls `smp_stop_aps()` first: every AP gets an INIT and is parked in the wait-for-SIPI state before the trampoline overwrites the kernel they were executing. It runs with interrupts off, resets `sched_lock` (an AP may have been inside a scheduler critical section when INIT arrived) and then jumps; the new kernel starts the APs again from scratch. - **Mouse**: `mouse.c/h` — cursor move/draw shared by the PS/2 path (IntelliMouse, Cirrus/Radeon hardware cursor) and the USB backend; `usbhid.c/h` — USB HID boot devices: find + configure a mouse and/or keyboard, arm their interrupt endpoints, decode mouse reports and inject keyboard scancodes, watch for plug/unplug. - **USB**: `usb.c/h` — controller-agnostic core: device enumeration, descriptor parsing, hub recursion, bus scans, per-controller addresses, the hotplug watcher and the interrupt-IN consumers (mouse + keyboard). It keeps a global controller table, so EHCI (high-speed) and its UHCI/OHCI companions (low/full-speed) are driven together; EHCI is scanned first so its port resets hand non-high-speed devices back to the companions. `usb_hcd.h` is the host-controller ops vtable; `uhci.c` (I/O-port UHCI, frame list at `0x3000`, one instance), `ohci.c` (MMIO OHCI, up to 4 instances, HCCA + ED/TD lists, polling), `ehci.c` (MMIO EHCI, QH/qTD asynchronous schedule, up to 4 instances) and `xhci.c` (MMIO xHCI, USB2 root ports) implement it. `lsusb.c` — the `lsusb` command (lists every controller and its tree). The devices work on every controller type and can be plugged in at any time (root-port connect-change watcher); `lsusb` re-enumerates the bus, after which `usbhid` re-inits itself via a scan generation counter. - **Power/idle**: `idle.c` — `idle auto` (the default) asks `power.c` for the MWAIT hint: C6 (`0x20`) on the Nehalem/Westmere allowlist, HLT everywhere else. `idle hlt|c1e|c3|c6` (and the `c3ap`/`c6ap` AP-only variants) are explicit overrides for testing; the Atom boards keep HLT because of the old USB-legacy SMM hang (the UHCI/OHCI `0xC0` legacy-SMI disable addresses it). Arrandale hints are C1 `0x00`, C1E `0x01`, C3 `0x10`, C6 `0x20`. The BSP PIT and each AP's LAPIC timer run at 1 kHz while a process runs and drop to 100 Hz/10 ms while the CPU is idle (`timer_set_hz`, `lapic_timer_set_ms`); the PIT stub advances the global millisecond clock by `timer_tick_advance()`, and `smp_resched_wake()` shortens the idle period when new work arrives. - **Frequency/package power**: `power.c/h` — Nehalem/Westmere P-states and C-state setup, gated on the model allowlist (`0x1A/1E/1F/25/2C/2E/2F`) because the MSRs must not be touched elsewhere. `power_init()` enables SpeedStep (`MISC_ENABLE` bit 16) and C1E (`POWER_CTL` bit 1), raises the package C-state limit in `PKG_CST_CONFIG_CONTROL` to C6 only when it is unlocked (bit 15), reads min/max ratios from `PLATFORM_INFO`, and starts at the maximum non-turbo ratio. The per-CPU tick runs a race-to-idle governor: 100 ms windows pick min/max/linear target ratios (short busy streaks jump to max immediately) and each CPU writes its own `IA32_PERF_CTL`. Nehalem/Westmere take the target ratio in bits 15:8 and the low byte is written as zero (a preserved VID byte made the request silently ineffective); `IA32_PERF_STATUS` reports the current ratio in bits 7:0 (the X201 boot dump shows 0x12 at the 18x max non-turbo ratio). The `power` command prints effective MHz (`APERF`/`MPERF`), the current and requested ratios, per-core C3/C6 residency and package C3/C6; `cpufreq [auto|min|max|off|]` overrides the governor. - **CPU temperature**: `thermal.c/h` — Intel DTS through `IA32_THERM_STATUS` (MSR `0x19C`). Each CPU samples itself once a second from its scheduler tick (`struct cpu.temp_c`), and `SYS_CPU_TEMP` (`sys_info.c`) exposes the hottest core plus TjMax to ring 3. The model allowlist follows coretemp (Core/Core 2, Nehalem/Westmere including the X201's Arrandale `0x25`, and Bonnell) and is what keeps `rdmsr` away from CPUs that lack the MSR. Nehalem and later read TjMax from `IA32_TEMPERATURE_TARGET` (MSR `0x1A2`, bits 23:16; the X201's i5 M 520 reports 105 °C); Bonnell has no such MSR, so its TjMax stays table-driven (Atom 330 = 125 °C, 230 = 100, other Bonnell = 90, otherwise 100). The 330's 125 °C is Linux coretemp's empirical value; Intel only specifies TJ = 90 °C and Tcase-max = 85.2 °C, so `sensors` prints the raw delta and the 90/100/125 °C scales as well as the top bar's `CPU 43C` before the clock (with `BAT 87%` to its left on ThinkPads) and `cpuinfo`'s value plus EIST state. Platforms without DTS (QEMU, Pentium) hide it. - **Board sensors**: `it87.c/h` — read-only probe of the IT87xx Super I/O (the AT3IONT-I exposes three temperatures and three fan tachometers), used by `SYS_SENSORS` and the ring-3 `sensors` command to cross-check the DTS and show whether the fans turn. Nothing is written to the fan control. `tpec.c/h` adds the ThinkPad embedded controller of the X201 (`SYS_TPEC_SENSORS` for temperatures/fan, `SYS_POWER_INFO` for AC/battery): a `_SM_` SMBIOS type 1 check gates the probe to Lenovo/IBM machines, then EC reads through ports 0x62/0x66 return the temperatures at EC 0x78..0x7F / 0xC0..0xC7 (0x80 = absent, 0x00 = unimplemented; revision 3+ at EC 0xEF only uses the first block), the fan tachometer at 0x84 (LSB, always read first) / 0x85 and the 0x2F fan mode. The power path reads 0x38/0x39 (bit 7 present, bit 6 discharging, bit 5 charging) and 0x46 bit 4 (AC online), then selects the 0x81 battery information page (high nibble battery, low nibble page: 0 dynamic, 1 mode, 2 design, 5 manufacturer, 6 model) and reads the 16-byte window at 0xA0..0xAF. A pending EC output byte (a hotkey event, since there is no SCI handler) is drained before every command, and every wait is bounded; the only EC write is the 0x81 page selector, restored when it changed. `sensors` labels the EC registers and decodes the fan mode (auto / full speed / level); the ring-3 `powerinfo` command prints AC/battery details and the WM top bar shows the first present battery with a valid percentage. - **Ring-3 address space**: the ELF image and 8 KB stack live in the 2 MB `USER_BASE` (`0x40000000`)..`USER_STACK_TOP` (`0x40200000`) window, which is too small for a full-frame image. `SYS_MEM_ALLOC`/`SYS_MEM_GROW`/`SYS_MEM_FREE` (`sys_mem.c/h`) map/grow/delete a single anonymous arena at `USER_HEAP_BASE` (`0x60000000`), capped at 32 MB; the initial allocation is zeroed but pages appended by `SYS_MEM_GROW` are not (decoders initialize what they use), which keeps large image arenas fast to map. The reaper frees it with the rest of the process and `top` counts its pages. Ring-3 commands use `libc/malloc.c` (malloc/free/heap_reset), which owns this arena; the `SYS_MEM_*` calls are the libc backend (`libc/ucmd_mem.c`) and are not called by application code. The canvas mapping at `USER_GFX_BASE` (`0x50000000`) and the WM mappings are separate. - **Ring-3 libc**: `libc/include/` (stddef/stdint/stdarg/stdlib/string/ctype/ assert/ucmd_heap), `libc/malloc.c`, `libc/string.c`, `libc/strdup.c`, `libc/stdlib.c`, `libc/ucmd_mem.c`, linked as `libc.a` only into commands that reference it. `malloc` is a boundary-tag first-fit allocator with immediate coalescing: 16-byte aligned, `calloc` zeroes, `realloc` grows in place when the next block is free, and the heap maps 64 KB lazily then grows in page-rounded steps with 64 KB slack up to the 32 MB arena cap. `heap_reset()` (`ucmd_heap.h`) discards every allocation and unmaps the arena for page-scoped apps such as the browser. There are no threads, so there is no lock; application code uses this heap, and the libc backend is the only caller of `SYS_MEM_*`. The archive plus `-ffunction-sections`/`--gc-sections` keeps unused code out of the legacy pack. Host test: `make test-libc` (`libc/test_malloc.c`). - **Ring-3 commands**: `ucmd_*.c`, `ucmd_lib.h`, `ucmd.ld`, `mkpack.c`, `rootfs.h`, `mkrootfs.c`, `ramfs.c/h` — static ELFs linked at `USER_BASE` (`0x40000000`), packed by `mkpack` into `cmds.pack` (as `bin/`), gzipped to `cmds_pack_gz.bin` and wrapped by `mkrootfs` with a `NBROOT1` header. The pack is the system rootfs: the boot path loads it into RAM (legacy low gap / UEFI / kexec staging) and `ramfs_init` takes a private page-allocated copy, mounted read-only at `/ramfs`. The shell finds them through PATH (`/ramfs/bin` by default), loads the whole ELF through the VFS and spawns it as a ring-3 process; `hello` is just `bin/hello`. New command: add `ucmd_.c` to UCMDS — the pack, the mount and the PATH listing pick it up automatically. `SYS_SPAWN` still loads ELFs from any VFS mount, so commands can also live on `/share` or a FAT disk (`path /share/bin`, or an absolute path). They talk to the kernel through `int 0x80` (`syscall.h`: putstr/ticks/sleep/exit, the whole-file service in `sys_fs.c`, the state snapshots in `sys_info.c` and the network service in `sys_net.c`) and inherit the terminal's screen, so their output lands in the owning window. Each process inherits the spawning terminal's working directory (`struct process.cwd`, exposed as `SYS_GETCWD`), and the file syscalls resolve relative paths against it, so commands keep working after `cd` (the shell passes arguments verbatim). The one argument is passed as a C string on the top of the user stack (`process_create_user(..., arg)`), so `_start(const char *arg)` needs no crt0. `ngui.c/h` is the shared userland GUI toolkit linked into `ucmd_files.c`, `ucmd_mines.c`, `ucmd_solitaire.c` and the external `gallery.elf` (buttons, menu items, text fields, icons, layout cuts and scroll panes); `files` opens the selected text file through `/ramfs/bin/edit`, image files through `/ramfs/bin/view`, and `.htm`/`.html` files through `/ramfs/bin/browser`. `ngui_end_ex()` is the variant that runs the bookkeeping without publishing the canvas, for apps that poll input without redrawing. - **Gallery**: `gallery.c` is the ngui widget gallery: typography and truncation, the drawing primitives and clip stack, the theme palette, all nine icons, live buttons/icon buttons, text fields with event feedback, a nested draggable scroll pane and the `ngui_cut_*` layout helpers. The real ELF ships in the pack as `bin/gallery.app`; `ucmd_gallery.c` is the tiny `bin/gallery` launcher, which prefers `/share/GALLERY` (development upload via `make gallery-dev`), then the pack copy, then the `GALLERY` disk fallback on `root.img`/FAT mounts. - **Solitaire**: `ucmd_solitaire.c` — a Windows 95 style Klondike game on the canvas service: green felt, a Game/Help menu (ngui buttons and menu items: new game, draw one/three, blue or red deck), four foundations, seven tableau piles, stock/waste, drag-and-drop (or click a card and then its destination), double-click to send a card home, auto-flip, standard scoring, a score/time status bar and the bouncing-card win animation. The cards use pip layouts with mirrored corner indices, notched corners and pixel-art J/Q/K portraits; the back is the castle. The bar's "Cards" button launches `/ramfs/bin/solitaire`. - **Browser**: the real browser ships in the pack as `bin/browser.app` (it links ngui, the full image library, inflate, TLS and uhttp, but the rootfs is no longer constrained by the kernel's low-memory window). `ucmd_browser.c` is the tiny `bin/browser` launcher; it prefers `/share/BROWSER` (`make browser-dev` uploads it via the board's `websrv`; stop `websrv` before browsing HTTP, because it owns the NIC), then the pack copy, then `BROWSER` on `root.img`/IDE/SATA fat mounts. The launcher forwards its argument and cwd. `uhttp.c/h` is the shared ring-3 HTTP client extracted from curl: URL parsing/resolution, redirects, chunked decoding, timeouts and TLS; curl and the browser both use it. `browser_html.c/h` is a tolerant HTML tree + the CSS subset: external `` sheets (in document order, inline `