# 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, mass storage, 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-rndis # xHCI + QEMU usb-net RNDIS tethering device on slirp (rndis netdev) 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 test-install # installer test: clone, reinstall, install self, /data, BIOS/UEFI boot 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, RAM only) make net-install # persist kernel + full rootfs to P1/P2 (KXI2, keeps /data) 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 tests for ring-3 malloc, stdio, math, div64 and setjmp make test-mujs # host smoke test for the vendored MuJS engine make test-font # host TrueType parser/rasterizer specimen test make test-font-asan # ASan/UBSan variant make test-touchpad # host tests for the contact gesture engine make test-wpa # host tests for the WPA2-PSK supplicant (SHA-1/PBKDF2/PRF/AES, 4-way) make test-chat # host tests: JSON parser, cookie jar, chat login parsers (ASan) make test-chat-e2e # QEMU + tools/mock_chat.py chat end-to-end (CHAT_E2E=--totp...) make compat-serve # serve the browser A/B ladder on port 8000 make fonts # regenerate fonts/*.ttf with pyftsubset + system fonts make clean ``` - Build flags (in `Makefile`): `-m32 -march=i586 -ffreestanding -fno-pie -nostdlib -fno-stack-protector -mno-sse -mno-sse2 -mno-mmx -O2`. - QEMU guests default to 512 MB (`QEMU_MEM`, e.g. `make run QEMU_MEM=1G`), matching `MM_MAX_PHYS` in `phys.h`; all run and UEFI targets pass `-m`. - 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 `cmds.img` (the 8 MB USB partition image) and `BOOTX64.EFI`. The floppy images append `rootfs.bin`, built the same way from `cmds-lite.pack` (everything but `firmware/*`), because the ~1 MB WiFi firmware does not fit a 1.44 MB floppy. 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`). - The WiFi firmware `firmware/iwlwifi-7265D-29.ucode` is decompressed from the host's linux-firmware (`WIFI_FW` overrides the search; `zstd` needed for `.zst`). Without it the build prints a note and packs no firmware. - `root.img` is a second FAT12 floppy holding the disk fallback copies of the browser/gallery (`BROWSER`, `GALLERY`) and its `DEMO.HTM`/`JS.HTM` test pages plus `PIC.BMP`, and 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. With the WiFi firmware the gzip pack is ~1.3 MB, so it now ends past the first 1.44 MB: a BIOS that boots the stick as a CHS-only floppy can no longer read all of it (fixed-disk LBA boots are fine). 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. The `install` command clones this used image (MBR through the last partition) from a visible block device, so a cloned target keeps both boot paths. `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`, enables A20, reads the `NBROOT1` rootfs header at the boot sector's `pack_lba` field and copies the gzip pack directly to `PACK_HIGH_ADDR` (`0x900000`, above the 8 MB VGA-shadow reserve) in 16 KB chunks through the `0x3000` staging buffer with INT 15h AH=87h. The BIOS block move uses 24-bit descriptor bases; `paging_prepare_cpu()` clears the CR4/EFER state the X201's BIOS leaves behind. The stage then 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`, enters protected mode and jumps to `kernel_entry` (`entry.S`, re-points ESP to the current stack top, then `kernel_main`). The pack never occupies the low gap, so the cap is `PACK_MAX` (2 MB) and the kernel BSS/boot stack may 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, allocates a loader-data buffer below the 512 MB identity window (above the low 1 MB) for the embedded gz rootfs and copies it there, fills `0x500` (boot info) and `0x600` (framebuffer), calls `ExitBootServices`, 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` | No longer a rootfs staging area: the legacy stage copies each 16 KB chunk straight to `0x900000`. The kernel BSS/boot stack may use this range | | `_end` | Kernel end (linker symbol; `kernel.ld` keeps `_end <= 0x90000` so the top of the low-memory 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 written directly by `vesa_stage.S` (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 copies it directly to `0x900000`, the UEFI loader puts it at the top of RAM below 512 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/raw-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**: `phys.h` — the shared 512 MB physical ceiling (`MM_MAX_PHYS`), also used by the UEFI loader. `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, kernel staging below 4 GB and rootfs pack in loader-data pages below 512 MB, boot-info/framebuffer blocks, `ExitBootServices`). The loader prefers the raw installed image: it locates the parent whole-disk Block I/O handle from the ESP device path, reads the P1 boot sector (kernel_lba/kernel_sectors/pack_lba), then reads the kernel from P1 and the NBROOT1 gzip pack from P2. The kernel and pack embedded in `BOOTX64.EFI` are only a fallback when the disk image is missing or invalid, so `install`/`net-install` update both boot paths without rewriting the ESP. `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; when either rectangle is partly off-screen the shadow has no valid pixels for the hidden part, so that step repaints the window rect instead of copying desktop background into it. Windows may be dragged past the left, right and bottom edges while at least `WM_DRAG_VISIBLE` (48 px) of the title bar stays on-screen; the top bar is never overlapped. Double-clicking the title bar toggles maximize/restore against the work area below the bar (`0, WM_BAR_H, fbw, fbh - WM_BAR_H`); dragging a maximized window restores it first, and the resize grip grows a window to the full work area (snapping when dragged into the screen corner). The kernel hit-test uses the same order. The right-aligned date/time text is itself a click target: `draw_bar()` records its rectangle, the pointer highlights it, and a click spawns `/ramfs/bin/settime` (the `Clock` launcher still opens the analog clock). The rightmost bar item is the AC/battery status icon: a plug while the adapter is online and a level-filled battery on battery. Hovering it paints a percentage tooltip below the bar, above every window. To its left is the network status icon: a cable for a wired netdev, signal bars for an associated WiFi link, a USB mark for RNDIS tethering, and a red X otherwise. The WM polls `SYS_NET_INFO` (and `SYS_WIFI_STATUS` only while WiFi is active) at 1 Hz; clicking the network icon spawns one `/ramfs/bin/netmenu` window and anchors it under the icon once its window exists (`u_wm_set_geom`). The last launcher, `Chat`, spawns `/ramfs/bin/chat`; `WM_BTN_END_X` (`wm_abi.h`) is the launchers' right edge, and the bar notice and the right-aligned status never draw left of it. `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`); the WM maps each front canvas in its own 4 MB `WM_CONTENT_SLOT`, which covers a full-screen 1280x1024 canvas minus the chrome. `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_SCROLL`, `SYS_WIN_KEY_WAIT` and the generic `SYS_KEY_POLL` handle input. `SYS_WIN_SCROLL` returns scroll accumulated for the canvas window under the pointer, in pixels (`+dy` = later content), so every client sees one unit independent of whether it came from the touchpad or a wheel. 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`, `settime`, `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 use the proportional font with measured caret, selection and horizontal scrolling, and 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. A field with `secret` set is measured and painted from a `*` mask (the real text is swapped back only for the edit loop, so caret, selection and clicks follow the mask); Tab returns `NGUI_INPUT_NEXT` with `NGUI_INPUT_CANCEL` so forms move the focus themselves. `NGUI_INPUT_MAX` is 512 (511 characters). - **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. The kernel console stays 8×8; userland proportional text uses `ufont` (below). - **Wall clock**: `rtc.c/h` reads and writes the CMOS RTC. Reads honour the register-B BCD/binary and 12/24-hour modes, retry around the update cycle, and expand the two-digit year with a 1970-2069 window (70-99 -> 1900s, 00-69 -> 2000s), so a dead-battery default such as 1980 or 1990 reads correctly. Writes use the RTC's SET bit, preserve its mode bits and validate leap years and 1970-2069; on ACPI machines the FADT century byte (exposed by `acpi_rtc_century_reg()`) is written too, so other software sees the right century. `SYS_RTC_GET`/`SYS_RTC_SET` (104/105) expose the full `struct sys_datetime`; `SYS_RTC_HMS`/`SYS_RTC_DATETIME` (56/69) stay the small read-only views. The WM top-bar date/time is a click target that spawns `/ramfs/bin/settime`, whose "Sync NTP" button fetches UTC through `SYS_NTP_SYNC` and writes it with `SYS_RTC_SET`; the `date` command prints the classic `date` line and a small `+FORMAT` subset. - **Fonts**: `ufont.c/h`, `ufont_ttf.c`, `ufont_draw.c`, `ufont_file.c` — a fixed-point (26.6, no FPU) TrueType parser and antialiased rasterizer for ring-3 text. The byte/Latin-1 path remains the default; cmap format 4 and format 12 are supported, and the new UTF-8 `ngui_text_utf8*`/ `ngui_menu_item_utf8` APIs fall back per codepoint to the monochrome `fonts/emoji.ttf` subset (`ngui_font_attach` loads it lazily). The existing faces are the Arimo regular/bold/italic/bold-italic and Liberation Mono subsets plus Noto Emoji in `fonts/`, packed into `/ramfs/fonts`. The emoji subset is limited to common single-codepoint glyphs that fit the rasterizer (256 points / 16 contours); ZWJ sequences, flags, color glyphs and shaping are not supported. `ufont` owns one 512 KB `malloc` arena for face data and glyph masks; the built-in faces plus up to 11 `@font-face` faces share it. `ngui_font_attach/detach` (ngui) and `usurf_font_attach` (`uwm_lib`) load faces and leave the 8×16 bitmap fallback when they are absent. The **browser calls `ngui_font_detach` before `heap_reset()` and reattaches after `heap_start()`**, because its page heap is reset on every navigation. Terminal and editor cells deliberately keep the 8×16 bitmap grid; ngui text fields use the proportional face with measured caret, selection and horizontal scrolling. Host test: `make test-font` (`ufont_test.c`); `make fonts` regenerates the subsets. No hinting, CFF/variable fonts, shaping, bidi or full Unicode yet. - **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 + eMMC + USB 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 file operation enters a non-preemptible section (`preempt_disable`, with interrupts on for the floppy's IRQ 6) because the FAT driver has static state; `vfs_scan_busy` and `format_busy` make it sleep first when a mount scan or a destructive format owns the disks. A format releases the BKL for its raw-sector loop, so the WM and terminals keep running; `sys_fs_begin()` applies the `format_busy` wait only to disk-backed mounts, so `/ramfs` and `/share` stay usable during a format. Expect a brief 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. - **Installer**: `install.c/h` — the privileged `install [source|self]` command clones the live NebOS image or writes the running image. A clone detects a source by the MBR plus the LBA-63 boot-sector signature (`NEBOS` OEM string, `kernel_lba` 64, `pack_lba` 1088), computes the used length from the end of P1..P3 (P4 is the data volume and is never cloned), allocates a page buffer for the whole image and reads the source into RAM first (LBA 1..62 are synthesized as zeros instead of read). It prepares/keeps P4, writes the target from RAM in chunks with the source no longer active, merges the target's P4 entry into the source MBR, writes the MBR **last**, flushes and verifies by checksum before remounting the target. A source-read failure therefore leaves the target untouched. The source read keeps the BKL (a USB3 stick must stay active across chunks); the target writes release it per chunk so the WM/terminal stay responsive. It reuses `format_busy`. The source can be `usb0` (USB mass storage), IDE, SATA or eMMC; the target is any non-floppy block device with enough sectors. `install self` writes the retained gzip boot image and the kernel bundled at `/ramfs/install/kernel.bin` to P1/P2, patches the boot sector's exact `kernel_sectors`, keeps an existing P4 and creates/formats it when absent. It refuses a raw runtime pack (`cmds-dev`/`net-cmds`/ `kernel-dev`); use `net-install` for that. `target=auto` picks the only non-USB NebOS disk. - **`/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. - **`/data`**: the installed disk's partition 4 is a writable FAT volume with the label `NEBOSDATA`, created by `install`/`install self` at LBA 34816 (after P1 kernel, P2 rootfs pack and P3 ESP) and filling the rest of the disk. `vfs.c` mounts the first volume with that label as `/data` (not as `p4`); the mount table records its source device so remount/unmount works. Files are 8.3 only until FAT LFN write support exists. A reinstall replaces P1..P3 and keeps P4; `net-install` never touches it. The data volume is not available on the live USB unless that stick was installed. - **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). - **eMMC/SDHCI**: `sdhci.c/h` — polled SDHCI driver for the Intel Braswell MMC function at PCI `00:10.0` (8086:2294, class 0805, the HP Chromebook eMMC). `sdhci_init()` resets the host, selects the 1.8 V rail from the capabilities and enables Host Control 2's 1.8 V signalling, runs a 400 kHz init clock, then CMD0/1/2/3/7/16 and CMD8 to read the 512-byte EXT_CSD (`SEC_COUNT` at 212, `CACHE_SIZE` at 249), and switches to a 25 MHz data clock. Sector I/O is CMD17/CMD24 over the polled PIO buffer port (one 512-byte block per command; no DMA, IRQ, CMD6 bus-width/high-speed switch or hotplug). The read/write loops call `sched_yield()` every 32 sectors so a long format does not starve the WM/terminal (a normal file read has preemption disabled, so the yield is a no-op there). `blkdev.c` registers it as `mmc0`, so `storage`, the VFS MBR+ FAT mount path and `format mmc0` work exactly like an IDE/SATA disk; `sdhci_flush()` issues the CMD6 `FLUSH_CACHE` when the card reports a write-back cache. A stock eMMC holds the ChromeOS image, so formatting it is destructive. - **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), `asix.c` AX88772 USB Ethernet (bulk over the USB core, so an EHCI/xHCI dongle is usable) and `rndis.c` USB RNDIS tethering (Android phones and QEMU `usb-net`; device-level config scan, RNDIS INIT/QUERY/packet-filter, 44-byte packet header and an Ethernet netdev). `netdev [name]` is a kernel command that shows the active driver or switches it (`netdev rndis`, `netdev asix`, `netdev e1000e`, ...); it calls the selected driver's probe and leaves the current driver untouched on failure. The top-bar network icon opens `ucmd_netmenu.c`, which lists every present driver through `SYS_NET_DEVLIST` (111), selects one through `SYS_NET_SELECT` (112) and runs DHCP; the same window lists scanned WiFi networks and asks for the WPA2 passphrase. Hidden SSIDs are omitted, and BSSIDs that share an SSID/security collapse to the strongest entry (the active BSSID wins while connected). `wifi.c` (the Intel 7265D/3165 netdev, see the WiFi bullet) is last in the table; `struct netdev` has an optional `link_up()` hook (e1000e `STATUS.LU`, r8168 `PHYstatus`, ASIX probe-time `BMSR`, WiFi association state), the boot DHCP is skipped while it returns 0, and a physically linked wired NIC keeps `wifi autoconnect` from overriding it. `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()`. ARP entries expire after five minutes and their age slides on every hit, so a gateway or DNS entry is not lost during a long page load. `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, one query in flight plus a five-minute A-record cache for parallel stack callers; `netdns` shows/sets the server, `host ` resolves). `ntp.c/h` — a minimal SNTP client (RFC 4330): one 48-byte request to UDP port 123, three one-second tries, origin-timestamp validation and the reply's transmit timestamp converted from the 1900 epoch to UTC. `SYS_NTP_SYNC` exposes it to the Date & Time app; the default server is `pool.ntp.org`, the service takes the raw NIC receiver for the duration and is refused with `SYS_NTP_EBUSY` while another raw command or a TCP client is active. `tcp.c/h` — a minimal TCP *client table* (connect/send/recv/close, one connection per process, in-order receive with a per-connection receive queue (64 KB from the frame allocator when it can find a contiguous run, 32/16 KB fallbacks) so data arriving during a send is never lost, one segment of retransmit; `net_pump()` dispatches frames to every client). `tcp_client_close()` sends FIN and frees the slot at once (all sends are synchronous, so nothing is unacknowledged); the peer's late FIN matches no client and is dropped. `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). - **WiFi (Intel 7265D/3165, the HP Chromebook)**: `iwl_trans.c/h` — PCIe transport after Linux iwlwifi (7000 family): PCI scan for `8086:095a/095b/3165/3166`, D0, BAR0 mapped with `process_map_mmio_all`, APM init, one legacy RX queue (256 x 4 KB RBDs), gen1 128-byte TFD queues with dword byte-count tables, firmware TLV parse and section DMA through the FH service channel (128 KB bounce, `LMPM_CHICK` for the extended range), polled `CSR_INT`. Everything is page-allocated; the NIC is kept awake (MAC access request held) and INTx is disabled. Host commands use the wide header (legacy ids go out as group 1, like Linux's `DEF_ID`). `iwl_mvm.c/h` — firmware commands for the 7265D-29 API: INIT image (BT config, NVM HW section -> MAC at word 0x15, TX antennas, PHY config, `CALIB_RES_NOTIF_PHY_DB` collection until `INIT_COMPLETE`), runtime image (PHY-DB replay, PHY config, BT config, DQA enable, aux station 1 on queue 1, PHY context 0, CAM power, MCC `ZZ`, MAC context 0), LMAC scan (`SCAN_OFFLOAD_REQUEST`, wildcard active, 37 channels), connect (PHY context, binding + quota, `SCD_QUEUE_CFG` queue 4, AP station 0, time event), `ADD_STA_KEY` v1, `TX_CMD` v6 (fixed legacy rates: 1M CCK / 6M mgmt, 12M OFDM data), legacy `RX_PHY`/`RX_MPDU` parsing. `wifi.c/h` — 802.11 station: beacon/probe parsing (SSID, DS channel, TIM DTIM, RSN with PSK + CCMP pairwise/group), open-system auth and a non-QoS association request (no WMM/HT IEs), Ethernet <-> 802.11 data + LLC/SNAP + host-built CCMP header/PN, an EAPOL queue (ethertype 0x888e never reaches `net_pump()`), the `wifi` netdev and `SYS_WIFI` (110, multiplexed op). RX CCMP is decrypted in software (`ccmp.c`, AES-CCM, RFC 3610 vector in the host test) when the firmware reports `SEC_ENC_ERR`, because this 7265D-29 firmware does not use correctly installed `ADD_STA_KEY` keys for RX even though TX (which embeds the TK in `TX_CMD`) works; there is no software replay window yet. The firmware is loaded on the first `wifi` command, not at boot. `netdev_shutdown()` always calls `wifi_shutdown()` before a kexec (the RX ring would keep writing into reused pages). The ring-3 side is `ucmd_wifi.c` (`wifi`, `wifi up|scan|connect [pass]|disconnect`, `wifi connectfile ` for the network menu's staged SSID/pass/BSSID record, `wifi autoconnect` for the boot helper and `wifi forget`), `wpa.c/h` (4-way + group handshake, key descriptor v2) and `wpa_crypto.c/h` (SHA-1, HMAC, PBKDF2, PRF, AES-128, RFC 3394 unwrap; host test `make test-wpa`). After the handshake `wifi connect` installs the TK/GTK, calls `SYS_WIFI_AUTHORIZE` (data port open + `netdev_select ("wifi")`), runs DHCP and leaves `wifi __keep` running for group rekeys. A successful menu/CLI connect also writes the SSID and passphrase to `/data/WIFI.CFG` (8.3, plaintext, BSSID zeroed so a mesh/repeater AP works); after the boot DHCP attempt `kernel_main` spawns `/ramfs/bin/wifi autoconnect` when that file exists. Autoconnect leaves a wired link that is physically up alone and only tries WiFi when no wired link is present; an already-linked WiFi card is also left alone. `/data` is the persistent FAT volume from the installer. `wifi forget` removes the saved record. A FAT read may write a final partial sector past the requested length, so the credential reader keeps 512 bytes of slack on the stack. The helper's PTK and EAPOL replay counter are kept in the kernel (`SYS_WIFI_SET_PTK`/`SYS_WIFI_GET_PTK`) and fetched by connection ID, so the 64-byte `SYS_SPAWN` argument limit cannot truncate the rekey state. There is no QEMU model: test on the Chromebook over `make net-dev` with the RNDIS phone/ASIX dongle as the management link and `make netmon` for the `iwl:`/`wifi:` trail. - **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 including the 4th-byte wheel, Cirrus/Radeon hardware cursor) and the USB backend. Scroll from every backend accumulates in `mouse_scroll_y` and `mouse_scroll_take()` hands it to the WM in pixels; one PS/2 wheel notch is 48 px. `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 (boot protocol has no wheel field, so the USB wheel output stays 0 for now). - **I2C touchpad**: `i2c.c/h` — polled Synopsys DesignWare APB I2C master for the Braswell LPSS blocks (fast mode, component-type probe, explicit LPSS reset-release so the FIFO drains); `touchpad.c/h` — Elan HID-over-I2C touchpad on LPSS I2C6 at `0xD1327000`, slave `0x15`. `touchpad_init()` runs from `mouse_init()` at boot (it maps the I2C window before processes clone the page directory), resets the device, consumes the 2-byte acknowledgement, reads the HID descriptor, selects absolute mode (`0x0300 = 1`), wakes it (`0x0800`) and then queries the native max-X/Y commands (`0x0106`/`0x0107`). The report line is a GPIO with no driver, so `touchpad_poll()` reads the input register every 25 ms (back-to-back reads stall the device), parses the Elan `0x5D` vendor report (finger bitmask plus five bytes per packed finger) and feeds the device-independent `touchpad_gesture.c/h` engine. The engine owns pointer scaling, taps, the physical-button latch and two-finger scrolling, so another touchpad backend only has to decode its own reports into up to two contacts. A short stationary tap synthesizes a button press: two fingers -> right click, one finger in the bottom-right zone (`x >= 75%`, `y <= 25%`) -> right click, one finger elsewhere -> left click. The device's raw Y axis grows upwards, so the bottom is the low end. A physical clickpad press is also latched at its leading edge: in the bottom-right zone it becomes the right button, elsewhere the left button, and the latch holds for the whole press. Two fingers that move their centroid by more than ~30 device units scroll; the pointer freezes while two or more fingers are down and re-anchors when one remains. Natural scrolling (two fingers up = later content) is the default. `touchpad` prints the probe/status and takes `rightclick off|tap|corner|both`, `tapclick on|off` and `scroll on|off|natural|traditional`; `mouseinfo` lists the Elan VID/PID. - **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 and USB3 root ports; halt/HCH reset sequence and BIOS/OS handoff) implement it. `lsusb.c` — the `lsusb` command (lists every controller and its tree). `usbmsc.c/h` — USB mass-storage class driver (BOT/SCSI) exposed as `usb0..`; its device probe is registered next to ASIX and `blk_scan()` registers the devices in the block registry. 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. Nehalem/Westmere use C6 (`0x20`); Airmont/Braswell uses C6N (`0x58`) when CPUID.5:EDX advertises the C6 substates and the MWAIT interrupt-break extension is present; older Bonnell Atoms and APs without ARAT keep HLT because of the old USB-legacy SMM hang (the UHCI/OHCI `0xC0` legacy-SMI disable addresses it). `idle hlt|c1e|c3|c6` (and the `c3ap`/`c6ap` AP-only variants) are explicit overrides for testing. Arrandale hints are C1 `0x00`, C1E `0x01`, C3 `0x10`, C6 `0x20`; the Airmont auto path uses the Cherry Trail C6N hint. 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. - **P-state/frequency power**: `power.c/h` — two platform paths, gated on the model allowlist so the MSRs are not touched elsewhere. Nehalem/Westmere (`0x1A/1E/1F/25/2C/2E/2F`) enable SpeedStep (`MISC_ENABLE` bit 16) and C1E (`POWER_CTL` bit 1), raise the package C-state limit in `PKG_CST_CONFIG_CONTROL` to C6 only when it is unlocked (bit 15), read min/max ratios from `PLATFORM_INFO`, and start at the maximum non-turbo ratio. Their target ratio goes in bits 15:8 of `IA32_PERF_CTL` with the low byte 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). Airmont/Braswell (family 6 model `0x4C`) reads `MSR_ATOM_CORE_RATIOS` `0x66A` (min/max pstate), `MSR_ATOM_CORE_VIDS` `0x66B` (VID range), `MSR_ATOM_CORE_TURBO_RATIOS/VIDS` `0x66C/0x66D`, `MSR_FSB_FREQ` `0xCD` (the Airmont BCLK table) and `MSR_PLATFORM_INFO` as a fallback. The N3060 reports pstates 6..20, BCLK 80 MHz (1600 MHz nominal), turbo pstate 31 (2480 MHz) and VID 0x2D..0x3C. It writes `IA32_PERF_CTL` as pstate in 15:8 and the Linux-interpolated VID in 7:0; the governor starts at max non-turbo (pstate 20) and drops to min (pstate 6, 480 MHz). Turbo is detected but deliberately not requested, so `cpufreq max` means max non-turbo. No C1E/package-CST/auto-demotion MSR writes (coreboot configures them) and no package-energy MSR reads; APERF/MPERF are used only when CPUID.06H:ECX[0] says they exist. C3/C6 residency is not read on Airmont. The per-CPU tick runs a race-to-idle governor: 100 ms windows pick min/max/linear target pstates (short busy streaks jump to max immediately) and each CPU writes its own `IA32_PERF_CTL`. The `power` command prints the platform, effective MHz (`APERF`/`MPERF`), current/requested pstate, and on Nehalem the C3/C6 and package residency; the Airmont line adds the FSB, nominal MHz, turbo pstate/VID, VID range and the live `PERF_CTL`. `cpufreq [auto|min|max|off|]` overrides the governor on both. - **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`, Bonnell, and Airmont/Braswell model `0x4C`) and is what keeps `rdmsr` away from CPUs that lack the MSR. Nehalem/Westmere read TjMax from `IA32_TEMPERATURE_TARGET` (MSR `0x1A2`, bits 23:16; the X201's i5 M 520 reports 105 °C); Airmont uses the coretemp 90 °C table instead of reading `0x1A2` (a missing MSR before the IDT is installed would triple-fault); 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 bare `43C` before the clock and, on ThinkPads and the HP Chromebook, the AC/battery icon at the far right (a plug while on AC, a level-filled battery on battery, with a percentage tooltip below it on hover) 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 AC adapter state plus the first present battery with a valid percentage. Machines without the EC show neither. `ec.c/h` is the shared ACPI EC protocol (ports 0x62/0x66, command 0x80 read / 0x81 write, OBF/IBF waits, stale-byte drain, bounded polls); both `tpec.c` and `cros_ec.c` use it. `cros_ec.c/h` probes the Chrome OS EC: ACPI memory version 2, the `'E','C'` memmap id, the device feature bits, and skips the probe when the ThinkPad EC is present. The ACPI window 0x20..0xFF mirrors memmap 0x00..0xDF: temperature sensors 0x00..0x0f and 0x18..0x1f (raw - 73 °C), fans 0x10..0x17 (0xffff = absent), switches 0x30 (lid/power button), and the battery block 0x40..0x7f (AC/present/ charging/discharging flags at 0x4c, voltage 0x40, rate 0x44, remaining 0x48, design 0x50, design voltage 0x54, last full 0x58, cycle count 0x5c, and the 8-byte manufacturer/model/serial/type strings at 0x60..0x7f). `EC_ACPI_MEM_BATTERY_INDEX` 0x12 selects the battery and waits for `BATT_INDEX` 0x4e; `EC_ACPI_MEM_STRINGS_FIFO` 0x16 supplies longer strings when supported. The Cyan full-charge workaround is applied and the units are mAh/mA. `SYS_CROS_EC_SENSORS` (107) exposes temperatures, fans, fan duty and switches; `SYS_POWER_INFO` reports source `SYS_POWER_SRC_CROS`. `power_src.c` tries the ThinkPad backend first, then the Chrome EC, so the WM top bar and the `powerinfo`/`sensors` commands work on both. - **Ring-3 address space**: the ELF image and 128 KB (32-page) stack live in the 4 MB `USER_BASE` (`0x40000000`)..`USER_STACK_TOP` (`0x40400000`) 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, setjmp/errno/stdio/math/time/sys/time/sys/types, float/ limits/inttypes/alloca), `libc/malloc.c`, `libc/string.c`, `libc/strdup.c`, `libc/stdlib.c`, `libc/ucmd_mem.c`, `libc/setjmp.S`, `libc/errno.c`, `libc/div64.c`, `libc/dtoa.c`, `libc/stdio.c`, `libc/stdio_file.c`, `libc/math.c`, `libc/time.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_*`. `stdio` provides integer/string/float `printf`/`snprintf`/`sprintf` formatting and a read-only whole-file `FILE` (`fopen("rb")`, `fread`, `fseek`, `ftell`, `fclose`; stdout/stderr are console streams; stdin is EOF). `time` uses `SYS_RTC_GET`/`SYS_RTC_SET` with UTC-only `gmtime`/`localtime` and 64-bit `time_t`; `math` is the x87 double set used by MuJS. The archive plus `-ffunction-sections`/`--gc-sections` keeps unused code out of the legacy pack. Host tests: `make test-libc` (malloc, format/dtoa, math, div64, setjmp). - **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 high-memory AH=87h copy / 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 with a disabled state, 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 (including a disabled, read-only field) 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, uhttp and the vendored MuJS engine in `third_party/mujs/`, 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, the browser and chat use it. `browser_html.c/h` is a tolerant HTML tree + the CSS subset: external `` sheets (in document order, inline `