# 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-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 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`. - `root.img` is a second FAT12 floppy holding user binaries (`PROG.BIN`, `SPACE.BIN`), the external browser (`BROWSER`) 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` remains the legacy-only image. `make flash` uses `usb-efi.img`, which is `usb.img` plus an 8 MB FAT16 ESP in a new third MBR partition (type `0xEF`, LBA 131072). The MBR boot code, partition entries 1/2 and the active partition 1 are unchanged except for one BPB byte: FATSize16 is cleared in the dual image (disk offset `0x7E16`). Without that, UEFI firmware scans the partition, 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. Legacy boot from the patched image is tested; `make flash FLASH_IMG=usb.img` flashes the untouched legacy-only image. `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`, picks best VBE mode (≥16 bpp, LFB, fits VRAM, ≤1280px), writes mode info to `0x600`, enables A20, enters protected mode, jumps to `kernel_entry` (`entry.S`, re-points ESP to the current stack top, then `kernel_main`). 3. `kernel.c` — `kernel_main` zeroes BSS then inits serial → memory/paging → ACPI/MADT → I/O → 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 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 unchanged. 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` | UEFI boot info (`struct boot_info`, `bootinfo.h`): magic/checksum, ACPI RSDP, EFI/RGBX flags; `vesa_stage.S` clears the magic on BIOS boot | | `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) | | `_end` | Kernel end (linker symbol; `kernel.ld` ASSERTs it stays below `0x7F000`) | | (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) | | `0x100000`| VGA shadow buffer (`VGA_SHADOW_BASE`, `vga.h`) | 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, 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` and the trampoline in `BOOTX64.EFI`). `vesa_stage.S` clears the boot-info magic; `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. 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" and "Files" 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. - **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: `r8168.c` RTL8111/8168 (PCIe, polled, C+ mode, 64-entry RX ring) and `ne2000.c` RTL8029 (QEMU/ISA)). `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). `usb_hcd.h` is the host-controller ops vtable; `uhci.c` (I/O-port UHCI, frame list at `0x3000`, one instance) and `ohci.c` (MMIO OHCI, up to 4 instances, HCCA + ED/TD lists, polling) implement it. `lsusb.c` — the `lsusb` command (lists every controller and its tree). The devices work on both controller types 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` — HLT/C1 by default, `idle c2`/`idle c3` (and the `c2ap`/`c3ap` AP-only variants) switch to MONITOR/MWAIT at runtime (the old USB-legacy SMM hang is addressed by the UHCI/OHCI `0xC0` legacy-SMI disable; test the keyboard before making it the default). 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. - **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. TjMax is table-driven (Atom 330 = 125 °C, 230 = 100, other Bonnell = 90, otherwise 100) because Bonnell has no `IA32_TEMPERATURE_TARGET`. 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. - **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`, like `hello.elf`), 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`, `ramfs.c/h` — freestanding ELFs linked at `USER_BASE` (`0x40000000`), packed by `mkpack` into `cmds.pack` (as `bin/`), embedded in the kernel image (`cmds_pack.o`) and 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. 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` (buttons, 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. - **Browser**: `ucmd_browser.c` is a tiny `bin/browser` launcher; the real browser is the external `BROWSER` on `root.img` (also looked up in `/share` and on IDE/SATA FAT mounts) because it links ngui, the full image library, inflate, TLS and uhttp and would not fit the compressed command pack. The launcher forwards its argument and cwd; `make run`/`run-net` attach `root.img`, and a netbooted board can upload `browser.elf` to `/share` (`make browser-dev` uses the board's `websrv`; stop `websrv` before browsing HTTP, because it owns the NIC). `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 `