# AGENTS.md — Nebs OS (`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, no libc). Targets i586 (first-gen Pentium); runs under QEMU or on real hardware. ## 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 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 user binaries (`PROG.BIN`, `SPACE.BIN`), 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. - `make send PROGRAM=prog` transfers a binary to a real machine over serial. - 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 <= 0x7F000` so it does not reach the run area). 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) | | `0x7FF00` | Program API struct (`PROGRAM_API_ADDR`, `run_api.h`) | | `0x80000` | Legacy ring-0 program load area (`run.c`, `serial_recv.c`, `user.ld`; max 0x6000, inside the reserved low 1 MB) | | `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 the run area), 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, terminals 12, kworker 1, commands 8), 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**: `wm.c/h` — slot 0 runs `wm_run()`; fixed-size draggable terminal windows (64×32) with a system bar (banner + purple "New", "Clock", "Colors", "Files", "Mines", "Web" and "Cards" buttons + clock + CPU temperature + rainbow). Click-to-focus, drag-by-title-bar, close (×). The "New" button and first boot spawn terminals; there is no `term` command. Content is repainted per damage rect (`wm_redraw_rect`: desktop fill + every intersecting window back-to-front, clipped by `wm_draw_window_clip`), not by full redraws — a text window only over its damaged cell block (`screen_damage_block`), a canvas window over its whole content. - **Window graphics service**: `gfx.c/h` (RGB565 window canvases + bpp-aware blits), `sys_gfx.c/h` — a ring-3 command gets its window's canvas mapped RW at `0x50000000` (`SYS_GFX_BEGIN`; a mapped back buffer) and publishes frames with `SYS_GFX_PRESENT`, which copies it into the composited front buffer (double buffering; the copy runs with interrupts off, so a half-drawn frame can never reach the screen). Presented frames carry monotonic seq counters, so the WM can never lose one. Keys of a window with a live session go to the session (`SYS_KEY_POLL`; Ctrl+C still reaches the terminal), closing a window kills its session, and `sys_gfx_reap`/`sys_gfx_collect` free the canvas after exit/crash. `clock` and `colors` are its users. Generic canvas windows (`SYS_WIN_CREATE`) also get 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 per-terminal cell buffers (`struct text_screen`). A screen tracks the changed cell block (`screen_damage_block()`: `dmg_col0..dmg_col1`, `dmg_row0..dmg_row1`, grown by `screen_damage_cell()`/`screen_damage_cursor()`, reset by `screen_clear_damage()`), so the WM repaints a keystroke's cell instead of the whole window content and the blink only marks the cursor's own cell. - **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. - **Shell**: `terminal.c` — history, line editing, and a table-driven command registry (`cmds[]`: name, usage, spawn kind/handler) that holds only the builtins (`cd`, `path`, `help`, `clear`) and the kernel commands. Everything else is a file on the per-terminal **PATH** (`struct term.path`, default `/ramfs/bin`, `path` builtin to show/set): dispatch is builtins -> PATH -> kernel commands, so a packed command can shadow a kernel one. Tab completion and `help` list the registry plus the PATH contents. Runs in a window (`term_run(struct term *)`); reads keys from its per-terminal queue (filled by the WM). - **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`, `bin_recv.c/h`, `serial_recv.c`, `serial_loop.c`, `send_serial.c` — 16550 UART, IRQ-driven ring buffer, XMODEM. - **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, 3 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`, `bootstrap.c`, 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 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`): 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. A pending EC output byte (a hotkey event, since there is no SCI handler) is drained before every command, and every wait is bounded; nothing is written to the EC. `sensors` labels the EC registers and decodes the fan mode (auto / full speed / level). - **User programs**: `run.c`, `run_api.h`, `prog.c`, `space.c` — raw binaries at `0x80000`, API function-pointer struct at `0x7FF00`. `prog`/`space` are **embedded in the kernel image** (`prog_embed.o`/`space_embed.o`), so `make dev`/`make net-dev` update them too and a board with no readable filesystem can still run them: `run ` and the `prog`/ `space` commands use the embedded copy, `run //` still loads from FAT. Rebuilds are wired (`space.c` -> `space.bin` -> `space_embed.o` -> `kernel.elf`). Note: `run`/`prog`/`space` still draw over the WM (which keeps repainting its desktop); the windowed path for such programs is the ring-3 canvas service (see the window graphics bullet, used by `clock`/`colors`). - **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. The canvas mapping at `USER_GFX_BASE` (`0x50000000`) and the WM mappings are separate. - **Ring-3 commands**: `ucmd_*.c`, `ucmd_lib.h`, `ucmd.ld`, `mkpack.c`, `rootfs.h`, `mkrootfs.c`, `ramfs.c/h` — freestanding 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 `