Selaa lähdekoodia

Remove various legacy code and introduce docs pages

Johannes Zellner 1 viikko sitten
vanhempi
sitoutus
2538f5201d
45 muutettua tiedostoa jossa 4817 lisäystä ja 2871 poistoa
  1. 107 62
      AGENTS.md
  2. 4 17
      Makefile
  3. 2 2
      browser.c
  4. 419 0
      docs/boot.html
  5. 370 0
      docs/cpu.html
  6. 347 0
      docs/development.html
  7. 383 0
      docs/drivers.html
  8. 12 0
      docs/favicon.svg
  9. 400 0
      docs/filesystems.html
  10. 326 0
      docs/graphics.html
  11. 295 0
      docs/index.html
  12. 327 0
      docs/memory.html
  13. 336 0
      docs/network.html
  14. 987 0
      docs/style.css
  15. 344 0
      docs/userland.html
  16. 1 1
      efi/efi.h
  17. 2 2
      efi/main.c
  18. 1 69
      io.c
  19. 0 7
      io.h
  20. 5 12
      kernel.c
  21. 1 1
      netkexec_send.c
  22. 2 13
      process.c
  23. 4 8
      process.h
  24. 1 42
      screen.c
  25. 3 19
      screen.h
  26. 0 281
      sys_gfx.c
  27. 0 22
      sys_gfx.h
  28. 5 0
      sys_wm.c
  29. 1 0
      sys_wm.h
  30. 1 13
      syscall.c
  31. 1 18
      syscall.h
  32. 6 1001
      terminal.c
  33. 0 49
      terminal.h
  34. 2 2
      testdata/browser/demo.html
  35. 0 118
      text_canvas.c
  36. 0 28
      text_canvas.h
  37. 0 233
      text_canvas_test.c
  38. 0 25
      ucmd_lib.h
  39. 1 1
      ucmd_solitaire.c
  40. 3 3
      ucmd_websrv.c
  41. 16 0
      ucmd_wm.c
  42. 1 1
      version.h
  43. 95 799
      wm.c
  44. 5 22
      wm.h
  45. 1 0
      wm_abi.h

+ 107 - 62
AGENTS.md

@@ -1,9 +1,52 @@
-# AGENTS.md — Nebs OS (`nebos`)
+# 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, no libc).
 Targets i586 (first-gen Pentium); runs under QEMU or on real hardware.
 
+## Documentation site (`docs/`)
+
+`docs/` is the static architecture site: hand-written HTML5, one shared
+`style.css` and a small hand-written SVG favicon, with no JavaScript, no build
+step and no external fonts or CDNs. Open
+`docs/index.html` directly (`file://` works) or serve it with
+`python3 -m http.server -d docs`.
+
+Keep the site in the same change as the code.  Architecture changes belong in
+this file **and** the matching page:
+
+| Page | Covers |
+|------|--------|
+| `docs/index.html` | Overview, layer diagram, at-a-glance numbers, subsystem map |
+| `docs/boot.html` | BIOS/VESA, MBR, UEFI loader, kexec, boot info, image layout |
+| `docs/memory.html` | Address map, E820/bitmap allocator, paging, MTRR, user arenas |
+| `docs/cpu.html` | GDT/TSS, interrupts, ACPI/SMP, CFS-lite, BKL, idle/power |
+| `docs/drivers.html` | PCI, FDC/PATA/AHCI, USB core + UHCI/OHCI/EHCI/xHCI, HID, sensors |
+| `docs/filesystems.html` | VFS/`fs_ops`, FAT, ramfs pack, `/share`, WebDAV |
+| `docs/graphics.html` | VBE/shadow, damage, blit, WM, canvas ABI, ngui, images |
+| `docs/network.html` | netdev, ARP/ICMP/UDP/DHCP/DNS, TCP, TLS, netconsole/netkexec |
+| `docs/userland.html` | Ring-3 model, ELF spawn, syscalls, shell/PATH, pack, apps |
+| `docs/development.html` | Toolchain, make targets, hot reload, tests, debugging |
+
+Rules:
+
+- A change to a boot path, hardcoded address, scheduler/ABI, driver model,
+  file service, graphics/WM path, protocol, syscall number, build target or
+  reload workflow must update the corresponding page in the same change.  A
+  new subsystem needs a section on an existing page (or a new page linked from
+  the index) and a card on `docs/index.html`.
+- Update `AGENTS.md` whenever the architecture or a documented invariant
+  changes; `AGENTS.md` and `docs/` are both source-of-truth maps and must not
+  drift.  Each page's "Source map" lists the files it documents; keep it
+  current.
+- Charts and diagrams are hand-written HTML/CSS or inline SVG.  No JavaScript,
+  CDN, generated asset or build step.  Every charted number must come from a
+  source constant/table; cite the defining file in the caption or source map.
+- Keep internal links working, the active nav item correct, the layout usable
+  from a phone width to a wide desktop, and the site readable from `file://`.
+- Keep version strings in the page heads and footers in sync with
+  `OS_NAME`/`OS_VERSION` in `version.h`.
+
 ## Build & run
 
 Toolchain: `gcc` (32-bit multilib), `as`/`ld`/`objcopy`, `mtools` (`mcopy`/`mkfs.fat`), `qemu`.
@@ -158,7 +201,7 @@ run area), so adding code no longer moves any address.
 
 - **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
+  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
@@ -225,41 +268,47 @@ run area), so adding code no longer moves any address.
   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.
+- **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.  `terminal.c` keeps the privileged
+  kernel command registry for the ring-3 terminal (`SYS_SPAWN_KCMD` /
+  `term_kcmd_spawn`), but the kernel terminal entry/shell and the cell-window
+  ABI are gone.
+- **Window canvas API**: `gfx.c/h` allocates the RGB565 front/back canvases;
+  `sys_wm.c` is the ABI bridge.  `SYS_WIN_CREATE` gives a command its window
+  canvas mapped RW at `USER_WIN_BASE` (`0x50000000`); `SYS_WIN_PRESENT` copies
+  the back buffer into the front canvas with interrupts off, so a half-drawn
+  frame can never reach the screen.  `SYS_WIN_INFO`, `SYS_WIN_ACK_RESIZE`,
+  `SYS_WIN_POINTER`, `SYS_WIN_EVENT`, `SYS_WIN_KEY_WAIT` and the generic
+  `SYS_KEY_POLL` handle input.  The WM composites the front canvas; presented
+  frames carry monotonic seq counters, so the WM can never lose one.  Closing
+  a window kills its owner; the reaper frees the canvas.  `clock`, `colors`,
+  `term`, `files` and the other apps are canvas clients.  The old
+  `SYS_GFX_BEGIN/PRESENT/END` terminal-takeover service and the kernel
+  text-canvas renderer are removed.  Pointer input: `SYS_WIN_POINTER` reports
+  the content-relative position, buttons and focus, and `SYS_WIN_EVENT` queues
+  press/release edges with a capture window, so a click that starts in a
+  window still gets its release after the pointer leaves.  The userland
+  `ngui.c/h` immediate-mode toolkit builds on those: clipped RGB565
+  primitives, buttons, text input, procedural icons and scrolling panes.
+  `files` (`ucmd_files.c`) is its first user; `gallery` (`gallery.c`) is the
+  live showcase of every control and primitive the toolkit exports.  Buttons
+  fire on the release edge and keep `active` until `ui->released`: inferring
+  release from the sampled `ui->buttons` races the WM event queue and drops
+  clicks.  Text fields support mouse drag-selection, double-click select-all,
+  Ctrl+Left/Right word jumps, Ctrl+Delete/Ctrl+Backspace word deletion and
+  Ctrl+A select-all; typing or Backspace/Delete replaces a selection.  At the
+  end of the line Ctrl+Delete removes the word before the caret instead of
+  doing nothing.
 - **Graphics**: `vga.c/h`, `vga_copy.S`, `blit.c/h`, `gpu.c`, `ati.c`, `nvidia.c`,
   `nv50.c`, `pci.h` — VESA LFB + shadow buffer.  Drawing goes into a
   `struct surface` render target: `vga_target()` is the screen's shadow buffer
@@ -305,25 +354,21 @@ run area), so adding code no longer moves any address.
   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.
+  framebuffer glyph blitting (`fbtext_draw_cells`) and the boot-console cell
+  buffer (`screen.c`, used by `io.c`'s fallback screen and `bootcon`).  The
+  ring-3 terminal renders its own rows into its canvas; the kernel window
+  manager has no text-cell content path.  `screen_damage_*` remains for the
+  boot console's own bookkeeping.
+- **Shell**: `ucmd_term.c` is the windowed shell (rows, scrollback, Tab,
+  builtins `cd`, `path`, `help`, `clear`).  `terminal.c` keeps the privileged
+  kernel command registry and `term_kcmd_spawn()` used through `SYS_SPAWN_KCMD`;
+  commands are files on the terminal PATH (`/ramfs/bin` by default), so a
+  packed command can shadow a kernel one.  The in-kernel terminal entry point
+  (`term_entry()`, `term_run()`) is gone.
 - **Fatal exception screen**: `panic.c/h`, `timer.S` — on a ring-0 fault,
   dumps vector/error code, GPRs, CRs, EIP instruction bytes and stack
   return-address candidates straight into the LFB (and COM1) before halting;
   see the panic section below.
-- **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
@@ -382,7 +427,7 @@ run area), so adding code no longer moves any address.
   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
+  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`
@@ -639,7 +684,7 @@ run area), so adding code no longer moves any address.
   net users, so being preempted mid-wait is safe.
 
   The server side is the WebDAV command: `tcp.c` has a small listener (one
-  active connection + 7 queued ones, SYN-ACK/RST, and a fast FIN that keeps
+  active connection + 3 backlog/closing slots, SYN-ACK/RST, and a fast FIN that keeps
   the tuple briefly so a late FIN/ACK is absorbed).  The SYN-ACK advertises a
   zero window; a queued connection may hold 1 KB of early request (usually
   the HTTP headers), `tcp_srv_accept()` opens the window, and the update is
@@ -686,7 +731,7 @@ set the resolver) and `host <name>` (one DNS A query).  `curl <url>` fetches
 status line, headers and body (redirects are followed, up to 5 hops; numeric
 hosts skip DNS).  `https` uses the phase-A TLS 1.3 client (no certificate
 verification; the leaf fingerprint is printed).  On
-boot, if a NIC is present, a DHCP client runs with a 3 s budget (requesting the
+boot, if a NIC is present, a DHCP client runs with a 4 s budget (requesting the
 current address) and falls back to the static default when no server answers.
 The board also answers ARP/ICMP for its IP while idle.
 `lspci` lists every PCI function (one line each); with a filter (`lspci 8168`,
@@ -742,7 +787,7 @@ make dev            # kernel.bin + cmds_pack_gz.bin (atomic; ~46 s at 115200)
 make kernel-dev     # kernel only; the new kernel keeps the running rootfs
 make cmds-dev       # runtime raw-pack update, no reboot
 ```
-The reload is automatic. On boot the kernel prints `Nebs OS v<version> booted`
+The reload is automatic. On boot the kernel prints `NebOS v<version> booted`
 to COM1, so a serial monitor can confirm the new build headlessly:
 
 ```sh
@@ -1010,7 +1055,7 @@ directly at boot — no keystroke injection needed:
      -display none -vga std
    # ...then: cat -A /tmp/opencode/serial.log
    ```
-   The `Nebs OS v<version> booted` line is already written to COM1 at boot, so
+   The `NebOS v<version> booted` line is already written to COM1 at boot, so
    serial is live before the framebuffer is up — a crash in early init still shows.
 4. **Revert before committing** — remove the `io.c` echo and any boot-time call;
    `git status` should show `io.c` and `kernel.c` unchanged.
@@ -1146,9 +1191,9 @@ and the WM falls back to polling (`io_keyboard_irq_masked()`).
     non-network driver wait or a big shadow-buffer operation can stall syscalls
     on the other CPUs for its duration.  `bkl_pause()`/`bkl_resume()` is used
     for serial/network waits, not yet for disk I/O.
-13. Kernel threads (kworker, kexec/payload, kernel commands, the kernel WM
-    fallback) are pinned to the BSP.  Only ring-3 processes use the APs, so a
-    single CPU-bound kernel driver still limits throughput.
+13. Kernel threads (kworker, kexec/payload, kernel commands) are pinned to
+    the BSP.  Only ring-3 processes use the APs, so a single CPU-bound kernel
+    driver still limits throughput.
 14. Page-table updates for another CPU's running process (e.g. an MMIO mapping)
     rely on not-present TLB entries not being cached; there is no cross-CPU
     TLB shootdown.  No process shares an address space with another, so normal
@@ -1168,8 +1213,8 @@ and the WM falls back to polling (`io_keyboard_irq_masked()`).
     also open extensionless files in the viewer.  Automatic decode-at-scale
     for oversized images is still missing.
 
-18. WebDAV limits: one request at a time (one active connection plus 7
-    queued; the queue holds each connection's first 1 KB with a zero window),
+18. WebDAV limits: one request at a time (one active connection plus 3
+    backlog/closing slots; the queue holds each connection's first 1 KB with a zero window),
     files are buffered whole (4 MB cap; a larger PUT gets 413), directory
     `MOVE` is 501, `PROPPATCH` is answered 200 without persisting, and there
     is no authentication.  Sends use a four-segment window, and keep-alive is

+ 4 - 17
Makefile

@@ -31,7 +31,7 @@ EFI_LDFLAGS = -nostdlib -Wl,--subsystem,10 -Wl,-e,efi_main \
               -Wl,--image-base,0x0 -Wl,--dynamicbase \
               -Wl,--enable-reloc-section -Wl,--no-insert-timestamp
 
-.PHONY: all clean run run-smp run-floppy run-usb run-uhci run-ehci run-ehci-asix run-xhci run-xhci-asix run-net run-e1000 run-ahci test-usb run-serial floppy usb uefi run-uefi test-uefi flash space prog bootstrap dev net-dev cmds-dev net-cmds browser-dev gallery-dev netmon monitor test-crypto test-images test-images-asan test-textcanvas kernel-dev kernel-net-dev rootfs
+.PHONY: all clean run run-smp run-floppy run-usb run-uhci run-ehci run-ehci-asix run-xhci run-xhci-asix run-net run-e1000 run-ahci test-usb run-serial floppy usb uefi run-uefi test-uefi flash space prog bootstrap dev net-dev cmds-dev net-cmds browser-dev gallery-dev netmon monitor test-crypto test-images test-images-asan kernel-dev kernel-net-dev rootfs
 
 all: floppy.img usb.img final.bin root.img
 
@@ -56,9 +56,6 @@ font_8x8.o: font_8x8.c font_8x8.h
 font_8x16.o: font_8x16.c font_8x16.h
 	$(CC) $(CFLAGS) -o $@ $<
 
-text_canvas.o: text_canvas.c text_canvas.h font_8x16.h
-	$(CC) $(CFLAGS) -o $@ $<
-
 fbtext.o: fbtext.c fbtext.h font_8x8.h vga.h
 	$(CC) $(CFLAGS) -o $@ $<
 
@@ -161,9 +158,6 @@ mtrr.o: mtrr.c mtrr.h serial.h
 gfx.o: gfx.c gfx.h mm.h vga.h
 	$(CC) $(CFLAGS) -o $@ $<
 
-sys_gfx.o: sys_gfx.c sys_gfx.h gfx.h paging.h process.h wm.h wm_abi.h syscall.h
-	$(CC) $(CFLAGS) -o $@ $<
-
 display.o: display.c io.h vga.h gpu.h ati.h nvidia.h radeon.h mouse.h fbtext.h
 	$(CC) $(CFLAGS) -o $@ $<
 
@@ -347,7 +341,7 @@ sys_net.o: sys_net.c sys_net.h syscall.h dhcp.h dns.h net.h netdev.h netlog.h pr
 syscall_stub.o: syscall_stub.S irqret.inc
 	$(AS) $(ASFLAGS) -o $@ $<
 
-kernel.elf: kernel.ld vesa_stage.o entry.o kernel.o timer.o switch.o sched.o process.o mm.o kmalloc.o paging.o elf.o tss.o syscall.o sys_wm.o syscall_stub.o screen.o io.o tty.o rtc.o terminal.o wm.o reboot.o poweroff.o disk.o fat.o run.o serial.o serial_ring_buf.o serial_loop.o serial_recv.o bin_recv.o vga.o blit.o cpu.o thermal.o it87.o tpec.o power.o vga_copy.o gfxbench.o gpu.o ati.o cirrus.o intel.o nvidia.o nv50.o radeon.o mtrr.o font_8x8.o font_8x16.o text_canvas.o fbtext.o gfx.o sys_gfx.o display.o mouse.o uhci.o ohci.o ehci.o xhci.o asix.o usb.o usbhid.o lsusb.o panic.o bootcon.o blkdev.o ata.o ahci.o fatdetect.o fatformat.o format.o vfs.o sys_fs.o sys_info.o sys_mem.o sys_net.o idle.o kexec.o kexec_tramp.o dbg.o lspci.o peek.o ne2000.o r8168.o e1000e.o netdev.o net.o netkexec.o netlog.o dhcp.o dns.o tcp.o acpi.o lapic.o smp.o ap_tramp_embed.o prog_embed.o space_embed.o inflate.o ramfs.o share.o payload.o
+kernel.elf: kernel.ld vesa_stage.o entry.o kernel.o timer.o switch.o sched.o process.o mm.o kmalloc.o paging.o elf.o tss.o syscall.o sys_wm.o syscall_stub.o screen.o io.o tty.o rtc.o terminal.o wm.o reboot.o poweroff.o disk.o fat.o run.o serial.o serial_ring_buf.o serial_loop.o serial_recv.o bin_recv.o vga.o blit.o cpu.o thermal.o it87.o tpec.o power.o vga_copy.o gfxbench.o gpu.o ati.o cirrus.o intel.o nvidia.o nv50.o radeon.o mtrr.o font_8x8.o fbtext.o gfx.o display.o mouse.o uhci.o ohci.o ehci.o xhci.o asix.o usb.o usbhid.o lsusb.o panic.o bootcon.o blkdev.o ata.o ahci.o fatdetect.o fatformat.o format.o vfs.o sys_fs.o sys_info.o sys_mem.o sys_net.o idle.o kexec.o kexec_tramp.o dbg.o lspci.o peek.o ne2000.o r8168.o e1000e.o netdev.o net.o netkexec.o netlog.o dhcp.o dns.o tcp.o acpi.o lapic.o smp.o ap_tramp_embed.o prog_embed.o space_embed.o inflate.o ramfs.o share.o payload.o
 	$(LD) $(KERNEL_LDFLAGS) -o $@ $(filter-out kernel.ld,$^)
 
 MBR_LDFLAGS = -T mbr.ld -nostdlib -m elf_i386
@@ -717,13 +711,6 @@ test-images-asan: $(IMGTEST_SRCS) $(IMGTEST_DEPS)
 	gcc -O1 -g -fwrapv -fsanitize=address,undefined -I. -o img_test_asan $(IMGTEST_SRCS)
 	./img_test_asan
 
-# Host test for the 8x16 terminal-cell renderer (text_canvas.c).
-text_canvas_test: text_canvas_test.c text_canvas.c text_canvas.h font_8x16.c font_8x16.h
-	gcc -O2 -Wall -Wextra -I. -o $@ text_canvas_test.c text_canvas.c font_8x16.c
-
-test-textcanvas: text_canvas_test
-	./text_canvas_test
-
 mkpack: mkpack.c
 	gcc -O2 -o $@ $<
 
@@ -967,7 +954,7 @@ run-serial:
 
 monitor:
 	@echo "Watching $(SERIAL_DEV) @ $(SERIAL_BAUD) baud (Ctrl-A Ctrl-X to exit)."
-	@echo "Each 'make dev' reload prints: Nebs OS v<version> booted"
+	@echo "Each 'make dev' reload prints: NebOS v<version> booted"
 	picocom $(SERIAL_DEV) --baud $(SERIAL_BAUD)
 
 send: $(PROGRAM).bin send_serial
@@ -1051,4 +1038,4 @@ kernel-net-dev: kernel.bin netkexec_send
 	./netkexec_send $(BOARD_IP) $(NETKEXEC_PORT) 0x$$entry kernel.bin
 
 clean:
-	rm -f boot.o vesa_stage.o entry.o kernel.o timer.o switch.o sched.o process.o mm.o kmalloc.o paging.o elf.o tss.o syscall.o sys_wm.o syscall_stub.o screen.o io.o tty.o rtc.o terminal.o wm.o hello.o reboot.o poweroff.o fat.o run.o disk.o serial.o serial_ring_buf.o serial_loop.o serial_recv.o bin_recv.o vga.o blit.o cpu.o thermal.o it87.o tpec.o power.o vga_copy.o gfxbench.o gpu.o ati.o cirrus.o intel.o nvidia.o nv50.o radeon.o mtrr.o font_8x8.o font_8x16.o text_canvas.o fbtext.o gfx.o sys_gfx.o display.o mouse.o uhci.o ohci.o ehci.o xhci.o asix.o usb.o usbhid.o lsusb.o panic.o bootcon.o blkdev.o ata.o ahci.o fatdetect.o fatformat.o format.o vfs.o sys_fs.o sys_info.o sys_mem.o inflate.o idle.o kexec.o kexec_tramp.o dbg.o lspci.o peek.o ne2000.o r8168.o e1000e.o netdev.o net.o netkexec.o netlog.o dhcp.o dns.o tcp.o acpi.o lapic.o smp.o ap_tramp.o ap_tramp.elf ap_tramp.bin ap_tramp_embed.o mbr.o boot.elf kernel.elf mbr.elf boot.bin mbr.bin kernel.bin boot.bin.tmp boot.bin.patched image.bin floppy.img usb.img final.bin root.img prog.o prog.elf prog.bin space.o space.elf space.bin hello.elf hello_embed.o prog_embed.o space_embed.o cmds.pack cmds_pack_gz.bin cmds_pack.o rootfs.bin cmds.img mkrootfs ramfs.o share.o payload.o mkpack uwm_lib.o ngui.o img.o img_mem.o img_blit.o img_png.o img_bmp.o img_gif.o img_jpeg.o img_tga.o img_pnm.o img_ico.o img_pam.o img_gif_anim.o img_file.o browser.o browser_html.o uhttp.o browser.elf img_test img_test_asan text_canvas_test *.boot.tmp $(addsuffix .o,$(UCMDS)) $(addsuffix .elf,$(UCMDS)) gallery.o gallery.elf $(TLSLIB_OBJS) tls_test bootstrap.o bootstrap.elf bootstrap.bin send_serial kexec_send netkexec_send netmonitor BOOTX64.EFI esp.img usb-efi.img efi/main.o efi/payload.o efi/tramp.o efi/tramp.elf efi/tramp.bin efi/efi_entry.h
+	rm -f boot.o vesa_stage.o entry.o kernel.o timer.o switch.o sched.o process.o mm.o kmalloc.o paging.o elf.o tss.o syscall.o sys_wm.o syscall_stub.o screen.o io.o tty.o rtc.o terminal.o wm.o hello.o reboot.o poweroff.o fat.o run.o disk.o serial.o serial_ring_buf.o serial_loop.o serial_recv.o bin_recv.o vga.o blit.o cpu.o thermal.o it87.o tpec.o power.o vga_copy.o gfxbench.o gpu.o ati.o cirrus.o intel.o nvidia.o nv50.o radeon.o mtrr.o font_8x8.o font_8x16.o fbtext.o gfx.o display.o mouse.o uhci.o ohci.o ehci.o xhci.o asix.o usb.o usbhid.o lsusb.o panic.o bootcon.o blkdev.o ata.o ahci.o fatdetect.o fatformat.o format.o vfs.o sys_fs.o sys_info.o sys_mem.o inflate.o idle.o kexec.o kexec_tramp.o dbg.o lspci.o peek.o ne2000.o r8168.o e1000e.o netdev.o net.o netkexec.o netlog.o dhcp.o dns.o tcp.o acpi.o lapic.o smp.o ap_tramp.o ap_tramp.elf ap_tramp.bin ap_tramp_embed.o mbr.o boot.elf kernel.elf mbr.elf boot.bin mbr.bin kernel.bin boot.bin.tmp boot.bin.patched image.bin floppy.img usb.img final.bin root.img prog.o prog.elf prog.bin space.o space.elf space.bin hello.elf hello_embed.o prog_embed.o space_embed.o cmds.pack cmds_pack_gz.bin cmds_pack.o rootfs.bin cmds.img mkrootfs ramfs.o share.o payload.o mkpack uwm_lib.o ngui.o img.o img_mem.o img_blit.o img_png.o img_bmp.o img_gif.o img_jpeg.o img_tga.o img_pnm.o img_ico.o img_pam.o img_gif_anim.o img_file.o browser.o browser_html.o uhttp.o browser.elf img_test img_test_asan *.boot.tmp $(addsuffix .o,$(UCMDS)) $(addsuffix .elf,$(UCMDS)) gallery.o gallery.elf $(TLSLIB_OBJS) tls_test bootstrap.o bootstrap.elf bootstrap.bin send_serial kexec_send netkexec_send netmonitor BOOTX64.EFI esp.img usb-efi.img efi/main.o efi/payload.o efi/tramp.o efi/tramp.elf efi/tramp.bin efi/efi_entry.h

+ 2 - 2
browser.c

@@ -1594,7 +1594,7 @@ static void load_home(int push)
 	browser_rules_alloc();
 	{
 		static const char home[] =
-			"<html><head><title>Nebs Browser</title><style>"
+			"<html><head><title>NebOS Browser</title><style>"
 			"body { margin: 10px; color: #e4e6f0; }"
 			"h1 { color: #7fb0ff; }"
 			".box { background-color: #262b3a; margin: 12px; "
@@ -1602,7 +1602,7 @@ static void load_home(int push)
 			"a { color: #7fb0ff; }"
 			"pre { background-color: #32384a; }"
 			"</style></head><body>"
-			"<h1>Nebs Browser</h1>"
+			"<h1>NebOS Browser</h1>"
 			"<p>A small HTML/CSS browser built on <b>ngui</b>, the "
 			"shared HTTP client and the image library.</p>"
 			"<div class=\"box\"><b>Try:</b>"

+ 419 - 0
docs/boot.html

@@ -0,0 +1,419 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Boot | NebOS Architecture</title>
+<meta name="description" content="NebOS boot chain: BIOS boot sector and VESA stage, UEFI loader, kexec reload, boot-info handoff and disk image layout.">
+<link rel="icon" href="favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+
+<header class="site-header">
+	<a class="brand" href="index.html">
+		<span class="brand-mark" aria-hidden="true"></span>
+		<span>NebOS <span class="brand-sub">Architecture</span></span>
+	</a>
+	<nav class="site-nav" aria-label="Architecture sections">
+		<a href="index.html">Overview</a>
+		<a href="boot.html" aria-current="page">Boot</a>
+		<a href="memory.html">Memory</a>
+		<a href="cpu.html">CPU</a>
+		<a href="drivers.html">Drivers</a>
+		<a href="filesystems.html">Filesystems</a>
+		<a href="graphics.html">Graphics</a>
+		<a href="network.html">Network</a>
+		<a href="userland.html">Userland</a>
+		<a href="development.html">Development</a>
+	</nav>
+</header>
+
+<main id="main" class="page">
+	<div class="page-head">
+		<p class="kicker">Boot &amp; firmware</p>
+		<h1>Three ways into the same kernel.</h1>
+		<p class="lede">
+			A legacy BIOS floppy, a dual-boot USB image under UEFI, and a live
+			serial or network reload all converge on <code>kernel_entry</code>.
+			They must agree on three things: the low-memory boot structures, the
+			rootfs pack location, and a 32-bit flat protected-mode environment.
+		</p>
+		<div class="meta">
+			<span class="pill">512-byte boot sector</span>
+			<span class="pill">real-mode VESA stage</span>
+			<span class="pill">x86-64 UEFI loader</span>
+			<span class="pill">kexec hot reload</span>
+		</div>
+	</div>
+
+	<nav class="toc" aria-label="On this page">
+		<h2>On this page</h2>
+		<ul>
+			<li><a href="#overview">Boot paths</a></li>
+			<li><a href="#bios">BIOS path</a></li>
+			<li><a href="#uefi">UEFI path</a></li>
+			<li><a href="#kexec">kexec path</a></li>
+			<li><a href="#handoff">Handoff contract</a></li>
+			<li><a href="#images">Image layout</a></li>
+			<li><a href="#init">Kernel init order</a></li>
+			<li><a href="#failures">Failure modes</a></li>
+			<li><a href="#sources">Source map</a></li>
+		</ul>
+	</nav>
+
+	<section id="overview">
+		<h2>Three paths, one entry point</h2>
+		<p>
+			The boot code is deliberately split by execution mode. The BIOS path
+			starts in 16-bit real mode, the UEFI path starts in 64-bit long mode,
+			and the kexec path starts in the running 32-bit kernel. All three end
+			at <code>kernel_entry</code> in <span class="file">entry.S</span>,
+			which immediately re-points <code>ESP</code> at the new image's own
+			boot stack before calling <code>kernel_main</code>.
+		</p>
+
+		<figure class="figure">
+			<svg viewBox="0 0 920 390" role="img" aria-labelledby="paths-title paths-desc">
+				<title id="paths-title">Three NebOS boot paths</title>
+				<desc id="paths-desc">BIOS boot sector to VESA stage to kernel entry; UEFI BOOTX64.EFI to trampoline to kernel entry; kexec receiver to trampoline to kernel entry.</desc>
+
+				<rect class="svg-box blue" x="16" y="18" width="250" height="76" rx="8"/>
+				<text class="svg-text" x="36" y="46">BIOS · floppy / USB</text>
+				<text class="svg-sub" x="36" y="66">boot.S at 0x7C00 → vesa_stage.S</text>
+				<text class="svg-sub" x="36" y="82">real mode → protected mode</text>
+
+				<rect class="svg-box green" x="16" y="152" width="250" height="76" rx="8"/>
+				<text class="svg-text" x="36" y="180">UEFI · usb-efi.img</text>
+				<text class="svg-sub" x="36" y="200">BOOTX64.EFI · x86-64</text>
+				<text class="svg-sub" x="36" y="216">GOP + GetMemoryMap</text>
+
+				<rect class="svg-box amber" x="16" y="286" width="250" height="76" rx="8"/>
+				<text class="svg-text" x="36" y="314">kexec · make dev / net-dev</text>
+				<text class="svg-sub" x="36" y="334">KXE2 serial · KXN2 UDP</text>
+				<text class="svg-sub" x="36" y="350">running kernel receives image</text>
+
+				<path class="svg-line blue" d="M266 56h94"/>
+				<path class="svg-line blue" d="M354 50l7 6-7 6"/>
+
+				<path class="svg-line green" d="M266 190h94"/>
+				<path class="svg-line green" d="M354 184l7 6-7 6"/>
+
+				<path class="svg-line amber" d="M266 324h94"/>
+				<path class="svg-line amber" d="M354 318l7 6-7 6"/>
+
+				<rect class="svg-box" x="360" y="18" width="228" height="76" rx="8"/>
+				<text class="svg-text" x="380" y="46">VESA stage</text>
+				<text class="svg-sub" x="380" y="66">E820 · VBE mode · rootfs</text>
+				<text class="svg-sub" x="380" y="82">0x500 / 0x600 / 0x1000</text>
+
+				<rect class="svg-box" x="360" y="152" width="228" height="76" rx="8"/>
+				<text class="svg-text" x="380" y="180">UEFI trampoline</text>
+				<text class="svg-sub" x="380" y="200">0x800 · leave IA-32e</text>
+				<text class="svg-sub" x="380" y="216">kernel copy to 0x7E00</text>
+
+				<rect class="svg-box" x="360" y="286" width="228" height="76" rx="8"/>
+				<text class="svg-text" x="380" y="314">kexec trampoline</text>
+				<text class="svg-sub" x="380" y="334">APs parked · copy kernel</text>
+				<text class="svg-sub" x="380" y="350">keep framebuffer</text>
+
+				<path class="svg-line accent" d="M588 56h110v139"/>
+				<path class="svg-line accent" d="M588 190h110v5"/>
+				<path class="svg-line accent" d="M588 324h110v-129"/>
+				<path class="svg-line accent" d="M692 188l6 7 6-7"/>
+
+				<rect class="svg-box accent" x="620" y="136" width="280" height="108" rx="9"/>
+				<text class="svg-text" x="642" y="166">kernel_entry · entry.S</text>
+				<text class="svg-sub" x="642" y="188">ESP = __boot_stack_top</text>
+				<text class="svg-sub" x="642" y="208">jmp kernel_main</text>
+				<text class="svg-sub" x="642" y="228">32-bit flat · paging off</text>
+			</svg>
+			<figcaption>
+				<strong>Every path hands off in the same shape:</strong> flat
+				32-bit segments, paging off, the framebuffer block at
+				<code>0x600</code>, the boot-info block at <code>0x500</code>, and
+				the kernel loaded at <code>0x7E00</code>.
+			</figcaption>
+		</figure>
+	</section>
+
+	<section id="bios">
+		<h2>BIOS path</h2>
+
+		<h3><span class="file">boot.S</span> — the 512-byte boot sector</h3>
+		<p>
+			The boot sector carries a FAT16 BPB, loads the contiguous kernel
+			directly after itself to <code>0x7E00</code>, and jumps there.
+			Floppy drives use CHS; fixed disks use <code>INT 13h AH=42h</code>
+			(EDD LBA). The sector count and the rootfs LBA are patched into the
+			boot sector by the Makefile.
+		</p>
+		<p>
+			On the USB image, <span class="file">mbr.S</span> runs first and
+			loads the active partition's boot sector at LBA 63. From there the
+			path is identical.
+		</p>
+
+		<h3><span class="file">vesa_stage.S</span> — the real-mode setup</h3>
+		<p>
+			The VESA stage is the busiest piece of the legacy chain. It runs in
+			real mode at <code>0x7E00</code> and performs five jobs:
+		</p>
+		<ol>
+			<li>Probe the <code>INT 15h</code> E820 memory map into <code>0x1000</code>.</li>
+			<li>Read the <code>NBROOT1</code> rootfs header at the boot sector's <code>pack_lba</code> field.</li>
+			<li>Stage the compressed pack in the low gap <code>0x60000..0x9FBFF</code>, using 16 KB staging chunks at <code>0x3000</code> and <code>rep movsb</code>. No protected-mode BIOS call is required.</li>
+			<li>Pick the best VBE mode: at least 16 bpp, a linear framebuffer, it must fit the card's VRAM, and the width must be at most 1280 pixels. Mode information is written to <code>0x600</code>; the 12-dword boot-info block goes to <code>0x500</code>.</li>
+			<li>Enable A20, enter protected mode, copy the pack to <code>0x900000</code> above the 8 MB VGA-shadow reserve, rewrite the boot-info pack address, and jump to <code>kernel_entry</code>.</li>
+		</ol>
+		<p>
+			The staging gap is why the compressed pack has a hard cap of
+			<code>0x3FBFF</code> (~255 KB), ending below the EBDA at
+			<code>0x9FC00</code>. The kernel image itself must stay below the
+			same gap, which <span class="file">kernel.ld</span> enforces with
+			link-time assertions.
+		</p>
+
+		<div class="note">
+			<p><strong>Why copy the pack again?</strong> The low gap is temporary:
+			the kernel BSS and boot stack may extend past <code>0x60000</code>.
+			Moving the pack to <code>0x900000</code> before <code>kernel_main</code>
+			keeps it safe until <span class="file">ramfs.c</span> takes a private
+			page-allocated copy and releases the boot region.</p>
+		</div>
+	</section>
+
+	<section id="uefi">
+		<h2>UEFI path</h2>
+		<p>
+			<span class="file">efi/main.c</span> is a freestanding x86-64 PE32+
+			application built with <code>x86_64-w64-mingw32-gcc</code>. It does
+			not execute any of the legacy boot chain. Instead it:
+		</p>
+		<ol>
+			<li>Selects a GOP mode with BGRX or RGBX 32bpp, width at most 1280, <code>pitch × height</code> at most 8 MB, and a framebuffer below 4 GB.</li>
+			<li>Calls <code>GetMemoryMap</code> and converts the firmware map into the kernel's E820 format at <code>0x1000</code>.</li>
+			<li>Stages the kernel image below 4 GB and writes the boot-info and framebuffer blocks.</li>
+			<li>Calls <code>ExitBootServices</code>, copies the embedded rootfs pack to the top of RAM below 128 MB, and copies a 192-byte trampoline to <code>0x800</code>.</li>
+			<li>Leaves IA-32e mode (clears <code>CR0.PG</code>, <code>EFER.LME</code>, <code>CR4.PAE/PGE/PCIDE/SMEP/SMAP/LA57</code>), copies the kernel to <code>0x7E00</code>, and jumps to <code>kernel_entry</code>.</li>
+		</ol>
+		<p>
+			<span class="file">efi/payload.S</span> embeds the compressed
+			kernel, the gzip rootfs pack and the trampoline inside
+			<code>BOOTX64.EFI</code>, so the ESP is self-contained. Secure Boot
+			must be off; the loader is unsigned.
+		</p>
+		<div class="warn">
+			<p><strong>No GOP, no video.</strong> If the loader cannot satisfy the
+			mode constraints it still boots, but the kernel starts headless and
+			only the serial log is available.</p>
+		</div>
+	</section>
+
+	<section id="kexec">
+		<h2>kexec path</h2>
+		<p>
+			kexec is the normal development loop: it replaces the running kernel
+			without rebooting, reflashing or re-running the firmware. The
+			framebuffer and its mode stay in place; only the image changes.
+		</p>
+		<ul>
+			<li><strong>Serial.</strong> The WM loop watches the COM1 ring buffer for the <code>KXE2</code> magic. The header carries entry, kernel size, pack size and a checksum; <code>pack_size == 0</code> keeps the running rootfs.</li>
+			<li><strong>Network.</strong> The same transfer runs over UDP port 19288 with the <code>KXN2</code> magic. The board acknowledges every datagram with the next expected offset and verifies a 32-bit checksum.</li>
+			<li><strong>Runtime pack only.</strong> <code>KXNP</code> over serial or network replaces <code>/ramfs</code> in place without touching the kernel.</li>
+		</ul>
+		<p>
+			Before jumping, <span class="file">kexec.c</span> calls
+			<code>smp_stop_aps()</code>: every AP receives an INIT and is parked in
+			the wait-for-SIPI state before the trampoline overwrites the kernel
+			they were executing. The trampoline runs with interrupts off, resets
+			<code>sched_lock</code> (an AP may have been inside a scheduler
+			critical section), and jumps to <code>kernel_entry</code>.
+		</p>
+		<p>
+			Because <span class="file">entry.S</span> re-points <code>ESP</code>
+			before any stack use, a reload between builds with different memory
+			maps cannot inherit a stale stack inside the new image.
+		</p>
+	</section>
+
+	<section id="handoff">
+		<h2>Handoff contract</h2>
+		<p>
+			<span class="file">bootinfo.h</span> defines the 12-dword block at
+			<code>0x500</code>. The checksum is chosen so all twelve words sum to
+			zero; that keeps stale low memory from being mistaken for a valid
+			block after a kexec or legacy boot.
+		</p>
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Offset</th><th>Field</th><th>Meaning</th></tr>
+				</thead>
+				<tbody>
+					<tr><td><code>+0</code></td><td><code>magic</code></td><td><code>0x4E425349</code> (<code>"NBSI"</code>)</td></tr>
+					<tr><td><code>+4</code></td><td><code>version</code></td><td>Currently 2.</td></tr>
+					<tr><td><code>+8</code></td><td><code>checksum</code></td><td>Makes the 12-word sum zero.</td></tr>
+					<tr><td><code>+12</code></td><td><code>rsdp</code></td><td>ACPI RSDP physical address; zero means scan.</td></tr>
+					<tr><td><code>+16</code></td><td><code>flags</code></td><td>EFI, RGBX pixel order, retained network config.</td></tr>
+					<tr><td><code>+20</code></td><td><code>pack_addr</code></td><td>Boot-time rootfs pack address, zero if none.</td></tr>
+					<tr><td><code>+24</code></td><td><code>pack_size</code></td><td>Exact gzip or raw pack byte count.</td></tr>
+					<tr><td><code>+28</code></td><td><code>reserved[5]</code></td><td>Reserved; the kexec path stores retained IP/mask/gateway/DNS here.</td></tr>
+				</tbody>
+			</table>
+		</div>
+		<p>
+			The framebuffer block at <code>0x600</code> is a
+			<code>struct vga_boot_fb_info</code> (<span class="file">vga.h</span>):
+			valid flag, LFB base, pitch, width, height, bpp and the RGBX flag.
+			The E820 map at <code>0x1000</code> is a
+			<code>struct e820_map</code> (<span class="file">mm.h</span>): magic,
+			count and up to 32 entries.
+		</p>
+	</section>
+
+	<section id="images">
+		<h2>Disk image layout</h2>
+		<p>
+			The build produces several images from the same boot sector, kernel
+			and rootfs. The layouts are intentionally conservative: the first
+			1.44 MB must remain readable by a CHS-only BIOS.
+		</p>
+
+		<figure class="figure">
+			<svg viewBox="0 0 920 342" role="img" aria-labelledby="images-title images-desc">
+				<title id="images-title">NebOS disk image layouts</title>
+				<desc id="images-desc">Floppy image: boot sector, kernel, rootfs, padding to 1.44 MB. USB image: MBR and boot partition, rootfs at LBA 1088, 9 MB total. Dual-boot image: the same 9 MB plus an 8 MB EFI system partition at LBA 18432.</desc>
+
+				<text class="svg-text" x="12" y="30">floppy.img</text>
+				<text class="svg-tiny" x="908" y="30" text-anchor="end">1.44 MB</text>
+				<rect class="svg-box accent" x="160" y="42" width="14" height="24" rx="3"/>
+				<rect class="svg-box blue" x="178" y="42" width="250" height="24" rx="3"/>
+				<rect class="svg-box green" x="432" y="42" width="210" height="24" rx="3"/>
+				<rect class="svg-box" x="646" y="42" width="244" height="24" rx="3"/>
+				<text class="svg-tiny" x="186" y="59">kernel</text>
+				<text class="svg-tiny" x="440" y="59">rootfs.bin</text>
+				<text class="svg-tiny" x="654" y="59">zero padding</text>
+
+				<text class="svg-text" x="12" y="106">usb.img</text>
+				<text class="svg-tiny" x="908" y="106" text-anchor="end">9 MB</text>
+				<rect class="svg-box amber" x="160" y="118" width="184" height="24" rx="3"/>
+				<rect class="svg-box green" x="416" y="118" width="474" height="24" rx="3"/>
+				<text class="svg-tiny" x="176" y="135">P1 · boot + kernel</text>
+				<text class="svg-tiny" x="424" y="135">partition 2 · rootfs · LBA 1088 · 8 MB</text>
+
+				<text class="svg-text" x="12" y="182">usb-efi.img</text>
+				<text class="svg-tiny" x="908" y="182" text-anchor="end">17 MB</text>
+				<rect class="svg-box amber" x="160" y="194" width="184" height="24" rx="3"/>
+				<rect class="svg-box green" x="416" y="194" width="250" height="24" rx="3"/>
+				<rect class="svg-box accent" x="670" y="194" width="220" height="24" rx="3"/>
+				<text class="svg-tiny" x="176" y="211">partition 1</text>
+				<text class="svg-tiny" x="424" y="211">partition 2 · rootfs</text>
+				<text class="svg-tiny" x="678" y="211">partition 3 · FAT16 ESP</text>
+
+				<text class="svg-text" x="12" y="258">rootfs container</text>
+				<text class="svg-tiny" x="908" y="258" text-anchor="end">8 MB cmds.img</text>
+				<rect class="svg-box amber" x="160" y="270" width="56" height="26" rx="3"/>
+				<rect class="svg-box green" x="220" y="270" width="670" height="26" rx="3"/>
+				<text class="svg-tiny" x="172" y="288">header</text>
+				<text class="svg-tiny" x="232" y="288">gzip command pack</text>
+
+				<line class="svg-line" x1="160" y1="314" x2="890" y2="314"/>
+				<text class="svg-tiny" x="160" y="334">Schematic, not to scale. The first 1.44 MB keeps the pack reachable by CHS-only USB BIOSes.</text>
+			</svg>
+			<figcaption>
+				<strong>Three images, one source tree.</strong> The dual-boot image
+				clears one BPB byte in the fake FAT16 header of partition 1 so UEFI
+				firmware does not mount the raw kernel blob as a volume and overwrite
+				it.
+			</figcaption>
+		</figure>
+
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Image</th><th>Size</th><th>Use</th></tr>
+				</thead>
+				<tbody>
+					<tr><td><code>floppy.img</code></td><td>1.44 MB</td><td>Floppy boot; boot sector + kernel + appended rootfs.</td></tr>
+					<tr><td><code>usb.img</code></td><td>9 MB</td><td>Legacy BIOS USB/IDE disk; MBR, boot partition at LBA 63, rootfs at LBA 1088.</td></tr>
+					<tr><td><code>usb-efi.img</code></td><td>17 MB</td><td>Dual boot; adds an 8 MB FAT16 ESP at LBA 18432 with <code>BOOTX64.EFI</code>.</td></tr>
+					<tr><td><code>final.bin</code></td><td>Varies</td><td>Raw boot sector + kernel + rootfs, written directly to a device.</td></tr>
+					<tr><td><code>root.img</code></td><td>1.44 MB</td><td>FAT12 second floppy with test programs and fallback browser/gallery.</td></tr>
+				</tbody>
+			</table>
+		</div>
+	</section>
+
+	<section id="init">
+		<h2>Kernel init order</h2>
+		<p>
+			<code>kernel_main</code> is a single linear bring-up. The order is
+			constrained by what each step needs: GDT/TSS before <code>current_proc()</code>,
+			paging before ACPI table access, process setup before the PIT can
+			context-switch, and a ticking timer before AP bring-up can time out.
+		</p>
+		<ol>
+			<li>Clear BSS; initialise the boot console straight into the framebuffer.</li>
+			<li>Bring up COM1 and the network-console ring buffer.</li>
+			<li>Install the GDT/TSS and per-CPU GS base.</li>
+			<li>Parse E820, build the frame bitmap and initialise <code>kmalloc</code>.</li>
+			<li>Enable paging; keep a RAM copy of the boot log; enable SSE state if present.</li>
+			<li>Parse ACPI/MADT; initialise I/O, power, idle, thermal and board sensors.</li>
+			<li>Create the process table, then start the PIT and verify it ticks.</li>
+			<li>Start APs through INIT-SIPI-SIPI (they idle until scheduling is enabled).</li>
+			<li>Initialise PS/2, USB HID and the VGA shadow buffer.</li>
+			<li>Inflate the command pack into <code>/ramfs</code>; start the WM and the first frame.</li>
+			<li>Probe the NIC, restore retained network config, start the kworker.</li>
+			<li>Mount FAT devices; call <code>wm_server_boot_ready()</code> so the WM spawns the first terminal; run DHCP if needed.</li>
+			<li>Enable scheduling on the APs and enter the kernel idle loop.</li>
+		</ol>
+		<p>
+			The boot trace lines written along the way (<code>boot_trace</code>,
+			<code>boot_val</code>) go to the framebuffer console and COM1, so a
+			machine without serial still shows where a boot stopped. The WM
+			disables the boot console when it attaches; <code>bootlog</code>
+			prints the saved text.
+		</p>
+	</section>
+
+	<section id="failures">
+		<h2>Failure modes to know</h2>
+		<ul>
+			<li><strong>No VBE mode.</strong> The legacy stage cannot produce a framebuffer; the kernel may start headless or the boot stops in the stage.</li>
+			<li><strong>Pack larger than the low gap.</strong> The legacy path rejects a compressed pack above <code>PACK_LOW_MAX</code>. UEFI and kexec can carry more.</li>
+			<li><strong>PIT not ticking.</strong> <code>kernel_main</code> prints <code>*** PIT NOT TICKING ***</code> and halts; no process scheduling is possible.</li>
+			<li><strong>UEFI Secure Boot.</strong> The unsigned <code>BOOTX64.EFI</code> is rejected before any NebOS code runs.</li>
+			<li><strong>Stale boot info.</strong> The checksum makes an invalid <code>0x500</code> block read as absent rather than as a bogus pack or RSDP.</li>
+		</ul>
+	</section>
+
+	<section id="sources">
+		<h2>Source map</h2>
+		<ul class="filelist">
+			<li><code>boot.S</code> — boot sector</li>
+			<li><code>mbr.S</code> — USB/HDD MBR</li>
+			<li><code>vesa_stage.S</code> — real-mode VESA stage</li>
+			<li><code>entry.S</code> — canonical kernel entry</li>
+			<li><code>bootinfo.h</code> — 0x500 block</li>
+			<li><code>vga.h</code> — 0x600 framebuffer block</li>
+			<li><code>efi/main.c</code> — UEFI loader</li>
+			<li><code>efi/tramp.S</code> — long-mode exit</li>
+			<li><code>kexec.c</code>, <code>kexec_tramp.S</code> — serial reload</li>
+			<li><code>netkexec.c</code> — network reload</li>
+			<li><code>kernel.c</code> — init order</li>
+			<li><code>kernel.ld</code> — image limits</li>
+			<li><code>Makefile</code> — image sizes and layout rules</li>
+		</ul>
+	</section>
+</main>
+
+<footer class="site-footer">
+	<div class="inner">
+		<p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
+		<p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
+	</div>
+</footer>
+</body>
+</html>

+ 370 - 0
docs/cpu.html

@@ -0,0 +1,370 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CPU &amp; Scheduling | NebOS Architecture</title>
+<meta name="description" content="NebOS CPU architecture: GDT/TSS, PIC/PIT and LAPIC interrupts, ACPI SMP bring-up, CFS-lite scheduling, wait queues, the big kernel lock, idle and power management.">
+<link rel="icon" href="favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+
+<header class="site-header">
+	<a class="brand" href="index.html">
+		<span class="brand-mark" aria-hidden="true"></span>
+		<span>NebOS <span class="brand-sub">Architecture</span></span>
+	</a>
+	<nav class="site-nav" aria-label="Architecture sections">
+		<a href="index.html">Overview</a>
+		<a href="boot.html">Boot</a>
+		<a href="memory.html">Memory</a>
+		<a href="cpu.html" aria-current="page">CPU</a>
+		<a href="drivers.html">Drivers</a>
+		<a href="filesystems.html">Filesystems</a>
+		<a href="graphics.html">Graphics</a>
+		<a href="network.html">Network</a>
+		<a href="userland.html">Userland</a>
+		<a href="development.html">Development</a>
+	</nav>
+</header>
+
+<main id="main" class="page">
+	<div class="page-head">
+		<p class="kicker">CPU &amp; scheduling</p>
+		<h1>Weighted fairness, one global run queue, one big lock.</h1>
+		<p class="lede">
+			NebOS runs a CFS-lite scheduler over a single global run queue and
+			per-CPU <code>current</code> pointers. ACPI/MADT brings up the APs,
+			each CPU has its own GDT, TSS and timer, and a sleeping recursive
+			mutex — the big kernel lock — serializes kernel execution.
+		</p>
+		<div class="meta">
+			<span class="pill">8 CPUs max</span>
+			<span class="pill">64 process slots</span>
+			<span class="pill">10 ms slice</span>
+			<span class="pill">1 kHz busy / 100 Hz idle</span>
+		</div>
+	</div>
+
+	<nav class="toc" aria-label="On this page">
+		<h2>On this page</h2>
+		<ul>
+			<li><a href="#bringup">Boot CPU bring-up</a></li>
+			<li><a href="#interrupts">Interrupts &amp; timers</a></li>
+			<li><a href="#smp">SMP bring-up</a></li>
+			<li><a href="#process">Process model</a></li>
+			<li><a href="#scheduler">CFS-lite scheduler</a></li>
+			<li><a href="#bkl">Big kernel lock</a></li>
+			<li><a href="#idle">Idle &amp; power</a></li>
+			<li><a href="#sources">Source map</a></li>
+		</ul>
+	</nav>
+
+	<section id="bringup">
+		<h2>Boot CPU bring-up</h2>
+		<p>
+			After <code>kernel_main</code> clears BSS and starts the boot console,
+			the first structural step is <code>gdt_tss_init(0)</code>. The GDT/TSS
+			and the per-CPU GS base must exist before any code that calls
+			<code>current_proc()</code> or <code>this_cpu()</code>.
+		</p>
+		<ul>
+			<li>Each CPU has a <code>struct cpu</code> holding <code>current</code>, <code>idle</code>, its TSS, LAPIC id, tick period and scheduling flags.</li>
+			<li><code>%gs:0</code> points at the current CPU's <code>current</code> field; <span class="file">switch.S</span> reads it directly. A static assert locks the offsets.</li>
+			<li>The TSS <code>esp0</code> is updated by <code>schedule()</code>, so ring-3 entry always lands on the process's kernel stack.</li>
+			<li><code>process_init()</code> must run before <code>timer_init()</code>: once the PIT starts, the timer stub can switch context on every tick.</li>
+		</ul>
+	</section>
+
+	<section id="interrupts">
+		<h2>Interrupts &amp; timers</h2>
+		<p>
+			The BSP keeps the legacy 8259 PIC and PIT. Device IRQs stay on the
+			BSP because there is no IOAPIC driver. APs mask their LINT0/LINT1
+			inputs and use only their local APIC timer and IPIs.
+		</p>
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Source</th><th>Vector</th><th>Role</th></tr>
+				</thead>
+				<tbody>
+					<tr><td>8259 PIC + PIT</td><td>IRQ0, etc.</td><td>BSP global clock and device interrupts; PIT tick advances the millisecond clock.</td></tr>
+					<tr><td>LAPIC timer</td><td><code>0x30</code></td><td>Per-AP scheduling tick; 1 ms busy, 10 ms idle.</td></tr>
+					<tr><td>LAPIC IPI</td><td><code>0x31</code></td><td>Reschedule request; must be EOIed on the target LAPIC.</td></tr>
+					<tr><td><code>int 0x80</code></td><td>syscall gate</td><td>Ring-3 service entry.</td></tr>
+					<tr><td><code>int 0x81</code></td><td>voluntary yield</td><td>Blocking helpers and <code>schedule()</code>.</td></tr>
+				</tbody>
+			</table>
+		</div>
+		<p>
+			The timer period is not fixed. While a process runs, the BSP PIT ticks
+			at 1 kHz and AP LAPIC timers tick every 1 ms. While a CPU is idle, the
+			BSP drops to 100 Hz and APs to 10 ms so MWAIT/HLT can hold a deeper
+			state. The global millisecond clock remains accurate because the PIT
+			stub advances it by the current tick period.
+		</p>
+
+		<figure class="figure">
+			<div class="bars" role="img" aria-label="Timer rates: 1000 Hz while busy, 100 Hz while idle. Bar widths are relative to 1000 Hz.">
+				<div class="bar-row">
+					<span class="bar-label">BSP busy</span>
+					<div class="bar-track"><span class="bar-fill green" style="--w:100%"></span></div>
+					<span class="bar-value">1000 Hz</span>
+				</div>
+				<div class="bar-row">
+					<span class="bar-label">BSP idle</span>
+					<div class="bar-track"><span class="bar-fill" style="--w:10%"></span></div>
+					<span class="bar-value">100 Hz</span>
+				</div>
+				<div class="bar-row">
+					<span class="bar-label">AP busy</span>
+					<div class="bar-track"><span class="bar-fill green" style="--w:100%"></span></div>
+					<span class="bar-value">1 ms</span>
+				</div>
+				<div class="bar-row">
+					<span class="bar-label">AP idle</span>
+					<div class="bar-track"><span class="bar-fill" style="--w:10%"></span></div>
+					<span class="bar-value">10 ms</span>
+				</div>
+			</div>
+			<figcaption>
+				<strong>Race to idle, then stay there.</strong> When a wake-up
+				arrives, <code>smp_resched_wake()</code> shortens the idle period so
+				the woken process runs at the next millisecond instead of waiting
+				out a 10 ms nap.
+			</figcaption>
+		</figure>
+	</section>
+
+	<section id="smp">
+		<h2>SMP bring-up</h2>
+		<p>
+			SMP is ACPI-only: RSDP → RSDT/XSDT → MADT → CPU/LAPIC list. There is
+			deliberately no Intel MP-table parser. A machine without ACPI, a
+			usable MADT, the CPUID APIC bit or a LAPIC stays uniprocessor and
+			follows exactly the old 8259/PIT path.
+		</p>
+		<ol>
+			<li>Copy the AP trampoline to <code>0x6000</code> (SIPI vector <code>0x06</code>).</li>
+			<li>Allocate an AP idle PCB and kernel stack via <code>process_init_ap()</code>.</li>
+			<li>Fill the startup block at <code>0x6F00</code> with CR3, stack top, C entry and CPU index.</li>
+			<li>Send INIT, then SIPI-SIPI, with a second SIPI retry.</li>
+			<li>The AP enters <code>smp_ap_main</code>, initialises its LAPIC timer and idle loop, and waits.</li>
+			<li>After device/FS setup, <code>smp_enable_sched()</code> lets APs take user work.</li>
+		</ol>
+		<p>
+			Kernel threads stay pinned to the BSP; only ring-3 processes may run
+			on an AP. Each AP runs <code>cpu_enable_sse()</code> because it starts
+			with firmware <code>CR4</code>; without OSFXSR/OSXMMEXCPT the SSE2
+			drawing fast paths would <code>#UD</code>.
+		</p>
+		<div class="warn">
+			<p><strong>No IOAPIC.</strong> Device IRQs never reach an AP, and
+			<code>pit_irq_stub</code> is BSP-only. A platform that routes ISA IRQs
+			through the IOAPIC would need a mask-all setup step after ACPI init.</p>
+		</div>
+	</section>
+
+	<section id="process">
+		<h2>Process model</h2>
+		<p>
+			Every process is a stable heap-allocated PCB referenced from a sparse
+			<code>procs[64]</code> table, so a process pointer never moves when
+			another slot changes. The idle context is not a process slot: the
+			<code>kernel_main</code> context becomes the BSP idle state, and APs
+			have their own idle PCBs.
+		</p>
+		<ul>
+			<li><strong>Kernel threads</strong> are created with <code>process_create</code> and take the BKL automatically.</li>
+			<li><strong>Ring-3 processes</strong> are created from an ELF image with their own page directory, 8-page user stack and cwd.</li>
+			<li><strong>The kworker</strong> is an ordinary kernel process that performs housekeeping and zombie reaping, so it cannot be starved by a busy system.</li>
+			<li><strong>Stable naming:</strong> process names are 12 bytes; the PCB holds the TTY id, cwd, affinity mask, CPU accounting and the scheduling entity.</li>
+		</ul>
+
+		<figure class="figure">
+			<svg viewBox="0 0 920 260" role="img" aria-labelledby="states-title states-desc">
+				<title id="states-title">Process state transitions</title>
+				<desc id="states-desc">Processes move between ready, running, sleeping, blocked and dead states. Wake-ups return to ready, and exit or kill moves to dead.</desc>
+
+				<rect class="svg-box green" x="48" y="96" width="150" height="58" rx="9"/>
+				<text class="svg-text" x="123" y="120" text-anchor="middle">READY</text>
+				<text class="svg-sub" x="123" y="140" text-anchor="middle">run queue</text>
+
+				<rect class="svg-box accent" x="288" y="96" width="150" height="58" rx="9"/>
+				<text class="svg-text" x="363" y="120" text-anchor="middle">RUNNING</text>
+				<text class="svg-sub" x="363" y="140" text-anchor="middle">one per CPU</text>
+
+				<rect class="svg-box blue" x="528" y="28" width="150" height="58" rx="9"/>
+				<text class="svg-text" x="603" y="52" text-anchor="middle">SLEEPING</text>
+				<text class="svg-sub" x="603" y="72" text-anchor="middle">deadline in sleep list</text>
+
+				<rect class="svg-box blue" x="528" y="164" width="150" height="58" rx="9"/>
+				<text class="svg-text" x="603" y="188" text-anchor="middle">BLOCKED</text>
+				<text class="svg-sub" x="603" y="208" text-anchor="middle">wait queue</text>
+
+				<rect class="svg-box amber" x="756" y="96" width="136" height="58" rx="9"/>
+				<text class="svg-text" x="824" y="120" text-anchor="middle">DEAD</text>
+				<text class="svg-sub" x="824" y="140" text-anchor="middle">zombie queue</text>
+
+				<path class="svg-line green" d="M198 118h84"/>
+				<path class="svg-line green" d="M276 112l7 6-7 6"/>
+				<text class="svg-tiny" x="240" y="108" text-anchor="middle">pick</text>
+
+				<path class="svg-line" d="M363 154v28H198v-24"/>
+				<path class="svg-line" d="M192 162l6-7 6 7"/>
+				<text class="svg-tiny" x="300" y="196" text-anchor="middle">slice / yield</text>
+
+				<path class="svg-line blue" d="M438 112h84"/>
+				<path class="svg-line blue" d="M516 106l7 6-7 6"/>
+				<text class="svg-tiny" x="480" y="103" text-anchor="middle">sleep</text>
+
+				<path class="svg-line blue" d="M438 138v46h84"/>
+				<path class="svg-line blue" d="M516 178l7 6-7 6"/>
+				<text class="svg-tiny" x="480" y="176" text-anchor="middle">wait</text>
+
+				<path class="svg-line" d="M603 86V62h-240v34"/>
+				<path class="svg-line" d="M357 90l6-7 6 7"/>
+				<text class="svg-tiny" x="475" y="56" text-anchor="middle">wake</text>
+
+				<path class="svg-line" d="M603 222v18H363v-18"/>
+				<path class="svg-line" d="M357 228l6-7 6 7"/>
+				<text class="svg-tiny" x="478" y="248" text-anchor="middle">wake</text>
+
+				<path class="svg-line amber" d="M438 125h312"/>
+				<path class="svg-line amber" d="M744 119l7 6-7 6"/>
+				<text class="svg-tiny" x="594" y="119" text-anchor="middle">exit / kill</text>
+			</svg>
+			<figcaption>
+				<strong>Five states, two queues.</strong> The run queue is global;
+				the sleep list is sorted by deadline; wait queues are per-object.
+				A woken process is clamped to the current minimum vruntime so an
+				interactive wake-up is scheduled promptly without accumulating
+				unbounded credit.
+			</figcaption>
+		</figure>
+	</section>
+
+	<section id="scheduler">
+		<h2>CFS-lite scheduler</h2>
+		<p>
+			Weight is an integer from 1 to 16. Each ready process carries a
+			64-bit <code>vruntime</code> and a <code>stride = 2<sup>20</sup> / weight</code>.
+			While a process runs, its vruntime advances by
+			<code>elapsed_ms × stride</code>; the scheduler picks the runnable
+			process with the smallest vruntime. The result is a long-term CPU
+			share proportional to weight.
+		</p>
+		<ul>
+			<li><strong>10 ms slice.</strong> A running process is preempted at the slice boundary unless it holds the BKL or has preemption disabled.</li>
+			<li><strong>Global run queue.</strong> A single linked list protected by <code>sched_lock</code>; every CPU scans it for the minimum vruntime.</li>
+			<li><strong>Wake-up clamp.</strong> A process waking from sleep or a wait queue is moved forward to the current minimum vruntime rather than receiving unlimited credit.</li>
+			<li><strong>Affinity.</strong> A CPU bitmask restricts where a process may run; kernel threads are pinned to the BSP.</li>
+			<li><strong><code>renice</code></strong> changes a live process's weight from the shell; the new stride takes effect immediately.</li>
+		</ul>
+
+		<figure class="figure">
+			<div class="bars" role="img" aria-label="Scheduler weights: window manager 16, default processes and terminals 8, kworker 4, minimum 1. Bar widths are relative to 16.">
+				<div class="bar-row">
+					<span class="bar-label">WM / max</span>
+					<div class="bar-track"><span class="bar-fill" style="--w:100%"></span></div>
+					<span class="bar-value">16</span>
+				</div>
+				<div class="bar-row">
+					<span class="bar-label">default / terminal</span>
+					<div class="bar-track"><span class="bar-fill blue" style="--w:50%"></span></div>
+					<span class="bar-value">8</span>
+				</div>
+				<div class="bar-row">
+					<span class="bar-label">kworker</span>
+					<div class="bar-track"><span class="bar-fill green" style="--w:25%"></span></div>
+					<span class="bar-value">4</span>
+				</div>
+				<div class="bar-row">
+					<span class="bar-label">minimum</span>
+					<div class="bar-track"><span class="bar-fill" style="--w:6.25%"></span></div>
+					<span class="bar-value">1</span>
+				</div>
+			</div>
+			<figcaption>
+				<strong>Weights seen in the tree.</strong> The ring-3 WM is raised
+				to 16, the kworker is set to 4 and a new process starts at 8. Bar
+				widths are relative to the maximum weight of 16.
+			</figcaption>
+		</figure>
+
+		<p>
+			The run queue is a flat list rather than a red-black tree; picking
+			the minimum is a scan. With at most 64 processes this is simple and
+			predictable, and the scheduler core stays small enough to audit.
+			Sleeping processes sit in a sorted sleep list, so the tick handler
+			wakes due sleepers without scanning every process.
+		</p>
+	</section>
+
+	<section id="bkl">
+		<h2>The big kernel lock</h2>
+		<p>
+			<code>bkl_*</code> is a sleeping recursive mutex, not a spinlock.
+			Every ring-3 syscall and every kernel thread takes it; voluntary
+			block and sleep points release it through <code>sched_yield</code>.
+			Long serial and network waits use <code>bkl_pause()</code> /
+			<code>bkl_resume()</code> so another CPU can make progress.
+		</p>
+		<ul>
+			<li><strong>Not timer-preempted.</strong> A CPU running a BKL holder is skipped by the tick decision, so the owner can safely be in the middle of kernel data structures.</li>
+			<li><strong>Recursive.</strong> The owner may re-enter; the depth is restored across a block in the PCB's <code>bkl_saved</code> field.</li>
+			<li><strong>Sleep, not spin.</strong> A waiter blocks on the BKL wait queue and is woken when the owner releases.</li>
+			<li><strong>Idle uses trylock.</strong> The idle fallback never blocks on the BKL; kworker and kernel commands take it normally.</li>
+		</ul>
+		<div class="note">
+			<p><strong>Why one big lock?</strong> The kernel is small and not
+			designed around fine-grained locking. The BKL keeps every kernel
+			invariant simple, at the cost of serializing long kernel operations.
+			Disk I/O still holds it; network and serial waits drop it.</p>
+		</div>
+	</section>
+
+	<section id="idle">
+		<h2>Idle, power &amp; thermals</h2>
+		<p>
+			<code>idle auto</code> is the default. It asks <span class="file">power.c</span>
+			for the deepest usable hint: C6 (<code>0x20</code>) on the
+			Nehalem/Westmere allowlist, HLT everywhere else. The Atom boards keep
+			HLT because of an old USB-legacy SMM hang; the UHCI/OHCI
+			<code>0xC0</code> legacy-SMI disable addresses it.
+		</p>
+		<ul>
+			<li><strong>P-states.</strong> On the allowlisted Nehalem/Westmere models, <code>power_init</code> enables SpeedStep, raises the package C-state limit to C6 when unlocked, reads min/max ratios and starts at the maximum non-turbo ratio.</li>
+			<li><strong>Governor.</strong> A 100 ms window picks min/max/linear target ratios; short busy streaks jump to max immediately. Each CPU writes its own <code>IA32_PERF_CTL</code>.</li>
+			<li><strong>Telemetry.</strong> <code>power</code> prints effective MHz from APERF/MPERF, ratios and C3/C6 residency; <code>sensors</code> prints DTS, board sensors and ThinkPad EC data.</li>
+			<li><strong>Thermal.</strong> Each CPU samples its DTS once a second from its scheduler tick; the hottest core is exposed to ring 3.</li>
+		</ul>
+	</section>
+
+	<section id="sources">
+		<h2>Source map</h2>
+		<ul class="filelist">
+			<li><code>sched.c</code>, <code>sched.h</code> — scheduler core and BKL</li>
+			<li><code>process.c</code>, <code>process.h</code> — PCBs and lifecycle</li>
+			<li><code>switch.S</code> — context switch</li>
+			<li><code>tss.c</code>, <code>tss.h</code> — per-CPU TSS</li>
+			<li><code>acpi.c</code>, <code>lapic.c</code>, <code>smp.c</code> — SMP</li>
+			<li><code>ap_tramp.S</code> — AP startup blob</li>
+			<li><code>timer.S</code>, <code>idle.c</code>, <code>power.c</code></li>
+			<li><code>thermal.c</code> — DTS sampling</li>
+			<li><code>spinlock.h</code> — IRQ-safe spinlocks</li>
+		</ul>
+	</section>
+</main>
+
+<footer class="site-footer">
+	<div class="inner">
+		<p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
+		<p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
+	</div>
+</footer>
+</body>
+</html>

+ 347 - 0
docs/development.html

@@ -0,0 +1,347 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Development | NebOS Architecture</title>
+<meta name="description" content="NebOS development: toolchain and build flags, image targets, QEMU runs, serial and network hot reload, runtime command-pack updates, tests and debugging tools.">
+<link rel="icon" href="favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+
+<header class="site-header">
+	<a class="brand" href="index.html">
+		<span class="brand-mark" aria-hidden="true"></span>
+		<span>NebOS <span class="brand-sub">Architecture</span></span>
+	</a>
+	<nav class="site-nav" aria-label="Architecture sections">
+		<a href="index.html">Overview</a>
+		<a href="boot.html">Boot</a>
+		<a href="memory.html">Memory</a>
+		<a href="cpu.html">CPU</a>
+		<a href="drivers.html">Drivers</a>
+		<a href="filesystems.html">Filesystems</a>
+		<a href="graphics.html">Graphics</a>
+		<a href="network.html">Network</a>
+		<a href="userland.html">Userland</a>
+		<a href="development.html" aria-current="page">Development</a>
+	</nav>
+</header>
+
+<main id="main" class="page">
+	<div class="page-head">
+		<p class="kicker">Development</p>
+		<h1>Edit, reload, watch the boot line.</h1>
+		<p class="lede">
+			A normal iteration does not reflash anything. The board receives a
+			new kernel and rootfs over serial or UDP, parks its APs, jumps into
+			the new image and prints the same version line on COM1. A runtime
+			command-pack update can skip even the kernel reload.
+		</p>
+		<div class="meta">
+			<span class="pill">gcc · as · ld · objcopy</span>
+			<span class="pill">QEMU + real hardware</span>
+			<span class="pill">KXE2 · KXN2 · KXNP</span>
+			<span class="pill">headless tests</span>
+		</div>
+	</div>
+
+	<nav class="toc" aria-label="On this page">
+		<h2>On this page</h2>
+		<ul>
+			<li><a href="#toolchain">Toolchain</a></li>
+			<li><a href="#pipeline">Build pipeline</a></li>
+			<li><a href="#targets">Make targets</a></li>
+			<li><a href="#serial">Serial reload</a></li>
+			<li><a href="#network">Network reload</a></li>
+			<li><a href="#pack">Runtime pack</a></li>
+			<li><a href="#tests">Tests</a></li>
+			<li><a href="#debug">Debugging</a></li>
+			<li><a href="#conventions">Conventions</a></li>
+			<li><a href="#docs">Keeping docs current</a></li>
+			<li><a href="#sources">Source map</a></li>
+		</ul>
+	</nav>
+
+	<section id="toolchain">
+		<h2>Toolchain</h2>
+		<p>
+			NebOS builds with a normal GNU toolchain for 32-bit x86, plus
+			<code>mtools</code> for FAT images and QEMU for testing. The UEFI
+			loader is the only 64-bit component and needs the mingw cross
+			compiler.
+		</p>
+		<ul>
+			<li><strong>Compiler.</strong> <code>gcc</code> with 32-bit multilib, <code>as</code>, <code>ld</code>, <code>objcopy</code>.</li>
+			<li><strong>Kernel flags.</strong> <code>-m32 -march=i586 -ffreestanding -fno-pie -nostdlib -fno-stack-protector -mno-sse -mno-sse2 -mno-mmx -O2</code>.</li>
+			<li><strong>Warnings.</strong> The build uses <code>-Wall -Wextra</code>; a new warning is a bug, not noise.</li>
+			<li><strong>User commands.</strong> Linked at <code>0x40000000</code> with <code>ucmd.ld</code>, stripped, and packed as <code>bin/&lt;name&gt;</code>.</li>
+			<li><strong>UEFI.</strong> <code>x86_64-w64-mingw32-gcc</code> builds <code>BOOTX64.EFI</code>; <code>make all</code> does not require it.</li>
+			<li><strong>Images.</strong> <code>mtools</code> builds <code>root.img</code> and the ESP.</li>
+		</ul>
+	</section>
+
+	<section id="pipeline">
+		<h2>Build pipeline</h2>
+		<figure class="figure">
+			<svg viewBox="0 0 920 360" role="img" aria-labelledby="build-title build-desc">
+				<title id="build-title">NebOS build pipeline</title>
+				<desc id="build-desc">Kernel sources become kernel.bin and boot.bin; ring-3 sources become cmds.pack and a gzip rootfs; the UEFI loader embeds kernel, pack and trampoline. The outputs feed floppy, USB and dual-boot images.</desc>
+
+				<rect class="svg-box blue" x="20" y="20" width="250" height="64" rx="9"/>
+				<text class="svg-text" x="40" y="46">kernel sources</text>
+				<text class="svg-sub" x="40" y="66">*.c · *.S · linker scripts</text>
+
+				<rect class="svg-box blue" x="20" y="116" width="250" height="64" rx="9"/>
+				<text class="svg-text" x="40" y="142">ring-3 sources</text>
+				<text class="svg-sub" x="40" y="162">ucmd_*.c · ngui · browser</text>
+
+				<rect class="svg-box blue" x="20" y="212" width="250" height="64" rx="9"/>
+				<text class="svg-text" x="40" y="238">UEFI loader</text>
+				<text class="svg-sub" x="40" y="258">efi/*.c · tramp.S</text>
+
+				<path class="svg-line blue" d="M270 52h62"/>
+				<path class="svg-line blue" d="M326 46l7 6-7 6"/>
+				<path class="svg-line blue" d="M270 148h62"/>
+				<path class="svg-line blue" d="M326 142l7 6-7 6"/>
+				<path class="svg-line blue" d="M270 244h62"/>
+				<path class="svg-line blue" d="M326 238l7 6-7 6"/>
+
+				<rect class="svg-box accent" x="338" y="20" width="230" height="64" rx="9"/>
+				<text class="svg-text" x="358" y="46">gcc · as · ld · objcopy</text>
+				<text class="svg-sub" x="358" y="66">kernel.elf → kernel.bin</text>
+
+				<rect class="svg-box accent" x="338" y="116" width="230" height="64" rx="9"/>
+				<text class="svg-text" x="358" y="142">mkpack · gzip · mkrootfs</text>
+				<text class="svg-sub" x="358" y="162">cmds.pack → NBROOT1</text>
+
+				<rect class="svg-box accent" x="338" y="212" width="230" height="64" rx="9"/>
+				<text class="svg-text" x="358" y="238">mingw gcc</text>
+				<text class="svg-sub" x="358" y="258">BOOTX64.EFI</text>
+
+				<path class="svg-line accent" d="M568 52h62"/>
+				<path class="svg-line accent" d="M624 46l7 6-7 6"/>
+				<path class="svg-line accent" d="M568 148h62"/>
+				<path class="svg-line accent" d="M624 142l7 6-7 6"/>
+				<path class="svg-line accent" d="M568 244h62"/>
+				<path class="svg-line accent" d="M624 238l7 6-7 6"/>
+
+				<rect class="svg-box green" x="636" y="20" width="264" height="64" rx="9"/>
+				<text class="svg-text" x="656" y="46">floppy.img · final.bin</text>
+				<text class="svg-sub" x="656" y="66">boot sector + kernel + rootfs</text>
+
+				<rect class="svg-box green" x="636" y="116" width="264" height="64" rx="9"/>
+				<text class="svg-text" x="656" y="142">usb.img</text>
+				<text class="svg-sub" x="656" y="162">MBR + boot + 8 MB rootfs</text>
+
+				<rect class="svg-box green" x="636" y="212" width="264" height="64" rx="9"/>
+				<text class="svg-text" x="656" y="238">usb-efi.img · 17 MB</text>
+				<text class="svg-sub" x="656" y="258">usb.img + 8 MB FAT16 ESP</text>
+
+				<line class="svg-line" x1="20" y1="310" x2="900" y2="310"/>
+				<text class="svg-sub" x="20" y="335">Hot reload skips the image step: make dev / net-dev sends kernel.bin + cmds_pack_gz.bin; cmds-dev / net-cmds sends cmds.pack.</text>
+			</svg>
+			<figcaption>
+				<strong>Two independent products.</strong> The kernel image and
+				the rootfs container have separate lifetimes: a kernel reload can
+				keep the running rootfs, and a pack update can keep the kernel.
+			</figcaption>
+		</figure>
+	</section>
+
+	<section id="targets">
+		<h2>Make targets</h2>
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Target</th><th>What it does</th></tr>
+				</thead>
+				<tbody>
+					<tr><td><code>make all</code></td><td>Build <code>floppy.img</code>, <code>usb.img</code>, <code>final.bin</code> and <code>root.img</code>.</td></tr>
+					<tr><td><code>make run</code> / <code>run-smp</code></td><td>Boot the floppy in QEMU, optionally with four CPUs (Atom 330 topology).</td></tr>
+					<tr><td><code>make run-usb</code></td><td>Boot <code>usb.img</code> as an IDE disk.</td></tr>
+					<tr><td><code>make run-uhci</code> / <code>run-ehci</code> / <code>run-xhci</code></td><td>Exercise the USB backends with a mouse/keyboard (and storage on EHCI).</td></tr>
+					<tr><td><code>make run-ehci-asix</code> / <code>run-xhci-asix</code></td><td>Pass through a real ASIX AX88772 dongle.</td></tr>
+					<tr><td><code>make run-net</code></td><td>Add a PCI NE2000 on QEMU's slirp network with host port 8080 forwarded.</td></tr>
+					<tr><td><code>make run-ahci</code></td><td>Add an ICH9 AHCI controller and a 512 MB SATA disk.</td></tr>
+					<tr><td><code>make uefi</code> / <code>run-uefi</code> / <code>test-uefi</code></td><td>Build the dual-boot image, boot it under OVMF, or run the headless serial check.</td></tr>
+					<tr><td><code>make rootfs</code></td><td>Rebuild <code>cmds.img</code> only.</td></tr>
+					<tr><td><code>make nowm</code></td><td>Diagnostic kernel with the WM disabled; the boot console stays visible.</td></tr>
+					<tr><td><code>make dev</code> / <code>kernel-dev</code></td><td>Serial reload of kernel + rootfs, or kernel only (keep the running rootfs).</td></tr>
+					<tr><td><code>make net-dev</code> / <code>kernel-net-dev</code></td><td>Network reload of kernel + rootfs, or kernel only.</td></tr>
+					<tr><td><code>make cmds-dev</code> / <code>net-cmds</code></td><td>Replace <code>/ramfs</code> at runtime over serial or UDP.</td></tr>
+					<tr><td><code>make monitor</code> / <code>netmon</code></td><td>Open the serial console, or listen to the UDP console mirror.</td></tr>
+					<tr><td><code>make flash</code></td><td>Write the dual-boot image to a USB stick (needs mingw and prompts for the device).</td></tr>
+					<tr><td><code>make test-usb</code></td><td>Headless QEMU mouse/keyboard regression tests using QMP and screen dumps.</td></tr>
+					<tr><td><code>make test-images</code> / <code>test-images-asan</code></td><td>Host image-decoder and blit tests, with an AddressSanitizer variant.</td></tr>
+					<tr><td><code>make test-crypto</code></td><td>Host vectors for SHA-256, ChaCha20-Poly1305, X25519 and TLS helpers.</td></tr>
+				</tbody>
+			</table>
+		</div>
+	</section>
+
+	<section id="serial">
+		<h2>Serial reload</h2>
+		<p>
+			COM1 runs at 115200 8N1. The WM idle loop watches the receive ring for
+			the <code>KXE2</code> magic and auto-spawns the reload, so a plain
+			<code>make dev</code> is enough. The manual <code>kexec</code> command
+			is a fallback that waits for the same image.
+		</p>
+		<pre><code>[magic "KXE2"][entry u32][kernel_size u32][pack_size u32]
+[kernel][rootfs gzip][checksum u8]</code></pre>
+		<ul>
+			<li><strong>Full reload.</strong> <code>make dev</code> stages kernel and rootfs in one page-allocated buffer, copies the kernel to <code>0x7E00</code> and publishes the pack range in boot info.</li>
+			<li><strong>Kernel only.</strong> <code>make kernel-dev</code> sends <code>pack_size == 0</code>; the new kernel keeps the running rootfs.</li>
+			<li><strong>Pack only.</strong> <code>make cmds-dev</code> uses <code>KXNP</code> and <code>ramfs_replace()</code>, without a kernel jump.</li>
+			<li><strong>Monitor.</strong> Run <code>make monitor</code> in a second terminal; each reload prints <code>NebOS v0.2.0 booted</code> on COM1.</li>
+		</ul>
+		<p>
+			The serial receive drops the BKL while it waits for bytes, so the WM
+			and the other CPU's syscalls stay responsive during a reload.
+		</p>
+		<div class="note">
+			<p><strong>One-time install on a 9600-baud machine.</strong> Use the
+			<code>bootstrap</code> program loaded through <code>serial recv</code>
+			+ <code>run serial</code>. It switches the link to 115200 and waits
+			for a normal <code>KXE2</code> transfer.</p>
+		</div>
+	</section>
+
+	<section id="network">
+		<h2>Network reload</h2>
+		<p>
+			For boards without a serial port, the same reload runs over UDP port
+			19288 with the <code>KXN2</code> magic. The host tool sends the
+			kernel and rootfs as one stop-and-wait stream; the board acknowledges
+			every datagram with the next expected offset and verifies a 32-bit
+			checksum before jumping.
+		</p>
+		<pre><code>make net-dev                    # kernel + rootfs to 192.168.178.240
+make net-dev BOARD_IP=192.168.178.42
+make kernel-net-dev             # kernel only; keep the rootfs
+make net-cmds                   # replace /ramfs only</code></pre>
+		<p>
+			The board must be idle at a shell prompt. The WM loop answers
+			ARP/ICMP, detects the <code>KXN2</code>/<code>KXNP</code> header and
+			pauses the auto-detect while a packet-level command owns the NIC or a
+			transfer is in progress. Datagrams are at most 1400 bytes.
+		</p>
+		<p>
+			The board address comes from DHCP when a server is present; use
+			<code>make net-dev BOARD_IP=&lt;leased-address&gt;</code>, or pin an
+			address with <code>netip</code> on the board.
+		</p>
+	</section>
+
+	<section id="pack">
+		<h2>Runtime command pack</h2>
+		<p>
+			<code>make cmds-dev</code> sends the raw <code>cmds.pack</code> with
+			the <code>KXNP</code> magic. The receiver validates the pack before
+			the swap, so a truncated transfer leaves the running commands
+			untouched. A good pack is installed by <code>ramfs_replace()</code>
+			and the old heap copy is freed.
+		</p>
+		<ul>
+			<li><strong>Existing processes are unaffected.</strong> They already loaded their ELF.</li>
+			<li><strong>The next spawn sees the new files.</strong></li>
+			<li><strong>RAM only.</strong> A cold boot uses the flashed rootfs; reflash after changing the bundle.</li>
+		</ul>
+	</section>
+
+	<section id="tests">
+		<h2>Tests</h2>
+		<ul>
+			<li><strong>USB regression.</strong> <code>make test-usb</code> runs QMP cursor and keyboard tests against UHCI, OHCI, EHCI and xHCI, including hotplug.</li>
+			<li><strong>Image library.</strong> <code>make test-images</code> decodes a corpus of PNG/JPEG/GIF/BMP/TGA/PNM/ICO/PAM files and checks blits; the ASan variant catches memory errors.</li>
+			<li><strong>Crypto.</strong> <code>make test-crypto</code> runs host vectors for the freestanding crypto code.</li>
+			<li><strong>UEFI.</strong> <code>make test-uefi</code> boots the dual image under OVMF headless and greps the serial log for the boot line.</li>
+		</ul>
+	</section>
+
+	<section id="debug">
+		<h2>Debugging</h2>
+		<ul>
+			<li><strong>Serial log.</strong> <code>make monitor</code> shows the boot trace and printf-style driver output. The <code>NebOS v… booted</code> line is written before the framebuffer is ready.</li>
+			<li><strong>Network console.</strong> <code>make netmon</code> listens to UDP 19290 for serial and terminal output; <code>netconsole host &lt;ip&gt;</code> narrows the target.</li>
+			<li><strong>dbg.</strong> The ring-0 serial monitor accepts <code>r addr len</code>, <code>w addr b0 …</code>, <code>i port</code>, <code>o port val</code>, <code>h</code> and <code>q</code>.</li>
+			<li><strong>Panic.</strong> A ring-0 fault dumps vector, error code, registers, CRs, EIP bytes and stack candidates to the LFB and COM1. Resolve addresses with <code>nm kernel.elf</code> / <code>addr2line -e kernel.elf</code>.</li>
+			<li><strong>Profiling.</strong> <code>gfxbench</code> times fill/copy/cell/canvas/flush; <code>top</code>, <code>sched</code>, <code>sensors</code>, <code>power</code> and <code>lspci</code>/<code>lsusb</code> expose live state.</li>
+			<li><strong>Memory.</strong> <code>peek addr len</code> hex-dumps identity-mapped memory (MMIO too); <code>poke addr val</code> writes one dword and prints the read-back.</li>
+		</ul>
+	</section>
+
+	<section id="conventions">
+		<h2>Conventions &amp; gotchas</h2>
+		<ul>
+			<li><strong>Freestanding C.</strong> No libc, no <code>malloc</code>, no <code>printf</code>. Use <code>io_putstr</code>, <code>io_putchar</code> and <code>io_puthex</code>.</li>
+			<li><strong>Fresh memory is not zeroed.</strong> Clear structures whose fields are read before being written. QEMU starts RAM clear and hides the bug.</li>
+			<li><strong>Keep the memory map in sync.</strong> Hardcoded addresses appear in assembly, C headers and linker scripts; changing one without the others breaks boot or loading.</li>
+			<li><strong>Ring-3 data segments.</strong> An IRET to ring 3 nulls DS/ES/FS/GS whose DPL is below CPL 3. Kernel stubs must restore selector <code>0x23</code> with <code>IRQ_RETURN_DS</code>. QEMU does not model this; only real hardware fails.</li>
+			<li><strong>Paging is flat.</strong> Physical equals virtual everywhere; there is no process isolation.</li>
+			<li><strong>The BKL is not preemptible.</strong> A BKL holder can be in the middle of kernel structures; block points drop it, and <code>bkl_pause()</code> is for long waits.</li>
+			<li><strong>Kernel size wall.</strong> <code>_end</code> must stay below <code>0x7F000</code>; the legacy staging gap also constrains BSS and the compressed pack.</li>
+		</ul>
+	</section>
+
+	<section id="docs">
+		<h2>Keeping docs current</h2>
+		<p>
+			This site is static HTML with one shared stylesheet, no JavaScript and
+			no build step. It is part of the tree, not generated output. When a
+			subsystem changes, update the matching page and the overview card in
+			the same change:
+		</p>
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Change</th><th>Update</th></tr>
+				</thead>
+				<tbody>
+					<tr><td>Boot path, boot info, image layout</td><td><a href="boot.html">boot.html</a></td></tr>
+					<tr><td>Address map, allocator, paging, user arenas</td><td><a href="memory.html">memory.html</a></td></tr>
+					<tr><td>Scheduler, interrupts, SMP, BKL, power</td><td><a href="cpu.html">cpu.html</a></td></tr>
+					<tr><td>PCI, storage, USB, input, sensors</td><td><a href="drivers.html">drivers.html</a></td></tr>
+					<tr><td>VFS, FAT, ramfs, /share, WebDAV</td><td><a href="filesystems.html">filesystems.html</a></td></tr>
+					<tr><td>Framebuffer, WM, canvas, ngui, images</td><td><a href="graphics.html">graphics.html</a></td></tr>
+					<tr><td>NIC, protocols, TLS, netconsole</td><td><a href="network.html">network.html</a></td></tr>
+					<tr><td>Syscalls, shell, pack, apps</td><td><a href="userland.html">userland.html</a></td></tr>
+					<tr><td>Build targets, reload, tests, debugging</td><td><a href="development.html">development.html</a></td></tr>
+				</tbody>
+			</table>
+		</div>
+		<p>
+			<code>AGENTS.md</code> repeats the rule and lists the same page map.
+			Numbers in charts must come from a source constant or table; if a
+			constant moves, update the chart caption and the source file that
+			defines it.
+		</p>
+	</section>
+
+	<section id="sources">
+		<h2>Source map</h2>
+		<ul class="filelist">
+			<li><code>Makefile</code> — targets and image rules</li>
+			<li><code>kexec.c</code>, <code>kexec_send.c</code> — serial reload</li>
+			<li><code>netkexec.c</code>, <code>netkexec_send.c</code> — network reload</li>
+			<li><code>netlog.c</code>, <code>netmonitor.c</code> — UDP console</li>
+			<li><code>dbg.c</code> — serial debug monitor</li>
+			<li><code>panic.c</code> — fatal exception dump</li>
+			<li><code>kernel.ld</code>, <code>ucmd.ld</code> — link limits</li>
+			<li><code>tools/</code> — QMP USB tests</li>
+			<li><code>AGENTS.md</code> — developer notes and maintenance rule</li>
+		</ul>
+	</section>
+</main>
+
+<footer class="site-footer">
+	<div class="inner">
+		<p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
+		<p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
+	</div>
+</footer>
+</body>
+</html>

+ 383 - 0
docs/drivers.html

@@ -0,0 +1,383 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Drivers &amp; Buses | NebOS Architecture</title>
+<meta name="description" content="NebOS drivers: PCI enumeration, floppy/ATA/AHCI storage, the USB core with UHCI, OHCI, EHCI and xHCI, HID input, serial, board sensors and the panic path.">
+<link rel="icon" href="favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+
+<header class="site-header">
+	<a class="brand" href="index.html">
+		<span class="brand-mark" aria-hidden="true"></span>
+		<span>NebOS <span class="brand-sub">Architecture</span></span>
+	</a>
+	<nav class="site-nav" aria-label="Architecture sections">
+		<a href="index.html">Overview</a>
+		<a href="boot.html">Boot</a>
+		<a href="memory.html">Memory</a>
+		<a href="cpu.html">CPU</a>
+		<a href="drivers.html" aria-current="page">Drivers</a>
+		<a href="filesystems.html">Filesystems</a>
+		<a href="graphics.html">Graphics</a>
+		<a href="network.html">Network</a>
+		<a href="userland.html">Userland</a>
+		<a href="development.html">Development</a>
+	</nav>
+</header>
+
+<main id="main" class="page">
+	<div class="page-head">
+		<p class="kicker">Drivers &amp; buses</p>
+		<h1>Polled hardware, one vtable per bus.</h1>
+		<p class="lede">
+			Most NebOS drivers are polled rather than interrupt-driven: storage,
+			USB and every NIC are serviced from process context. That trades
+			latency and CPU time for simple, single-owner state and a kernel that
+			stays easy to reason about on old hardware.
+		</p>
+		<div class="meta">
+			<span class="pill">PCI enumeration</span>
+			<span class="pill">FDC · PATA · SATA</span>
+			<span class="pill">UHCI · OHCI · EHCI · xHCI</span>
+			<span class="pill">PS/2 + USB HID</span>
+		</div>
+	</div>
+
+	<nav class="toc" aria-label="On this page">
+		<h2>On this page</h2>
+		<ul>
+			<li><a href="#inventory">Driver inventory</a></li>
+			<li><a href="#pci">PCI &amp; discovery</a></li>
+			<li><a href="#storage">Storage</a></li>
+			<li><a href="#usb">USB stack</a></li>
+			<li><a href="#hid">Input</a></li>
+			<li><a href="#serial">Serial</a></li>
+			<li><a href="#sensors">Sensors &amp; power</a></li>
+			<li><a href="#panic">Panic screen</a></li>
+			<li><a href="#limits">Limits</a></li>
+			<li><a href="#sources">Source map</a></li>
+		</ul>
+	</nav>
+
+	<section id="inventory">
+		<h2>Driver inventory</h2>
+		<p>
+			Every driver in the tree is small enough to read in one sitting. The
+			table below is the quickest way to find the one responsible for a
+			device.
+		</p>
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Subsystem</th><th>Driver</th><th>Bus / access</th><th>Service model</th></tr>
+				</thead>
+				<tbody>
+					<tr><td>Floppy</td><td><span class="file">disk.c</span></td><td>ISA FDC + DMA channel 2</td><td>IRQ 6; FAT operations set <code>sys_fs_busy</code></td></tr>
+					<tr><td>PATA</td><td><span class="file">ata.c</span></td><td>Legacy ports or PCI native BARs</td><td>Polled PIO, DRQ wait per sector</td></tr>
+					<tr><td>SATA</td><td><span class="file">ahci.c</span></td><td>PCI AHCI MMIO</td><td>Polled, READ/WRITE DMA EXT</td></tr>
+					<tr><td>USB</td><td><span class="file">usb.c</span> + <span class="file">uhci.c</span> <span class="file">ohci.c</span> <span class="file">ehci.c</span> <span class="file">xhci.c</span></td><td>PCI I/O ports or MMIO</td><td>Polled; hotplug watcher in the WM loop</td></tr>
+					<tr><td>Network</td><td><span class="file">e1000e.c</span> <span class="file">r8168.c</span> <span class="file">ne2000.c</span> <span class="file">asix.c</span></td><td>PCI or USB</td><td>Polled, one active receiver</td></tr>
+					<tr><td>PS/2</td><td><span class="file">mouse.c</span>, <span class="file">io.c</span></td><td>i8042</td><td>IRQ 1 keyboard, IRQ 12 mouse; polling fallback</td></tr>
+					<tr><td>Serial</td><td><span class="file">serial.c</span></td><td>16550 UART, COM1</td><td>IRQ 4 ring buffer + polled transmitter</td></tr>
+					<tr><td>Thermal</td><td><span class="file">thermal.c</span></td><td>Intel DTS MSR</td><td>Sampled once a second from the scheduler tick</td></tr>
+					<tr><td>Board sensors</td><td><span class="file">it87.c</span>, <span class="file">tpec.c</span></td><td>Super I/O, ThinkPad EC</td><td>Polled read-only</td></tr>
+				</tbody>
+			</table>
+		</div>
+	</section>
+
+	<section id="pci">
+		<h2>PCI &amp; discovery</h2>
+		<p>
+			<span class="file">pci.c</span> walks bus/device/function and exposes
+			BAR and capability access. The USB scan checks all functions: real
+			PIIX3/PIIX4/VIA layouts put the USB function at 0:07.2 or 0:01.2, not
+			0:07.0. Controllers with unassigned BARs are ignored rather than
+			driven at address zero.
+		</p>
+		<p>
+			MMIO regions are mapped through <code>paging_map_mmio()</code>. PCI
+			interrupts are disabled before touching MMIO, so every driver polls
+			its own status registers. <code>lspci</code> lists every function;
+			with a filter it prints BAR type, size and address details.
+		</p>
+	</section>
+
+	<section id="storage">
+		<h2>Storage</h2>
+		<p>
+			<span class="file">blkdev.c</span> is a small registry of block
+			devices. Each device exposes sector read/write plus geometry; FAT and
+			the format command sit above that interface and never talk to a
+			controller directly. Devices are named <code>floppy0</code>,
+			<code>ide0</code>, <code>sata0</code> and so on; partitions append
+			<code>p1</code>, <code>p2</code>.
+		</p>
+
+		<figure class="figure">
+			<svg viewBox="0 0 920 246" role="img" aria-labelledby="storage-title storage-desc">
+				<title id="storage-title">Storage software layers</title>
+				<desc id="storage-desc">The VFS and format tools use a block-device registry, which dispatches to the floppy, ATA PIO or AHCI driver, then to the physical disk.</desc>
+
+				<rect class="svg-box blue" x="40" y="30" width="230" height="62" rx="9"/>
+				<text class="svg-text" x="60" y="57">VFS · FAT · format</text>
+				<text class="svg-sub" x="60" y="77">files, not sectors</text>
+
+				<rect class="svg-box accent" x="345" y="30" width="230" height="62" rx="9"/>
+				<text class="svg-text" x="365" y="57">blkdev registry</text>
+				<text class="svg-sub" x="365" y="77">sector read / write + geometry</text>
+
+				<rect class="svg-box" x="650" y="30" width="230" height="62" rx="9"/>
+				<text class="svg-text" x="670" y="57">driver</text>
+				<text class="svg-sub" x="670" y="77">FDC · ATA · AHCI</text>
+
+				<path class="svg-line blue" d="M270 61h67"/>
+				<path class="svg-line blue" d="M330 55l7 6-7 6"/>
+				<path class="svg-line accent" d="M575 61h67"/>
+				<path class="svg-line accent" d="M635 55l7 6-7 6"/>
+
+				<rect class="svg-box green" x="40" y="142" width="230" height="62" rx="9"/>
+				<text class="svg-text" x="60" y="169">floppy.img</text>
+				<text class="svg-sub" x="60" y="189">CHS + ISA DMA</text>
+
+				<rect class="svg-box green" x="345" y="142" width="230" height="62" rx="9"/>
+				<text class="svg-text" x="365" y="169">ide0 / ide0pN</text>
+				<text class="svg-sub" x="365" y="189">PIO, legacy or native BARs</text>
+
+				<rect class="svg-box green" x="650" y="142" width="230" height="62" rx="9"/>
+				<text class="svg-text" x="670" y="169">sata0 / sata0pN</text>
+				<text class="svg-sub" x="670" y="189">AHCI port index</text>
+
+				<path class="svg-line" d="M175 92v42"/>
+				<path class="svg-line" d="M169 126l6 7 6-7"/>
+				<path class="svg-line" d="M460 92v42"/>
+				<path class="svg-line" d="M454 126l6 7 6-7"/>
+				<path class="svg-line" d="M765 92v42"/>
+				<path class="svg-line" d="M759 126l6 7 6-7"/>
+			</svg>
+			<figcaption>
+				<strong>One narrow waist.</strong> Filesystems and tools only see
+				<code>struct blk_dev</code>. The floppy still needs IRQ 6, but ATA
+				and AHCI are polled; a FAT operation takes <code>sys_fs_busy</code>
+				so the scheduler does not switch away mid-transfer.
+			</figcaption>
+		</figure>
+
+		<h3>Floppy</h3>
+		<p>
+			<span class="file">disk.c</span> drives the 8272-compatible FDC
+			through ISA DMA channel 2, with the single-sector DMA buffer at
+			<code>0x4000</code>. Retries handle the usual real-hardware flakiness.
+			The second floppy slot can hold <code>root.img</code>.
+		</p>
+		<h3>PATA</h3>
+		<p>
+			<span class="file">ata.c</span> uses the legacy command block or the
+			PCI IDE interface's native BARs. Multi-sector PIO waits for DRQ
+			before every sector because drives drop it between sectors; it polls
+			the command-block status rather than the alternate-status BAR, and
+			falls back to single-sector commands when a bridge leaves DRQ pending.
+		</p>
+		<h3>SATA/AHCI</h3>
+		<p>
+			<span class="file">ahci.c</span> drives the first AHCI controller
+			only, with no IRQs and no NCQ. It does COMRESET, IDENTIFY through the
+			shared <code>ata_identify_parse()</code>, and READ/WRITE DMA EXT
+			through a page-allocated bounce buffer. A disk added after boot needs
+			a rescan; there is no COMRESET hotplug.
+		</p>
+	</section>
+
+	<section id="usb">
+		<h2>USB stack</h2>
+		<p>
+			<span class="file">usb.c</span> is controller-agnostic. It handles
+			enumeration, descriptor parsing, hub recursion, bus scans, per-controller
+			addresses, the hotplug watcher and interrupt-IN consumers. Each host
+			controller implements the <code>usb_hcd_ops</code> vtable in
+			<span class="file">usb_hcd.h</span>.
+		</p>
+
+		<figure class="figure">
+			<svg viewBox="0 0 920 300" role="img" aria-labelledby="usb-title usb-desc">
+				<title id="usb-title">USB controller topology</title>
+				<desc id="usb-desc">EHCI handles high-speed root ports, UHCI and OHCI handle low and full speed devices, xHCI handles USB2 root ports. All feed the same USB core and HID layer.</desc>
+
+				<rect class="svg-box accent" x="30" y="24" width="200" height="64" rx="9"/>
+				<text class="svg-text" x="50" y="50">EHCI</text>
+				<text class="svg-sub" x="50" y="70">high-speed root ports</text>
+
+				<rect class="svg-box blue" x="252" y="24" width="200" height="64" rx="9"/>
+				<text class="svg-text" x="272" y="50">UHCI</text>
+				<text class="svg-sub" x="272" y="70">full/low speed · 1 instance</text>
+
+				<rect class="svg-box blue" x="474" y="24" width="200" height="64" rx="9"/>
+				<text class="svg-text" x="494" y="50">OHCI</text>
+				<text class="svg-sub" x="494" y="70">full/low speed · up to 4</text>
+
+				<rect class="svg-box green" x="696" y="24" width="194" height="64" rx="9"/>
+				<text class="svg-text" x="716" y="50">xHCI</text>
+				<text class="svg-sub" x="716" y="70">USB2 root ports only</text>
+
+				<path class="svg-line accent" d="M130 88v40h330v28"/>
+				<path class="svg-line blue" d="M352 88v68"/>
+				<path class="svg-line blue" d="M574 88v68"/>
+				<path class="svg-line green" d="M793 88v40H460v28"/>
+
+				<rect class="svg-box" x="300" y="156" width="320" height="58" rx="9"/>
+				<text class="svg-text" x="320" y="181">usb core</text>
+				<text class="svg-sub" x="320" y="201">enumeration · hubs · hotplug · interrupt-IN slots</text>
+
+				<path class="svg-line" d="M460 214v34"/>
+				<path class="svg-line" d="M454 240l6 7 6-7"/>
+
+				<rect class="svg-box" x="300" y="248" width="320" height="44" rx="9"/>
+				<text class="svg-text" x="320" y="275">usbhid · keyboard + mouse</text>
+			</svg>
+			<figcaption>
+				<strong>Companions are not optional.</strong> EHCI is scanned first
+				so its port resets can hand non-high-speed devices back to a
+				companion. There is no transaction translator: a low/full-speed
+				device behind a high-speed hub is invisible to EHCI.
+			</figcaption>
+		</figure>
+
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Controller</th><th>Transport</th><th>Instances</th><th>Implementation notes</th></tr>
+				</thead>
+				<tbody>
+					<tr><td>UHCI</td><td>PCI I/O ports</td><td>1</td><td>Frame list at <code>0x3000</code>; control QH plus one QH per interrupt slot.</td></tr>
+					<tr><td>OHCI</td><td>PCI MMIO</td><td>up to 4</td><td>HCCA from the page allocator, static ED/TD sets, TDs start at <code>CC = NotAccessed</code>.</td></tr>
+					<tr><td>EHCI</td><td>PCI MMIO</td><td>up to 4</td><td>Async QH/qTD schedule, page-allocated descriptors, polling only, no periodic list.</td></tr>
+					<tr><td>xHCI</td><td>PCI MMIO</td><td>—</td><td>USB2 root ports only; USB3 SuperSpeed devices are not handled.</td></tr>
+				</tbody>
+			</table>
+		</div>
+
+		<p>
+			Hubs are class-9 devices: <code>usb.c</code> sets their configuration,
+			powers every downstream port (honouring <code>bPwrOn2PwrGood</code>),
+			resets and waits for <code>PORT_ENABLE</code>, then enumerates
+			recursively. This is what makes the X201's internal PCH hubs work.
+			Hotplug watches root ports; a device behind a hub is only found when a
+			full scan runs (<code>lsusb</code> also bumps the USB generation so
+			<code>usbhid</code> re-attaches).
+		</p>
+	</section>
+
+	<section id="hid">
+		<h2>Input</h2>
+		<p>
+			<span class="file">usbhid.c</span> gives every HID class-3 interface
+			with an interrupt-IN endpoint one of the six USB interrupt slots. Boot
+			interfaces (subclass 1, protocol 1/2) are used as-is; other class-3
+			interfaces are classified by reading their HID report descriptor.
+			Composite receivers and several devices can coexist; mouse reports
+			from all slots are merged.
+		</p>
+		<ul>
+			<li><strong>Mouse.</strong> Three-byte boot reports: buttons in <code>b0 &amp; 7</code>, signed <code>dx/dy</code>. HID's +y is flipped to the PS/2 convention.</li>
+			<li><strong>Keyboard.</strong> Eight-byte boot reports (modifier + six keycodes). Reports are diffed and decoded through a HID-usage → scancode-set-1 table, then injected with <code>io_inject_scancode()</code>.</li>
+			<li><strong>Repeat.</strong> A boot keyboard only reports changes, so <code>io.c</code> adds software typematic repeat (500 ms delay, 33 ms rate).</li>
+			<li><strong>PS/2.</strong> The i8042 path shares the cursor and keyboard code; the BIOS legacy USB emulation is disabled because the kernel owns the devices.</li>
+		</ul>
+		<p>
+			<code>mouseinfo</code> shows the active backend and whether a USB
+			keyboard is attached. Headless regression tests inject mouse motion
+			and keys through QMP and verify the result with screen dumps.
+		</p>
+	</section>
+
+	<section id="serial">
+		<h2>Serial</h2>
+		<p>
+			<span class="file">serial.c</span> drives the 16550 at COM1, 115200
+			8N1, with an IRQ-driven receive ring buffer. It is used for the boot
+			trace, the netlog mirror source, XMODEM transfers, the <code>dbg</code>
+			monitor and the <code>KXE2</code> kexec receiver.
+		</p>
+		<p>
+			The transmitter is polled, so a machine without a serial port still
+			boots normally. <code>serial_puthex</code> and
+			<code>serial_putdec</code> are the structured dump helpers used by
+			drivers.
+		</p>
+	</section>
+
+	<section id="sensors">
+		<h2>Sensors, power &amp; thermals</h2>
+		<ul>
+			<li><strong>DTS.</strong> <span class="file">thermal.c</span> reads <code>IA32_THERM_STATUS</code> on an allowlist of Core/Core 2, Nehalem/Westmere and Bonnell models. TjMax comes from <code>IA32_TEMPERATURE_TARGET</code> on Nehalem and later; Bonnell uses a table.</li>
+			<li><strong>IT87xx.</strong> <span class="file">it87.c</span> reads the Super I/O temperatures and fan tachometers on the ASUS AT3IONT-I. Nothing is written to fan control.</li>
+			<li><strong>ThinkPad EC.</strong> <span class="file">tpec.c</span> is gated on an SMBIOS Lenovo/IBM match and reads temperatures and fan mode through ports <code>0x62/0x66</code>. It drains pending output bytes and uses bounded waits; nothing is written.</li>
+			<li><strong>MTRRs.</strong> <span class="file">mtrr.c</span> manages write-combining ranges for the framebuffer and reports the effective mapping.</li>
+		</ul>
+		<p>
+			<code>sensors</code> prints DTS values on the 90/100/125 °C scales,
+			board sensors and EC registers; <code>power</code> prints ratios,
+			effective MHz and C-state residency.
+		</p>
+	</section>
+
+	<section id="panic">
+		<h2>Panic screen</h2>
+		<p>
+			On a ring-0 fault, <span class="file">panic.c</span> draws straight
+			into the framebuffer — bypassing the shadow buffer and the WM — and
+			mirrors the same data to COM1 before halting. The banner includes the
+			vector and error code, GPRs, control registers, current pid/name,
+			uptime, instruction bytes and stack return-address candidates in the
+			kernel image.
+		</p>
+		<p>
+			Faults from ring 3 do not halt: the process is killed with a short
+			message in its terminal and serial log. There is no interactive
+			debugger on screen; the <code>dbg</code> kernel command drives a
+			serial monitor instead.
+		</p>
+	</section>
+
+	<section id="limits">
+		<h2>Limits</h2>
+		<ul>
+			<li><strong>Polling.</strong> USB, storage and network drivers consume CPU time while waiting; there is no IRQ-driven data path outside PS/2, serial and the PIT.</li>
+			<li><strong>EHCI.</strong> High-speed root ports only; no split transactions for low/full-speed devices behind a high-speed hub.</li>
+			<li><strong>xHCI.</strong> USB2 root ports only; USB3 SuperSpeed devices are not handled.</li>
+			<li><strong>HID.</strong> Report IDs are not handled, absolute pointers/tablets are ignored, and there is no wheel support.</li>
+			<li><strong>AHCI.</strong> First controller only, no hotplug after boot, disks above 2 TB are clamped to 32-bit LBA.</li>
+			<li><strong>Storage serialization.</strong> A FAT/floppy operation sets <code>sys_fs_busy</code> and stalls process switching for its duration; the PIT keeps ticking.</li>
+		</ul>
+	</section>
+
+	<section id="sources">
+		<h2>Source map</h2>
+		<ul class="filelist">
+			<li><code>pci.c</code>, <code>pci.h</code> — enumeration</li>
+			<li><code>blkdev.c</code> — block registry</li>
+			<li><code>disk.c</code> — floppy / DMA</li>
+			<li><code>ata.c</code>, <code>ahci.c</code> — PATA/SATA</li>
+			<li><code>usb.c</code>, <code>usb_hcd.h</code> — USB core</li>
+			<li><code>uhci.c</code>, <code>ohci.c</code>, <code>ehci.c</code>, <code>xhci.c</code></li>
+			<li><code>usbhid.c</code>, <code>mouse.c</code>, <code>io.c</code> — input</li>
+			<li><code>serial.c</code>, <code>serial_ring_buf.c</code></li>
+			<li><code>thermal.c</code>, <code>it87.c</code>, <code>tpec.c</code>, <code>mtrr.c</code></li>
+			<li><code>panic.c</code>, <code>timer.S</code> — fatal exceptions</li>
+		</ul>
+	</section>
+</main>
+
+<footer class="site-footer">
+	<div class="inner">
+		<p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
+		<p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
+	</div>
+</footer>
+</body>
+</html>

+ 12 - 0
docs/favicon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+	<defs>
+		<linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+			<stop offset="0" stop-color="#8b5cf6"/>
+			<stop offset="1" stop-color="#4f9de8"/>
+		</linearGradient>
+	</defs>
+	<rect width="64" height="64" rx="14" fill="url(#g)"/>
+	<rect x="16" y="17" width="32" height="6" rx="3" fill="#fff" opacity=".95"/>
+	<rect x="16" y="29" width="24" height="6" rx="3" fill="#fff" opacity=".8"/>
+	<rect x="16" y="41" width="32" height="6" rx="3" fill="#fff" opacity=".62"/>
+</svg>

+ 400 - 0
docs/filesystems.html

@@ -0,0 +1,400 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Storage &amp; Filesystems | NebOS Architecture</title>
+<meta name="description" content="NebOS filesystems: the VFS fs_ops layer, FAT12/16/32, the command-pack ramfs pipeline, the writable /share filesystem and the WebDAV view of the VFS.">
+<link rel="icon" href="favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+
+<header class="site-header">
+	<a class="brand" href="index.html">
+		<span class="brand-mark" aria-hidden="true"></span>
+		<span>NebOS <span class="brand-sub">Architecture</span></span>
+	</a>
+	<nav class="site-nav" aria-label="Architecture sections">
+		<a href="index.html">Overview</a>
+		<a href="boot.html">Boot</a>
+		<a href="memory.html">Memory</a>
+		<a href="cpu.html">CPU</a>
+		<a href="drivers.html">Drivers</a>
+		<a href="filesystems.html" aria-current="page">Filesystems</a>
+		<a href="graphics.html">Graphics</a>
+		<a href="network.html">Network</a>
+		<a href="userland.html">Userland</a>
+		<a href="development.html">Development</a>
+	</nav>
+</header>
+
+<main id="main" class="page">
+	<div class="page-head">
+		<p class="kicker">Storage &amp; filesystems</p>
+		<h1>One VFS, three very different backends.</h1>
+		<p class="lede">
+			The kernel keeps filesystem policy thin: a mount table and an
+			<code>fs_ops</code> vtable. FAT provides persistent read/write storage,
+			the command-pack ramfs is a read-only system image, and
+			<code>/share</code> is a writable RAM filesystem for network uploads.
+		</p>
+		<div class="meta">
+			<span class="pill">FAT12/16/32</span>
+			<span class="pill">read-only ramfs</span>
+			<span class="pill">/share · 16 MB</span>
+			<span class="pill">WebDAV</span>
+		</div>
+	</div>
+
+	<nav class="toc" aria-label="On this page">
+		<h2>On this page</h2>
+		<ul>
+			<li><a href="#vfs">VFS layer</a></li>
+			<li><a href="#fat">FAT</a></li>
+			<li><a href="#ramfs">ramfs &amp; the command pack</a></li>
+			<li><a href="#share">/share</a></li>
+			<li><a href="#sysfs">File service ABI</a></li>
+			<li><a href="#webdav">WebDAV</a></li>
+			<li><a href="#capacity">Capacity chart</a></li>
+			<li><a href="#limits">Limits</a></li>
+			<li><a href="#sources">Source map</a></li>
+		</ul>
+	</nav>
+
+	<section id="vfs">
+		<h2>VFS layer</h2>
+		<p>
+			<span class="file">vfs.c</span> mounts every detected FAT device under
+			<code>/</code>, keeps the two memory filesystems available throughout
+			the boot scan, and dispatches file operations through
+			<code>struct fs_ops</code>. The shell, the file service and the
+			WebDAV server never call <code>fat_*</code> directly.
+		</p>
+
+		<figure class="figure">
+			<svg viewBox="0 0 920 330" role="img" aria-labelledby="vfs-title vfs-desc">
+				<title id="vfs-title">VFS and filesystem backends</title>
+				<desc id="vfs-desc">The shell, sys_fs and WebDAV use the VFS mount table, which dispatches to FAT, ramfs or share through fs_ops. FAT sits on the block-device registry.</desc>
+
+				<rect class="svg-box blue" x="30" y="30" width="200" height="60" rx="9"/>
+				<text class="svg-text" x="50" y="56">shell / commands</text>
+				<text class="svg-sub" x="50" y="76">ls, cat, save, files</text>
+
+				<rect class="svg-box blue" x="255" y="30" width="200" height="60" rx="9"/>
+				<text class="svg-text" x="275" y="56">sys_fs · WebDAV</text>
+				<text class="svg-sub" x="275" y="76">ring-3 file service</text>
+
+				<rect class="svg-box accent" x="485" y="30" width="200" height="60" rx="9"/>
+				<text class="svg-text" x="505" y="56">vfs.c</text>
+				<text class="svg-sub" x="505" y="76">mount table · fs_ops</text>
+
+				<path class="svg-line blue" d="M230 60h18"/>
+				<path class="svg-line blue" d="M240 54l7 6-7 6"/>
+				<path class="svg-line blue" d="M455 60h23"/>
+				<path class="svg-line blue" d="M470 54l7 6-7 6"/>
+
+				<rect class="svg-box green" x="712" y="30" width="180" height="60" rx="9"/>
+				<text class="svg-text" x="732" y="56">directory cache</text>
+				<text class="svg-sub" x="732" y="76">last 64 FAT entries</text>
+
+				<path class="svg-line accent" d="M685 60h20"/>
+				<path class="svg-line accent" d="M697 54l7 6-7 6"/>
+
+				<rect class="svg-box" x="30" y="150" width="200" height="64" rx="9"/>
+				<text class="svg-text" x="50" y="176">FAT12/16/32</text>
+				<text class="svg-sub" x="50" y="196">read + write · 8.3 names</text>
+
+				<rect class="svg-box" x="255" y="150" width="200" height="64" rx="9"/>
+				<text class="svg-text" x="275" y="176">ramfs</text>
+				<text class="svg-sub" x="275" y="196">read-only · command pack</text>
+
+				<rect class="svg-box" x="485" y="150" width="200" height="64" rx="9"/>
+				<text class="svg-text" x="505" y="176">/share</text>
+				<text class="svg-sub" x="505" y="196">writable · RAM only</text>
+
+				<rect class="svg-box" x="30" y="252" width="200" height="58" rx="9"/>
+				<text class="svg-text" x="50" y="277">block devices</text>
+				<text class="svg-sub" x="50" y="297">floppy · ide · sata</text>
+
+				<path class="svg-line" d="M585 90v28"/>
+				<path class="svg-line" d="M130 118h455"/>
+				<path class="svg-line" d="M130 118v24"/>
+				<path class="svg-line" d="M355 118v24"/>
+				<path class="svg-line" d="M585 118v24"/>
+				<path class="svg-line" d="M124 143l6 7 6-7"/>
+				<path class="svg-line" d="M349 143l6 7 6-7"/>
+				<path class="svg-line" d="M579 143l6 7 6-7"/>
+				<path class="svg-line" d="M130 214v26"/>
+				<path class="svg-line" d="M124 240l6 7 6-7"/>
+			</svg>
+			<figcaption>
+				<strong>Same operations, different storage.</strong> Each backend
+				implements read, load/release, stat, write, unlink, mkdir, rmdir and
+				index-based directory listing. Paths passed to the backend are
+				relative to the mount; the VFS has already normalised them.
+			</figcaption>
+		</figure>
+
+		<p>
+			<code>vfs_resolve()</code> drops <code>.</code> components, collapses
+			and trims slashes, and resolves <code>..</code> against the mount.
+			The shell's working directory is per-process and inherited across
+			commands, so relative paths keep working after <code>cd</code>.
+		</p>
+	</section>
+
+	<section id="fat">
+		<h2>FAT</h2>
+		<p>
+			<span class="file">fat.c</span> supports FAT12, FAT16 and FAT32 on
+			any registered block device. It reads the BPB, validates the media
+			byte and mounts partitions as separate entries such as
+			<code>ide0p1</code> or <code>sata0p2</code>.
+		</p>
+		<ul>
+			<li><strong>Read/write.</strong> Read, write, delete, mkdir and rmdir are implemented; FAT32 allocation uses an FSInfo-seeded free-cluster hint.</li>
+			<li><strong>8.3 names.</strong> The on-disk name is the canonical one. The shell and <code>files</code> display the space-padded form; a long name cannot be created.</li>
+			<li><strong>Directory cache.</strong> The last FAT directory's first 64 entries are cached in <code>vfs.c</code>, so WebDAV's index sequence is one walk instead of N. Any write invalidates the cache.</li>
+			<li><strong>Serialization.</strong> A FAT operation sets <code>sys_fs_busy</code>; the scheduler does not switch processes during it because the driver has static state and the floppy needs IRQ 6.</li>
+		</ul>
+		<p>
+			<span class="file">fatdetect.c</span> and <span class="file">fatformat.c</span>
+			back the <code>format</code> command. A disk can be formatted in
+			binary units (<code>format ide0 100mb</code>, <code>1gb</code>) or
+			whole-disk.
+		</p>
+		<div class="warn">
+			<p><strong>FAT32 limits.</strong> The FSInfo free-count is not updated,
+			and a completely full FAT32 directory is not grown: new cluster
+			allocation for directories is not implemented.</p>
+		</div>
+	</section>
+
+	<section id="ramfs">
+		<h2>ramfs &amp; the command pack</h2>
+		<p>
+			The system root is a compressed command pack, not a disk image. Every
+			ring-3 command is a freestanding ELF linked at <code>0x40000000</code>,
+			packed as <code>bin/&lt;name&gt;</code>, gzipped and wrapped in a
+			one-sector <code>NBROOT1</code> header. At boot the path loads the
+			pack into RAM and <span class="file">ramfs.c</span> inflates it into a
+			private page-allocated copy mounted read-only at <code>/ramfs</code>.
+		</p>
+
+		<figure class="figure">
+			<svg viewBox="0 0 920 312" role="img" aria-labelledby="pack-title pack-desc">
+				<title id="pack-title">Command pack build and boot pipeline</title>
+				<desc id="pack-desc">ucmd ELFs are packed by mkpack, gzipped, wrapped by mkrootfs, loaded by the boot path into RAM, then inflated by ramfs_init and mounted at /ramfs.</desc>
+
+				<rect class="svg-box" x="20" y="26" width="150" height="64" rx="9"/>
+				<text class="svg-text" x="40" y="52">ucmd_*.c</text>
+				<text class="svg-sub" x="40" y="72">42 UCMDS + 3 app ELFs</text>
+
+				<rect class="svg-box" x="196" y="26" width="150" height="64" rx="9"/>
+				<text class="svg-text" x="216" y="52">mkpack</text>
+				<text class="svg-sub" x="216" y="72">NBPAK1 · bin/name</text>
+
+				<rect class="svg-box" x="372" y="26" width="150" height="64" rx="9"/>
+				<text class="svg-text" x="392" y="52">gzip -12</text>
+				<text class="svg-sub" x="392" y="72">cmds_pack_gz.bin</text>
+
+				<rect class="svg-box" x="548" y="26" width="150" height="64" rx="9"/>
+				<text class="svg-text" x="568" y="52">mkrootfs</text>
+				<text class="svg-sub" x="568" y="72">NBROOT1 header</text>
+
+				<rect class="svg-box green" x="724" y="26" width="174" height="64" rx="9"/>
+				<text class="svg-text" x="744" y="52">boot path</text>
+				<text class="svg-sub" x="744" y="72">pack_addr / pack_size</text>
+
+				<path class="svg-line" d="M170 58h16"/>
+				<path class="svg-line" d="M180 52l7 6-7 6"/>
+				<path class="svg-line" d="M346 58h16"/>
+				<path class="svg-line" d="M356 52l7 6-7 6"/>
+				<path class="svg-line" d="M522 58h16"/>
+				<path class="svg-line" d="M532 52l7 6-7 6"/>
+				<path class="svg-line green" d="M698 58h16"/>
+				<path class="svg-line green" d="M708 52l7 6-7 6"/>
+
+				<rect class="svg-box" x="390" y="150" width="170" height="64" rx="9"/>
+				<text class="svg-text" x="410" y="176">ramfs_init</text>
+				<text class="svg-sub" x="410" y="196">inflate + validate</text>
+
+				<rect class="svg-box accent" x="620" y="150" width="200" height="64" rx="9"/>
+				<text class="svg-text" x="640" y="176">/ramfs</text>
+				<text class="svg-sub" x="640" y="196">read-only · bin/command</text>
+
+				<path class="svg-line green" d="M810 90v40h-335v20"/>
+				<path class="svg-line green" d="M469 142l6 7 6-7"/>
+				<path class="svg-line" d="M560 182h52"/>
+				<path class="svg-line" d="M606 176l7 6-7 6"/>
+
+				<text class="svg-tiny" x="20" y="272">Runtime replacement: KXNP packs replace /ramfs in place.</text>
+				<text class="svg-tiny" x="20" y="290">Existing processes keep their loaded ELFs.</text>
+			</svg>
+			<figcaption>
+				<strong>The pack is the root filesystem.</strong> The kernel no
+				longer embeds it, so command growth does not move <code>_end</code>.
+				The legacy boot path still caps the compressed pack at about 255 KB;
+				UEFI and kexec can carry more.
+			</figcaption>
+		</figure>
+
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Container</th><th>Format</th><th>Purpose</th></tr>
+				</thead>
+				<tbody>
+					<tr><td><code>cmds.pack</code></td><td><code>NBPAK1</code></td><td>Raw command archive: <code>bin/&lt;name&gt;</code> entries.</td></tr>
+					<tr><td><code>cmds_pack_gz.bin</code></td><td>gzip</td><td>Compressed pack; <code>libdeflate-gzip -12</code> when available.</td></tr>
+					<tr><td><code>rootfs.bin</code></td><td><code>NBROOT1</code> + gzip</td><td>Floppy append (header + pack).</td></tr>
+					<tr><td><code>cmds.img</code></td><td><code>NBROOT1</code> padded to 8 MB</td><td>USB rootfs partition image.</td></tr>
+					<tr><td><code>/share</code></td><td>RAM entries</td><td>Writable upload target; not part of the pack.</td></tr>
+				</tbody>
+			</table>
+		</div>
+
+		<p>
+			The pack build is part of the normal Makefile. Add a
+			<code>ucmd_&lt;name&gt;.c</code> to <code>UCMDS</code> and the pack,
+			the mount and the PATH listing pick it up automatically. Runtime
+			replacement uses <code>make cmds-dev</code> or
+			<code>make net-cmds</code> and validates the pack before swapping it.
+		</p>
+	</section>
+
+	<section id="share">
+		<h2>/share</h2>
+		<p>
+			<span class="file">share.c</span> is a writable, page-backed in-memory
+			filesystem for network uploads. It matters on boards with no writable
+			disk, or when the only writable medium is a floppy. Entries are full
+			relative paths plus explicit directory entries, so empty directories
+			work; names are plain strings up to 63 bytes.
+		</p>
+		<ul>
+			<li><strong>Limits.</strong> 64 entries and 16 MB total, allocated as pages and freed on replace/delete.</li>
+			<li><strong>Volatile.</strong> A reboot or kexec starts empty.</li>
+			<li><strong>Mount point.</strong> <code>/share</code>, listed by <code>ls /</code> and visible in <code>files</code>.</li>
+			<li><strong>Writable by anyone on the LAN.</strong> The WebDAV server has no authentication.</li>
+		</ul>
+	</section>
+
+	<section id="sysfs">
+		<h2>File service ABI</h2>
+		<p>
+			Ring-3 commands use <code>SYS_READ_FILE</code>,
+			<code>SYS_WRITE_FILE</code>, <code>SYS_LIST_DIR</code>,
+			<code>SYS_LIST_MOUNTS</code>, <code>SYS_UNLINK</code>,
+			<code>SYS_MKDIR</code>, <code>SYS_RMDIR</code>,
+			<code>SYS_FS_STAT</code> and <code>SYS_GETCWD</code>.
+			<span class="file">sys_fs.c</span> validates the path, resolves it
+			against the caller's cwd, calls the VFS and maps backend errors to
+			the stable <code>SYS_E*</code> values.
+		</p>
+		<p>
+			The file service reads whole files, not streams. The shell loads an
+			ELF through <code>vfs_load_file</code> and spawns it; FAT ELFs are
+			loaded through <code>kmalloc</code> under <code>sys_fs_enter/exit</code>,
+			since the floppy needs IRQ 6.
+		</p>
+		<p>
+			Directory entries carry a 64-byte display name plus <code>raw_83</code>,
+			so FAT's space-padded names and the string-named memory filesystems
+			share one ABI.
+		</p>
+	</section>
+
+	<section id="webdav">
+		<h2>WebDAV</h2>
+		<p>
+			<span class="file">websrv</span> is a ring-3 HTTP/1.1 + WebDAV server
+			built on the kernel TCP listener. It serves the VFS:
+			<code>/</code> lists mounts, <code>/ramfs</code> is read-only, FAT
+			mounts accept only names that round-trip to 8.3, and
+			<code>/share</code> is the writable target.
+		</p>
+		<ul>
+			<li><strong>Concurrency.</strong> One active connection plus a small backlog (three backlog/closing slots in the current TCP server). Parallel clients queue with a zero window until the active request finishes.</li>
+			<li><strong>Bodies.</strong> Whole-file buffering, 4 MB normally and 1 MB when the heap cannot provide the larger buffer. A larger PUT gets 413.</li>
+			<li><strong>Methods.</strong> GET, PUT, DELETE, MKCOL, PROPFIND and MOVE to the extent described; directory <code>MOVE</code> is 501 and <code>PROPPATCH</code> is answered 200 without persisting.</li>
+			<li><strong>No auth.</strong> This is a trusted-LAN service; <code>/share</code> is writable by anyone who can reach it.</li>
+		</ul>
+		<p>
+			The WebDAV server and the packet-level <code>ping</code>/<code>curl</code>/
+			<code>netrecv</code> commands are mutually exclusive: both need the
+			single NIC receiver. Starting <code>websrv</code> while another
+			command owns the receiver fails.
+		</p>
+	</section>
+
+	<section id="capacity">
+		<h2>Capacity chart</h2>
+		<figure class="figure">
+			<div class="bars" role="img" aria-label="Capacity limits: /share 16 MB, ramfs decompressed pack 8 MB, USB rootfs image 8 MB, legacy compressed pack about 255 KB. Bar widths are relative to 16 MB.">
+				<div class="bar-row">
+					<span class="bar-label">/share</span>
+					<div class="bar-track"><span class="bar-fill green" style="--w:100%"></span></div>
+					<span class="bar-value">16 MB</span>
+				</div>
+				<div class="bar-row">
+					<span class="bar-label">ramfs (inflated)</span>
+					<div class="bar-track"><span class="bar-fill" style="--w:50%"></span></div>
+					<span class="bar-value">8 MB</span>
+				</div>
+				<div class="bar-row">
+					<span class="bar-label">rootfs image</span>
+					<div class="bar-track"><span class="bar-fill blue" style="--w:50%"></span></div>
+					<span class="bar-value">8 MB</span>
+				</div>
+				<div class="bar-row">
+					<span class="bar-label">legacy pack</span>
+					<div class="bar-track"><span class="bar-fill" style="--w:1.56%"></span></div>
+					<span class="bar-value">~255 KB</span>
+				</div>
+			</div>
+			<figcaption>
+				<strong>Different limits for different paths.</strong> The legacy
+				boot stage's compressed-pack cap is much smaller than the 8 MB
+				ramfs cap; UEFI and kexec avoid the low-gap bottleneck.
+			</figcaption>
+		</figure>
+	</section>
+
+	<section id="limits">
+		<h2>Limits</h2>
+		<ul>
+			<li><strong>Whole-file service.</strong> Commands read a complete file into memory; there is no stream API for general files.</li>
+			<li><strong>FAT names.</strong> No long filename creation or lookup. WebDAV refuses names that cannot be represented exactly in 8.3.</li>
+			<li><strong>ramfs is read-only.</strong> Writes return <code>SYS_EROFS</code>; use <code>/share</code> for mutable data.</li>
+			<li><strong>Pack volatile at runtime.</strong> Runtime pack replacement is RAM only; a cold boot uses the flashed rootfs.</li>
+			<li><strong>Directory listing cache.</strong> Only the first 64 entries of the last FAT directory are cached; a very large directory still costs a walk.</li>
+		</ul>
+	</section>
+
+	<section id="sources">
+		<h2>Source map</h2>
+		<ul class="filelist">
+			<li><code>vfs.c</code>, <code>vfs.h</code> — mounts and dispatch</li>
+			<li><code>fat.c</code>, <code>fat.h</code> — FAT12/16/32</li>
+			<li><code>ramfs.c</code>, <code>ramfs.h</code> — pack inflate</li>
+			<li><code>share.c</code>, <code>share.h</code> — /share</li>
+			<li><code>sys_fs.c</code> — ring-3 file service</li>
+			<li><code>mkpack.c</code>, <code>mkrootfs.c</code>, <code>rootfs.h</code></li>
+			<li><code>inflate.c</code> — DEFLATE/gzip</li>
+			<li><code>ucmd_websrv.c</code> — HTTP/WebDAV</li>
+			<li><code>fatdetect.c</code>, <code>fatformat.c</code> — format</li>
+		</ul>
+	</section>
+</main>
+
+<footer class="site-footer">
+	<div class="inner">
+		<p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
+		<p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
+	</div>
+</footer>
+</body>
+</html>

+ 326 - 0
docs/graphics.html

@@ -0,0 +1,326 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Graphics &amp; UI | NebOS Architecture</title>
+<meta name="description" content="NebOS graphics architecture: VBE framebuffer, shadow buffer, damage rectangles, blit vtable, window manager, canvas ABI, ngui toolkit and image library.">
+<link rel="icon" href="favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+
+<header class="site-header">
+	<a class="brand" href="index.html">
+		<span class="brand-mark" aria-hidden="true"></span>
+		<span>NebOS <span class="brand-sub">Architecture</span></span>
+	</a>
+	<nav class="site-nav" aria-label="Architecture sections">
+		<a href="index.html">Overview</a>
+		<a href="boot.html">Boot</a>
+		<a href="memory.html">Memory</a>
+		<a href="cpu.html">CPU</a>
+		<a href="drivers.html">Drivers</a>
+		<a href="filesystems.html">Filesystems</a>
+		<a href="graphics.html" aria-current="page">Graphics</a>
+		<a href="network.html">Network</a>
+		<a href="userland.html">Userland</a>
+		<a href="development.html">Development</a>
+	</nav>
+</header>
+
+<main id="main" class="page">
+	<div class="page-head">
+		<p class="kicker">Graphics &amp; UI</p>
+		<h1>Draw into a shadow, publish by damage.</h1>
+		<p class="lede">
+			The display path is intentionally simple: drawing lands in a RAM
+			shadow buffer, damage rectangles describe what changed, and a
+			budgeted flush copies those rectangles to VRAM. Windows add a
+			compositor and a mapped-canvas ABI on top; a small immediate-mode
+			toolkit supplies the widgets.
+		</p>
+		<div class="meta">
+			<span class="pill">VBE LFB</span>
+			<span class="pill">1 MiB flush budget</span>
+			<span class="pill">8 windows</span>
+			<span class="pill">RGB565 canvases</span>
+		</div>
+	</div>
+
+	<nav class="toc" aria-label="On this page">
+		<h2>On this page</h2>
+		<ul>
+			<li><a href="#framebuffer">Framebuffer</a></li>
+			<li><a href="#shadow">Shadow &amp; damage</a></li>
+			<li><a href="#blit">Blit backends</a></li>
+			<li><a href="#wm">Window manager</a></li>
+			<li><a href="#canvas">Canvas ABI</a></li>
+			<li><a href="#ngui">ngui toolkit</a></li>
+			<li><a href="#apps">Applications</a></li>
+			<li><a href="#images">Image library</a></li>
+			<li><a href="#gpu">GPU quirks</a></li>
+			<li><a href="#sources">Source map</a></li>
+		</ul>
+	</nav>
+
+	<section id="framebuffer">
+		<h2>Framebuffer</h2>
+		<p>
+			The boot path writes a <code>struct vga_boot_fb_info</code> to
+			<code>0x600</code>: LFB base, pitch, width, height, bits per pixel
+			and an RGBX flag for GOP's byte order. The legacy VESA stage chooses
+			a mode with at least 16 bpp, a linear framebuffer, it must fit the
+			card's VRAM, and width at most 1280 pixels. The UEFI loader imposes
+			its own GOP constraints.
+		</p>
+		<p>
+			<span class="file">vga.c</span> owns the visible surface. On a
+			normal boot the render target is a RAM shadow buffer at
+			<code>0x100000</code>, not the LFB; the 8 MB reserve leaves room for
+			future modes. A surface carries width, height, pitch, format and a
+			pixel-pointer, so the same drawing code can target a window layer or
+			a canvas.
+		</p>
+	</section>
+
+	<section id="shadow">
+		<h2>Shadow buffer &amp; damage</h2>
+		<p>
+			Drawing never writes VRAM directly. Each operation records a damage
+			rectangle; overlapping or touching rectangles merge, so a keystroke's
+			cells collapse into one small rect while unrelated damage stays
+			apart. The main loop calls <code>vga_present_shadow()</code> on every
+			iteration with a byte budget of <code>VGA_FLUSH_BUDGET_BYTES</code>
+			(1 MiB by default).
+		</p>
+		<ul>
+			<li><strong>Small rects copy whole.</strong> A window repaint within the budget never tears.</li>
+			<li><strong>Large rects are chunked.</strong> A full-screen redraw continues across loop iterations; newer damage is queued behind it.</li>
+			<li><strong>No fixed frame rate.</strong> The loop flushes whenever there is pending damage, so a cursor move reaches the screen within one loop.</li>
+			<li><strong>Re-entry guard.</strong> <code>vga_present_shadow()</code> refuses to run while another process is mid-flush; a full-screen copy is long enough to be preempted.</li>
+			<li><strong>Window drags flush immediately.</strong> <code>wm_drag_shadow</code> copies each drag step as one consistent frame.</li>
+		</ul>
+		<p>
+			When the target is not the screen — a window layer or an app canvas —
+			<code>vga_target_damage()</code> is a no-op. The render target
+			override is stored in the PCB, so a preempted draw cannot leak into
+			another process's window.
+		</p>
+	</section>
+
+	<section id="blit">
+		<h2>Blit backends</h2>
+		<p>
+			<span class="file">blit.c</span> is the pixel-operation vtable:
+			fill, copy, blend, canvas, present and flip. Software is the only
+			backend today, but the WM calls the vtable rather than a fixed
+			function, so an accelerator can replace individual operations
+			without touching window logic.
+		</p>
+		<p>
+			The software fill uses an SSE2 row store when the CPU supports it.
+			Rows that do not fit the cache use streaming stores
+			(<code>movntdq</code>, one <code>sfence</code> per fill), which
+			avoids read-for-ownership traffic that makes large fills DRAM-bound
+			on the Atom. SSE/SSE2 are never assumed: the kernel is built with
+			<code>-mno-sse</code>, and <code>cpu_has_sse2()</code> probes CPUID,
+			sets <code>CR4.OSFXSR/OSXMMEXCPT</code> and is re-run on every AP.
+		</p>
+		<p>
+			<code>gfxbench</code> times fill, copy, cell, canvas and flush paths
+			and reports the bytes actually copied by the presenter.
+		</p>
+	</section>
+
+	<section id="wm">
+		<h2>Window manager</h2>
+		<p>
+			The WM is a process that owns the desktop and a fixed array of eight
+			windows. It draws a system bar with the banner, launcher buttons and
+			clock, plus draggable terminal and canvas windows with a title bar and
+			close button. Click-to-focus, drag-by-title-bar and close are routed
+			through the same pointer path.
+		</p>
+		<p>
+			The WM is the ring-3 process loaded from
+			<code>/ramfs/bin/wm</code>; there is no kernel WM fallback. The
+			kernel window server in <span class="file">wm.c</span> owns the
+			shadow mapping, the per-window canvases, input routing, the cursor,
+			kexec detection and the boot-console handoff. It starts the first
+			terminal after the storage mount
+			(<code>wm_server_boot_ready</code>) and leaves the boot console
+			visible until the WM attaches.
+		</p>
+
+		<figure class="figure">
+			<svg viewBox="0 0 920 260" role="img" aria-labelledby="wm-title wm-desc">
+				<title id="wm-title">Window anatomy</title>
+				<desc id="wm-desc">A window consists of a title bar, a content area backed by an RGB565 canvas, and a close control. The WM composites the canvas into the screen shadow buffer.</desc>
+
+				<rect class="svg-box" x="70" y="22" width="780" height="200" rx="10"/>
+				<rect class="svg-box accent" x="70" y="22" width="780" height="34" rx="10"/>
+				<text class="svg-text" x="88" y="45">Terminal · /ramfs/bin/ls</text>
+				<text class="svg-text" x="800" y="45">×</text>
+
+				<rect class="svg-box green" x="86" y="72" width="748" height="132" rx="6"/>
+				<text class="svg-text" x="104" y="98">content canvas · RGB565 · mapped at 0x50000000</text>
+				<text class="svg-sub" x="104" y="120">text cells, images, widgets, or arbitrary drawing</text>
+			</svg>
+			<figcaption>
+				<strong>One window, one canvas.</strong> The title bar belongs to
+				the WM; the content is whatever the owning process draws into its
+				mapped back buffer. The WM never reads the process's memory — it
+				composites the front canvas on <code>PRESENT</code>.
+			</figcaption>
+		</figure>
+
+		<ul>
+			<li><strong>Terminal windows</strong> are canvas clients: <span class="file">ucmd_term.c</span> renders its rows into the RGB565 window canvas; keys arrive through the generic <code>SYS_KEY_POLL</code> or <code>SYS_WIN_KEY_WAIT</code>. The WM no longer has a text-cell path.</li>
+			<li><strong>Canvas windows</strong> are generic: the app gets a back buffer, pointer position/buttons/focus and queued press/release edges with capture.</li>
+			<li><strong>Focus and z-order</strong> are explicit; closing a window kills its session and frees its canvas.</li>
+		</ul>
+	</section>
+
+	<section id="canvas">
+		<h2>Canvas ABI</h2>
+		<p>
+			<code>SYS_WIN_CREATE</code> maps the calling command's window canvas
+			read/write at <code>0x50000000</code>. The process draws RGB565
+			pixels and publishes a finished frame with
+			<code>SYS_WIN_PRESENT</code>. Present copies the back buffer into
+			the composited front canvas with interrupts off, so a half-drawn
+			frame can never reach the screen. Frames carry monotonic sequence
+			counters, so the WM cannot lose one.
+		</p>
+		<p>
+			<code>SYS_WIN_CREATE</code> creates a generic canvas window. Input is
+			exposed through <code>SYS_WIN_POINTER</code> (content-relative
+			position, button mask, focus) and <code>SYS_WIN_EVENT</code>, which
+			queues press/release edges and a capture window. A click that starts
+			in a window still receives its release after the pointer leaves.
+			The WM process itself is special: it maps the screen shadow at
+			<code>0x58000000</code> and each front canvas at
+			<code>0x59000000 + index × 2 MB</code>, which is how it composites
+			without reading another process's memory.
+			<code>SYS_WM_RESIZE</code> (WM side) and
+			<code>SYS_WIN_ACK_RESIZE</code> (client side) swap in a resized
+			canvas.
+		</p>
+		<div class="note">
+			<p><strong>Buttons fire on the release edge.</strong> The toolkit keeps
+			a button <code>active</code> until <code>ui-&gt;released</code>;
+			inferring release from the sampled button mask races the WM event
+			queue and drops clicks.</p>
+		</div>
+		<p>
+			When a process exits or crashes, the reaper releases its window
+			mappings and the window server frees the canvas. Closing a window
+			kills its owner. Keys go through the window key queue
+			(<code>SYS_WIN_KEY_WAIT</code>) or the generic
+			<code>SYS_KEY_POLL</code>; Ctrl+C still reaches the terminal.
+		</p>
+	</section>
+
+	<section id="ngui">
+		<h2>ngui toolkit</h2>
+		<p>
+			<span class="file">ngui.c</span>/<span class="file">ngui.h</span> is an
+			immediate-mode GUI toolkit shared by the ring-3 apps. It provides
+			clipped RGB565 primitives, buttons, menu items, text fields, nine
+			procedural icons, a theme palette, layout cut helpers and scrolling
+			panes. It is linked into <code>files</code>, <code>mines</code>,
+			<code>solitaire</code> and the real <code>gallery.elf</code>.
+		</p>
+		<ul>
+			<li><strong>Text fields</strong> support drag-selection, double-click select-all, Ctrl+Left/Right word jumps, Ctrl+Delete/Backspace word deletion and Ctrl+A.</li>
+			<li><strong>Clip stack</strong> keeps nested panes and popups inside their parents.</li>
+			<li><strong>Layout cuts</strong> split a rectangle into rows, columns and fixed margins without a constraint solver.</li>
+			<li><strong>No retained widget tree.</strong> Apps redraw from state every frame, which keeps the toolkit small and predictable.</li>
+		</ul>
+	</section>
+
+	<section id="apps">
+		<h2>Applications</h2>
+		<div class="grid">
+			<div class="card">
+				<h3>files</h3>
+				<p>File browser on the VFS: opens text in <code>edit</code>, images in <code>view</code> and HTML in <code>browser</code>. The first ngui user.</p>
+			</div>
+			<div class="card">
+				<h3>gallery</h3>
+				<p>Live showcase of every ngui control and primitive. Ships in the pack as <code>bin/gallery.app</code>; a launcher prefers <code>/share/GALLERY</code> for development.</p>
+			</div>
+			<div class="card">
+				<h3>solitaire</h3>
+				<p>Klondike with drag-and-drop, draw-one/three, scoring, animation and pixel-art cards on the canvas service.</p>
+			</div>
+			<div class="card">
+				<h3>view</h3>
+				<p>Image viewer with fit, 1:1, zoom, pan, EXIF orientation and animated GIF playback.</p>
+			</div>
+			<div class="card">
+				<h3>clock / colors</h3>
+				<p>Small canvas demos: a clock and a colour test window. Both are early users of the window canvas API.</p>
+			</div>
+			<div class="card">
+				<h3>browser</h3>
+				<p>HTML renderer with CSS subset, inline images and a headless fetch helper. The largest ring-3 application in the tree.</p>
+			</div>
+		</div>
+	</section>
+
+	<section id="images">
+		<h2>Image library</h2>
+		<p>
+			The codecs are independent of the OS and the toolkit: each takes an
+			input buffer plus a caller-provided <code>struct img_mem</code> arena
+			and returns an RGB565 image with an optional 8-bit alpha plane. The
+			browser links the same objects and decodes HTTP bodies in memory.
+		</p>
+		<ul>
+			<li><strong>Formats.</strong> PNG, baseline and progressive JPEG, animated GIF, BMP, TGA, PNM, ICO/CUR and PAM.</li>
+			<li><strong>Drawing.</strong> <code>img_draw()</code> is a clipped, scaled RGB565 blit: box-filter downscale, bilinear upscale, alpha over a checkerboard or over the destination.</li>
+			<li><strong>Orientation.</strong> EXIF orientation is applied; arithmetic JPEG and CMYK are rejected.</li>
+			<li><strong>Cost.</strong> Downscaling runs on the CPU. The viewer caches one image; the browser keeps a display bitmap but still rescales on repaint.</li>
+		</ul>
+	</section>
+
+	<section id="gpu">
+		<h2>GPU quirks</h2>
+		<ul>
+			<li><strong>ATI Mach64.</strong> A CRTC fixup is applied after mode set. The legacy CRTC is skipped under UEFI.</li>
+			<li><strong>NVIDIA.</strong> VBE-only. The legacy VGA CRTC is never touched. On the ION, the framebuffer is stolen DRAM behind a BAR3 aperture; <span class="file">nvidia.c</span> finds the stolen range and writes through a cached alias once a WC MTRR covers it.</li>
+			<li><strong>Intel.</strong> The Ironlake-era path supports a hardware cursor where available; the software cursor is the common fallback.</li>
+			<li><strong>UEFI.</strong> <code>vga.c</code> honours the RGBX flag and skips the VBE-only ATI CRTC reset and NVIDIA stolen-VRAM alias. <span class="file">mouse.c</span> forces the software cursor.</li>
+		</ul>
+	</section>
+
+	<section id="sources">
+		<h2>Source map</h2>
+		<ul class="filelist">
+			<li><code>vga.c</code>, <code>vga.h</code> — framebuffer and damage</li>
+			<li><code>vga_copy.S</code> — copy primitives</li>
+			<li><code>blit.c</code>, <code>blit.h</code> — pixel vtable</li>
+			<li><code>cpu.c</code> — SSE2 probing</li>
+			<li><code>wm.c</code>, <code>wm.h</code> — kernel window server</li>
+			<li><code>ucmd_wm.c</code>, <code>uwm_lib.c</code> — ring-3 WM</li>
+			<li><code>gfx.c</code>, <code>gfx.h</code> — RGB565 window canvases</li>
+			<li><code>sys_wm.c</code>, <code>sys_wm.h</code> — WM/window ABI</li>
+			<li><code>ngui.c</code>, <code>ngui.h</code> — toolkit</li>
+			<li><code>ucmd_files.c</code>, <code>gallery.c</code>, <code>ucmd_solitaire.c</code></li>
+			<li><code>img*.c</code> — image codecs</li>
+			<li><code>ati.c</code>, <code>nvidia.c</code>, <code>intel.c</code>, <code>nv50.c</code></li>
+		</ul>
+	</section>
+</main>
+
+<footer class="site-footer">
+	<div class="inner">
+		<p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
+		<p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
+	</div>
+</footer>
+</body>
+</html>

+ 295 - 0
docs/index.html

@@ -0,0 +1,295 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Overview | NebOS Architecture</title>
+<meta name="description" content="Architecture overview of NebOS: a freestanding 32-bit x86 hobby operating system with its own boot chain, kernel, window manager, filesystem and network stack.">
+<link rel="icon" href="favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+
+<header class="site-header">
+	<a class="brand" href="index.html">
+		<span class="brand-mark" aria-hidden="true"></span>
+		<span>NebOS <span class="brand-sub">Architecture</span></span>
+	</a>
+	<nav class="site-nav" aria-label="Architecture sections">
+		<a href="index.html" aria-current="page">Overview</a>
+		<a href="boot.html">Boot</a>
+		<a href="memory.html">Memory</a>
+		<a href="cpu.html">CPU</a>
+		<a href="drivers.html">Drivers</a>
+		<a href="filesystems.html">Filesystems</a>
+		<a href="graphics.html">Graphics</a>
+		<a href="network.html">Network</a>
+		<a href="userland.html">Userland</a>
+		<a href="development.html">Development</a>
+	</nav>
+</header>
+
+<main id="main" class="page">
+	<div class="page-head">
+		<p class="kicker">NebOS 0.2.0 · Architecture notes</p>
+		<h1>One small OS, from boot sector to browser.</h1>
+		<p class="lede">
+			NebOS is a from-scratch, freestanding 32-bit x86 operating system
+			written in C and assembly. It targets a first-generation Pentium,
+			boots from a floppy, a USB disk or x86-64 UEFI firmware, and carries
+			its own scheduler, filesystems, window manager, TCP/IP stack and
+			ring-3 command pack.
+		</p>
+		<div class="meta">
+			<span class="pill accent">i586 · 32-bit</span>
+			<span class="pill">freestanding · no libc</span>
+			<span class="pill">BIOS + UEFI</span>
+			<span class="pill">serial + net hot reload</span>
+		</div>
+	</div>
+
+	<nav class="toc" aria-label="On this page">
+		<h2>On this page</h2>
+		<ul>
+			<li><a href="#stack">System stack</a></li>
+			<li><a href="#numbers">At a glance</a></li>
+			<li><a href="#constraints">Design constraints</a></li>
+			<li><a href="#reading">Reading path</a></li>
+			<li><a href="#subsystems">Subsystems</a></li>
+			<li><a href="#tour">Repository tour</a></li>
+		</ul>
+	</nav>
+
+	<section id="stack">
+		<h2>The system stack</h2>
+		<p>
+			Almost everything is built in-tree: the boot sectors, the physical
+			memory manager, the scheduler, the FAT driver, the USB host
+			controllers, the TCP client, the TLS implementation and the
+			applications. The only runtime contract with the outside world is
+			the PC firmware and the x86 instruction set.
+		</p>
+
+		<figure class="figure">
+			<svg viewBox="0 0 920 474" role="img" aria-labelledby="stack-title stack-desc">
+				<title id="stack-title">NebOS software stack</title>
+				<desc id="stack-desc">Five layers: ring-3 commands and GUI apps, the int 0x80 syscall boundary, kernel services, drivers and platform support, and firmware and hardware.</desc>
+
+				<rect class="svg-box accent" x="100" y="8" width="720" height="72" rx="9"/>
+				<text class="svg-text" x="124" y="35">Ring 3 · commands &amp; GUI apps</text>
+				<text class="svg-sub" x="124" y="55">ls · cat · edit · view · files · browser · gallery · solitaire</text>
+				<text class="svg-tiny" x="796" y="35" text-anchor="end">0x40000000</text>
+
+				<path class="svg-line" d="M460 80v22"/>
+				<path class="svg-line" d="M454 96l6 7 6-7"/>
+
+				<rect class="svg-box blue" x="100" y="104" width="720" height="72" rx="9"/>
+				<text class="svg-text" x="124" y="131">Syscall boundary · int 0x80</text>
+				<text class="svg-sub" x="124" y="151">SYS_* services · one string argument · canvas mapped at 0x50000000</text>
+
+				<path class="svg-line" d="M460 176v22"/>
+				<path class="svg-line" d="M454 192l6 7 6-7"/>
+
+				<rect class="svg-box" x="100" y="200" width="720" height="92" rx="9"/>
+				<text class="svg-text" x="124" y="227">Kernel services</text>
+				<text class="svg-sub" x="124" y="247">CFS-lite scheduler · VFS · FAT + ramfs · TCP/IP + TLS</text>
+				<text class="svg-sub" x="124" y="267">window server · file / info / memory services</text>
+
+				<path class="svg-line" d="M460 292v22"/>
+				<path class="svg-line" d="M454 308l6 7 6-7"/>
+
+				<rect class="svg-box" x="100" y="316" width="720" height="92" rx="9"/>
+				<text class="svg-text" x="124" y="343">Drivers &amp; platform</text>
+				<text class="svg-sub" x="124" y="363">PCI · PATA/SATA · FDC · USB UHCI/OHCI/EHCI/xHCI · NICs</text>
+				<text class="svg-sub" x="124" y="383">PS/2 + USB HID · serial · ACPI/MADT · thermal · power</text>
+
+				<path class="svg-line" d="M460 408v22"/>
+				<path class="svg-line" d="M454 424l6 7 6-7"/>
+
+				<rect class="svg-box green" x="100" y="432" width="720" height="36" rx="9"/>
+				<text class="svg-text" x="124" y="455">Firmware &amp; hardware · BIOS or UEFI · i586 CPU · VGA/VBE · RAM</text>
+
+				<text class="svg-tiny" x="40" y="52" text-anchor="middle">user</text>
+				<text class="svg-tiny" x="40" y="240" text-anchor="middle">kernel</text>
+				<text class="svg-tiny" x="40" y="360" text-anchor="middle">drivers</text>
+				<text class="svg-tiny" x="40" y="454" text-anchor="middle">firmware</text>
+			</svg>
+			<figcaption>
+				<strong>The layering is real, not just conceptual.</strong>
+				Ring-3 commands enter the kernel only through <code>int 0x80</code>;
+				the kernel owns the devices and exposes narrow services. The one
+				deliberate exception is the legacy ring-0 <code>run</code> area used
+				by <code>prog</code> and <code>space</code>.
+			</figcaption>
+		</figure>
+	</section>
+
+	<section id="numbers">
+		<h2>At a glance</h2>
+		<div class="grid">
+			<div class="card">
+				<h3>8 CPUs</h3>
+				<p>BSP plus up to seven APs, discovered through ACPI/MADT and started with INIT-SIPI-SIPI. Without ACPI the machine stays on the uniprocessor path.</p>
+			</div>
+			<div class="card">
+				<h3>64 process slots</h3>
+				<p>Kernel threads and ring-3 processes share a sparse, stable PCB table. Kernel threads are pinned to the BSP; user work can run on any AP.</p>
+			</div>
+			<div class="card">
+				<h3>8 windows</h3>
+				<p>Terminal and canvas windows are composited by the window manager, with per-window RGB565 canvases mapped into the owning process.</p>
+			</div>
+			<div class="card">
+				<h3>8 MB rootfs</h3>
+				<p>The command pack travels as a compressed <code>NBROOT1</code> image and is inflated into a read-only ramfs at boot. Runtime replacement needs no reboot.</p>
+			</div>
+		</div>
+	</section>
+
+	<section id="constraints">
+		<h2>Design constraints</h2>
+		<p>
+			The unusual parts of the architecture follow from a few hard rules.
+			They explain why the code uses fixed low-memory blocks, why the kernel
+			is linked below <code>0x7F000</code>, and why so much care goes into
+			keeping the kernel image small.
+		</p>
+		<ul>
+			<li><strong>Freestanding C.</strong> No libc, no <code>malloc</code>, no <code>printf</code>, no external runtime. Formatting and allocation are in-tree.</li>
+			<li><strong>i586 baseline.</strong> Builds use <code>-march=i586 -mno-sse -mno-sse2 -mno-mmx</code>; SSE2 drawing paths are probed at runtime.</li>
+			<li><strong>Identity-mapped paging.</strong> Physical and virtual addresses are equal. There is no per-process address space or isolation.</li>
+			<li><strong>128 MB physical ceiling.</strong> The frame bitmap covers 128 MB; anything above that is unmapped.</li>
+			<li><strong>Hardcoded low memory.</strong> Boot info, the E820 map, the framebuffer block and the AP trampoline have fixed addresses that every boot path must honour.</li>
+			<li><strong>No firmware runtime.</strong> <code>reboot</code> and <code>poweroff</code> use legacy ports; UEFI runtime services are not called after <code>ExitBootServices</code>.</li>
+		</ul>
+		<div class="warn">
+			<p><strong>Fresh memory is not zeroed.</strong> <code>mm_alloc_page</code> and <code>kmalloc</code> return whatever RAM contained. Every structure read before it is written must be cleared on allocation; QEMU hides this because its RAM starts clear.</p>
+		</div>
+	</section>
+
+	<section id="reading">
+		<h2>Reading path</h2>
+		<p>If you are new to the tree, follow the machine through a boot:</p>
+		<ol>
+			<li><a href="boot.html">Boot</a> — the real-mode stage, the UEFI loader and the <code>0x500</code>/<code>0x600</code> handoff contract.</li>
+			<li><a href="memory.html">Memory</a> — the fixed low-memory map and the 4 KB frame allocator it feeds.</li>
+			<li><a href="cpu.html">CPU &amp; scheduling</a> — interrupt setup, the CFS-lite scheduler and the big kernel lock.</li>
+			<li><a href="drivers.html">Drivers</a> — how storage, USB, input and sensors are discovered.</li>
+			<li><a href="graphics.html">Graphics</a> — the shadow buffer, compositor and ring-3 canvas model.</li>
+		</ol>
+		<p>
+			The remaining pages cover the filesystem and command-pack pipeline,
+			the network stack, the ring-3 ABI and the development workflow.
+		</p>
+	</section>
+
+	<section id="subsystems">
+		<h2>Subsystem map</h2>
+		<div class="grid">
+			<a class="card" href="boot.html">
+				<h3>Boot &amp; firmware</h3>
+				<p>BIOS boot sector, VESA stage, MBR, UEFI loader, kexec trampoline and the boot-info block.</p>
+				<span class="card-tag">boot.html</span>
+			</a>
+			<a class="card" href="memory.html">
+				<h3>Memory &amp; paging</h3>
+				<p>E820 map, 4 KB frame bitmap, kmalloc, process stacks, user arena and the hardcoded address ladder.</p>
+				<span class="card-tag">memory.html</span>
+			</a>
+			<a class="card" href="cpu.html">
+				<h3>CPU &amp; scheduling</h3>
+				<p>GDT/TSS, interrupts, AP bring-up, CFS-lite weights, wait queues, the BKL, idle and power states.</p>
+				<span class="card-tag">cpu.html</span>
+			</a>
+			<a class="card" href="drivers.html">
+				<h3>Drivers &amp; buses</h3>
+				<p>PCI enumeration, FDC/PATA/SATA, the USB core and four host controllers, HID, serial and board sensors.</p>
+				<span class="card-tag">drivers.html</span>
+			</a>
+			<a class="card" href="filesystems.html">
+				<h3>Storage &amp; filesystems</h3>
+				<p>VFS vtable, FAT12/16/32, the ramfs pack pipeline, <code>/share</code> and the WebDAV view of the VFS.</p>
+				<span class="card-tag">filesystems.html</span>
+			</a>
+			<a class="card" href="graphics.html">
+				<h3>Graphics &amp; UI</h3>
+				<p>VBE framebuffer, shadow buffer, damage rectangles, compositor, canvas ABI, ngui and image codecs.</p>
+				<span class="card-tag">graphics.html</span>
+			</a>
+			<a class="card" href="network.html">
+				<h3>Networking</h3>
+				<p>NIC registry, ARP/ICMP/UDP, DHCP, DNS, TCP client and listener, TLS 1.3, netconsole and netkexec.</p>
+				<span class="card-tag">network.html</span>
+			</a>
+			<a class="card" href="userland.html">
+				<h3>Userland</h3>
+				<p>Ring-3 address space, ELF loading, syscall groups, PATH dispatch, the command pack and GUI apps.</p>
+				<span class="card-tag">userland.html</span>
+			</a>
+			<a class="card" href="development.html">
+				<h3>Development</h3>
+				<p>Toolchain, build images, QEMU targets, serial/network reload, tests and low-level debugging tools.</p>
+				<span class="card-tag">development.html</span>
+			</a>
+		</div>
+	</section>
+
+	<section id="tour">
+		<h2>Repository tour</h2>
+		<p>
+			NebOS is deliberately flat: the kernel, the freestanding libraries
+			and the ring-3 commands live side by side at the repository root.
+			The linker scripts and the Makefile are the map.
+		</p>
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Area</th><th>Important files</th></tr>
+				</thead>
+				<tbody>
+					<tr>
+						<td>Boot chain</td>
+						<td><span class="file">boot.S</span> <span class="file">mbr.S</span> <span class="file">vesa_stage.S</span> <span class="file">entry.S</span> <span class="file">efi/</span></td>
+					</tr>
+					<tr>
+						<td>Kernel core</td>
+						<td><span class="file">kernel.c</span> <span class="file">sched.c</span> <span class="file">process.c</span> <span class="file">mm.c</span> <span class="file">paging.c</span> <span class="file">syscall.c</span></td>
+					</tr>
+					<tr>
+						<td>Devices</td>
+						<td><span class="file">usb.c</span> <span class="file">uhci.c</span> <span class="file">ohci.c</span> <span class="file">ehci.c</span> <span class="file">xhci.c</span> <span class="file">ata.c</span> <span class="file">ahci.c</span></td>
+					</tr>
+					<tr>
+						<td>Services</td>
+						<td><span class="file">sys_fs.c</span> <span class="file">sys_net.c</span> <span class="file">gfx.c</span> <span class="file">sys_wm.c</span> <span class="file">sys_info.c</span></td>
+					</tr>
+					<tr>
+						<td>Userland</td>
+						<td><span class="file">ucmd_*.c</span> <span class="file">ucmd_lib.h</span> <span class="file">ngui.c</span> <span class="file">browser.c</span> <span class="file">gallery.c</span></td>
+					</tr>
+					<tr>
+						<td>Build &amp; pack</td>
+						<td><span class="file">Makefile</span> <span class="file">mkpack.c</span> <span class="file">mkrootfs.c</span> <span class="file">kernel.ld</span> <span class="file">ucmd.ld</span></td>
+					</tr>
+					<tr>
+						<td>Documentation</td>
+						<td><span class="file">AGENTS.md</span> and this <span class="file">docs/</span> folder</td>
+					</tr>
+				</tbody>
+			</table>
+		</div>
+		<div class="tip">
+			<p><strong>Keep both maps current.</strong> Architecture changes belong in <code>AGENTS.md</code> and in the matching page under <code>docs/</code>. The maintenance rule is repeated in <code>AGENTS.md</code>.</p>
+		</div>
+	</section>
+</main>
+
+<footer class="site-footer">
+	<div class="inner">
+		<p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
+		<p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
+	</div>
+</footer>
+</body>
+</html>

+ 327 - 0
docs/memory.html

@@ -0,0 +1,327 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Memory | NebOS Architecture</title>
+<meta name="description" content="NebOS memory architecture: fixed low-memory addresses, E820 parsing, bitmap frame allocator, identity paging, MTRR write-combining, user arenas and boot-pack lifetime.">
+<link rel="icon" href="favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+
+<header class="site-header">
+	<a class="brand" href="index.html">
+		<span class="brand-mark" aria-hidden="true"></span>
+		<span>NebOS <span class="brand-sub">Architecture</span></span>
+	</a>
+	<nav class="site-nav" aria-label="Architecture sections">
+		<a href="index.html">Overview</a>
+		<a href="boot.html">Boot</a>
+		<a href="memory.html" aria-current="page">Memory</a>
+		<a href="cpu.html">CPU</a>
+		<a href="drivers.html">Drivers</a>
+		<a href="filesystems.html">Filesystems</a>
+		<a href="graphics.html">Graphics</a>
+		<a href="network.html">Network</a>
+		<a href="userland.html">Userland</a>
+		<a href="development.html">Development</a>
+	</nav>
+</header>
+
+<main id="main" class="page">
+	<div class="page-head">
+		<p class="kicker">Memory &amp; paging</p>
+		<h1>A fixed ladder and a 4 KB frame allocator.</h1>
+		<p class="lede">
+			NebOS identity-maps physical RAM with 4 MB pages and hands out
+			4 KB frames from a bitmap. A small set of low-memory addresses is
+			fixed by the boot path and the ABI; everything else — process stacks,
+			window canvases, the ring-3 heap and the rootfs copy — is dynamic.
+		</p>
+		<div class="meta">
+			<span class="pill">128 MB physical ceiling</span>
+			<span class="pill">4 KB frames</span>
+			<span class="pill">4 MB PSE pages</span>
+			<span class="pill">identity map</span>
+		</div>
+	</div>
+
+	<nav class="toc" aria-label="On this page">
+		<h2>On this page</h2>
+		<ul>
+			<li><a href="#physical">Physical memory</a></li>
+			<li><a href="#landmarks">Address landmarks</a></li>
+			<li><a href="#paging">Paging &amp; caching</a></li>
+			<li><a href="#frame">Frame allocator</a></li>
+			<li><a href="#heap">kmalloc</a></li>
+			<li><a href="#user">Ring-3 memory</a></li>
+			<li><a href="#pack">Rootfs pack lifetime</a></li>
+			<li><a href="#limits">Limits &amp; leaks</a></li>
+			<li><a href="#sources">Source map</a></li>
+		</ul>
+	</nav>
+
+	<section id="physical">
+		<h2>Physical memory</h2>
+		<p>
+			The real-mode stage probes <code>INT 15h</code> E820 and writes the
+			map to <code>0x1000</code>; the UEFI loader synthesises the same
+			structure from <code>GetMemoryMap</code>. <span class="file">mm.c</span>
+			starts with every page marked used, frees the E820 “usable RAM”
+			ranges, then reserves the regions the kernel already owns.
+		</p>
+
+		<figure class="figure">
+			<svg viewBox="0 0 920 180" role="img" aria-labelledby="phys-title phys-desc">
+				<title id="phys-title">Physical memory composition</title>
+				<desc id="phys-desc">Of the 128 MB addressable window, the low 1 MB and an 8 MB VGA shadow reserve are unavailable, leaving about 119 MB for the frame allocator.</desc>
+				<text class="svg-text" x="20" y="28">0x00000000</text>
+				<text class="svg-text" x="900" y="28" text-anchor="end">0x08000000 · 128 MB</text>
+
+				<rect class="svg-box blue" x="40" y="44" width="6.5" height="34" rx="1"/>
+				<rect class="svg-box accent" x="46.5" y="44" width="52.5" height="34" rx="1"/>
+				<rect class="svg-box green" x="99" y="44" width="781" height="34" rx="2"/>
+
+				<text class="svg-tiny" x="40" y="100">low 1 MB</text>
+				<text class="svg-tiny" x="105" y="100">VGA shadow · 8 MB</text>
+				<text class="svg-tiny" x="420" y="100" text-anchor="middle">frame allocator · ~119 MB</text>
+
+				<line class="svg-line" x1="43" y1="78" x2="43" y2="88"/>
+				<line class="svg-line" x1="73" y1="78" x2="73" y2="88"/>
+				<line class="svg-line" x1="490" y1="78" x2="490" y2="88"/>
+
+				<text class="svg-tiny" x="40" y="130">boot structures · kernel image · BIOS/UMA · DMA buffers</text>
+				<text class="svg-tiny" x="40" y="150">The 8 MB reserve protects the shadow buffer; the allocator starts at 0x900000.</text>
+			</svg>
+			<figcaption>
+				<strong>128 MB is a hard ceiling.</strong> The frame bitmap covers
+				<code>[0, 0x08000000)</code>; addresses above it are not mapped by
+				the kernel page tables. The VGA shadow reserve is conservative: the
+				actual buffer is smaller, but the gap keeps a future resolution bump
+				from colliding with allocated pages.
+			</figcaption>
+		</figure>
+	</section>
+
+	<section id="landmarks">
+		<h2>Address landmarks</h2>
+		<p>
+			These addresses are part of the boot contract or the kernel ABI.
+			Changing one requires updating the assembly, linker scripts, headers
+			and this table together.
+		</p>
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Address</th><th>Purpose</th><th>Written by / notes</th></tr>
+				</thead>
+				<tbody>
+					<tr><td><code>0x500</code></td><td>Boot info, 12 dwords</td><td>VESA stage, UEFI loader or kexec; <code>bootinfo.h</code></td></tr>
+					<tr><td><code>0x600</code></td><td>Boot framebuffer info</td><td>VESA stage or UEFI loader; <code>vga.h</code></td></tr>
+					<tr><td><code>0x7C00</code></td><td>Boot-sector load address / UEFI handoff stack top</td><td>BIOS and UEFI trampoline</td></tr>
+					<tr><td><code>0x7E00</code></td><td>Kernel load address and VESA-stage entry</td><td><code>kernel.ld</code></td></tr>
+					<tr><td><code>0x800</code></td><td>kexec and UEFI trampoline</td><td>Relocated at runtime; below the kernel</td></tr>
+					<tr><td><code>0x900</code></td><td>kexec/UEFI flat GDT and GDTR</td><td>Built at runtime; below the kernel</td></tr>
+					<tr><td><code>0x1000</code></td><td>E820 memory map</td><td>VESA stage, UEFI loader or kexec; parsed by <code>mm.c</code></td></tr>
+					<tr><td><code>0x3000</code></td><td>UHCI frame list</td><td>1024 × 4 bytes, 4 KB aligned</td></tr>
+					<tr><td><code>0x4000</code></td><td>ISA DMA buffer</td><td>One sector, used by the floppy driver</td></tr>
+					<tr><td><code>0x6000</code></td><td>AP real/protected-mode trampoline</td><td>SIPI vector <code>0x06</code>; image ends below <code>0x6C00</code></td></tr>
+					<tr><td><code>0x6C00</code></td><td>AP trampoline real-mode stack top</td><td>Grows down</td></tr>
+					<tr><td><code>0x6F00</code></td><td>AP startup info block</td><td>CR3, stack top, C entry, CPU index</td></tr>
+					<tr><td><code>0x60000</code></td><td>Legacy rootfs staging</td><td><code>0x60000..0x9FBFF</code>, compressed pack only</td></tr>
+					<tr><td><code>_end</code></td><td>Kernel end</td><td><code>kernel.ld</code> asserts <code>_end ≤ 0x7F000</code></td></tr>
+					<tr><td><code>0x7FF00</code></td><td>Program API struct</td><td><code>PROGRAM_API_ADDR</code>, <code>run_api.h</code></td></tr>
+					<tr><td><code>0x80000</code></td><td>Legacy ring-0 program load area</td><td><code>run.c</code>, <code>serial_recv.c</code>, <code>user.ld</code>; max <code>0x6000</code></td></tr>
+					<tr><td><code>0x900000</code></td><td>Boot pack after relocation; dynamic stacks and kexec staging</td><td>Freed after <code>ramfs_init</code> takes its copy</td></tr>
+					<tr><td><code>0x100000</code></td><td>VGA shadow buffer base</td><td><code>VGA_SHADOW_BASE</code>; 8 MB reserved</td></tr>
+					<tr><td><code>0x40000000</code></td><td>Ring-3 ELF link/load address</td><td><code>USER_BASE</code>, 2 MB window up to <code>0x40200000</code></td></tr>
+					<tr><td><code>0x50000000</code></td><td>Ring-3 window canvas</td><td><code>USER_WIN_BASE</code>, 4 MB slot</td></tr>
+					<tr><td><code>0x58000000</code></td><td>WM shadow mapping</td><td><code>WM_SHADOW_VA</code>; ring-3 WM only</td></tr>
+					<tr><td><code>0x59000000</code></td><td>WM content slots</td><td><code>WM_CONTENT_VA_BASE</code> + index × 2 MB (<code>WM_CONTENT_SLOT</code>)</td></tr>
+					<tr><td><code>0x60000000</code></td><td>Ring-3 anonymous heap</td><td><code>USER_HEAP_BASE</code>, up to 32 MB</td></tr>
+				</tbody>
+			</table>
+		</div>
+	</section>
+
+	<section id="paging">
+		<h2>Paging &amp; caching</h2>
+		<p>
+			<span class="file">paging.c</span> builds an identity map of RAM with
+			4 MB pages through <code>CR4.PSE</code>, adds the framebuffer's LFB
+			range, and enables <code>CR0.PG</code> and <code>CR0.WP</code>. Before
+			switching, it clears translation controls a BIOS protected-mode call
+			can leave behind: <code>CR4.PAE/PGE/LA57/PCIDE/SMEP/SMAP</code> and
+			<code>EFER.LME</code>.
+		</p>
+		<ul>
+			<li><strong>Identity map.</strong> Physical and virtual addresses are equal. Page-directory entries are shared with every process.</li>
+			<li><strong>Kernel stacks mapped everywhere.</strong> Each process gets a page directory cloned from the kernel identity map, so CR3 can switch while still running on the old kernel stack.</li>
+			<li><strong>LFB is uncacheable by default.</strong> If <code>mtrr_set_wc()</code> successfully covers the framebuffer, the LFB pages are mapped cacheable so the shadow-buffer flush can write-combine.</li>
+			<li><strong>No process isolation.</strong> There is one address space with per-process page directories only for mappings; a wild ring-0 or ring-3 pointer can reach any mapped physical page.</li>
+		</ul>
+		<p>
+			There is no cross-CPU TLB shootdown. MMIO mappings for another CPU's
+			running process rely on not-present TLB entries not being cached;
+			normal process teardown is unaffected because no two processes share
+			an address space.
+		</p>
+		<div class="note">
+			<p><strong>NVIDIA ION special case.</strong> 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, so <span class="file">nvidia.c</span>
+			locates the framebuffer in the stolen VRAM and writes through that
+			alias once a WC MTRR covers the stolen range. Everything else keeps
+			the uncacheable LFB.</p>
+		</div>
+	</section>
+
+	<section id="frame">
+		<h2>Frame allocator</h2>
+		<p>
+			<span class="file">mm.c</span> keeps one bit per 4 KB page for the
+			whole 128 MB window. The bitmap is not IRQ-safe; callers save and
+			disable interrupts around allocations. The allocator returns:
+		</p>
+		<ul>
+			<li><code>mm_alloc_page()</code> — one zero-address-ambiguous page (physical address 0 means failure).</li>
+			<li><code>mm_alloc_pages(n)</code> — <code>n</code> contiguous pages.</li>
+			<li><code>mm_free_page()</code> / <code>mm_free_range()</code> — release a page or a page-aligned boot reservation.</li>
+		</ul>
+		<p>
+			At boot, <code>mm_init</code> reserves the low 1 MB, the 8 MB VGA
+			shadow region, any LFB that happens to live below 128 MB, and the
+			boot-time rootfs pack. The pack reservation is released by
+			<code>ramfs_init</code> after it copies/inflates the pack into fresh
+			pages.
+		</p>
+		<p>
+			Fresh pages are <em>not</em> zeroed. Structures whose fields are read
+			before being written must be cleared explicitly; <code>clear_proc()</code>
+			in <span class="file">process.c</span> exists because a stale
+			<code>cr3</code> faulted on real hardware while QEMU's cleared RAM hid
+			the bug.
+		</p>
+	</section>
+
+	<section id="heap">
+		<h2>kmalloc</h2>
+		<p>
+			<span class="file">kmalloc.c</span> is a power-of-two heap allocator
+			on top of the frame allocator. It is intentionally simple: allocation
+			rounds to a size class, free lists are per class, and large objects
+			become contiguous page runs. PCBs, command context and
+			<span class="file">sys_fs.c</span> file loads use it.
+		</p>
+		<p>
+			The kernel heap is not a general-purpose userspace allocator. Ring-3
+			processes get one anonymous arena through <code>SYS_MEM_ALLOC</code>,
+			<code>SYS_MEM_GROW</code> and <code>SYS_MEM_FREE</code>.
+		</p>
+	</section>
+
+	<section id="user">
+		<h2>Ring-3 memory</h2>
+		<p>
+			A ring-3 ELF is linked at <code>0x40000000</code>. The image and its
+			8-page user stack live in a 2 MB window ending at
+			<code>0x40200000</code>. The kernel window server maps a window's
+			RGB565 back buffer at <code>0x50000000</code>, and the anonymous heap
+			starts at <code>0x60000000</code>.
+		</p>
+
+		<figure class="figure">
+			<div class="bars" role="img" aria-label="Ring-3 arena sizes relative to the 32 MB heap cap: image and stack 2 MB, canvas slot 4 MB, heap up to 32 MB.">
+				<div class="bar-row">
+					<span class="bar-label">image + stack</span>
+					<div class="bar-track"><span class="bar-fill blue" style="--w:6.25%"></span></div>
+					<span class="bar-value">2 MB</span>
+				</div>
+				<div class="bar-row">
+					<span class="bar-label">canvas slot</span>
+					<div class="bar-track"><span class="bar-fill" style="--w:12.5%"></span></div>
+					<span class="bar-value">4 MB</span>
+				</div>
+				<div class="bar-row">
+					<span class="bar-label">anonymous heap</span>
+					<div class="bar-track"><span class="bar-fill green" style="--w:100%"></span></div>
+					<span class="bar-value">32 MB</span>
+				</div>
+			</div>
+			<figcaption>
+				<strong>Three separate rings.</strong> The image/stack window is
+				fixed at link time; the canvas slot is one 4 MB mapping; the heap is
+				a growable arena. Bar widths are relative to the 32 MB heap cap.
+			</figcaption>
+		</figure>
+
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Range</th><th>Size</th><th>Contents</th></tr>
+				</thead>
+				<tbody>
+					<tr><td><code>0x40000000</code>–<code>0x40200000</code></td><td>2 MB</td><td>ELF segments, user stack top at <code>0x40200000</code> (8 pages, grows down)</td></tr>
+					<tr><td><code>0x50000000</code>–<code>0x50400000</code></td><td>4 MB</td><td>One window canvas mapping (RW, per window)</td></tr>
+					<tr><td><code>0x60000000</code>–<code>0x62000000</code></td><td>up to 32 MB</td><td>Anonymous heap; initial allocation zeroed, growth pages are not</td></tr>
+				</tbody>
+			</table>
+		</div>
+		<p>
+			Kernel stacks are 4 KB pages from the frame allocator, with an 8-stack
+			static fallback pool in BSS. The idle/bootstrap context uses the
+			in-image 8 KB <code>.stack</code> section. The user stack is separate:
+			8 pages just below <code>0x40200000</code>.
+		</p>
+	</section>
+
+	<section id="pack">
+		<h2>Rootfs pack lifetime</h2>
+		<ol>
+			<li>The boot path places the gzip pack in RAM: the legacy stage in the low gap and then <code>0x900000</code>, UEFI at the top of RAM below 128 MB, kexec in its staging buffer.</li>
+			<li><code>mm_init</code> reserves <code>[pack_addr, pack_addr + pack_size)</code> so the frame allocator cannot reuse it.</li>
+			<li><code>ramfs_init</code> takes a private page-allocated copy, validates the <code>NBROOT1</code> header and inflates the pack into it.</li>
+			<li><code>mm_free_range</code> releases the boot region when it is above the VGA shadow reserve. The private copy lives until <code>ramfs_replace</code> or reboot.</li>
+		</ol>
+		<p>
+			The ramfs holds at most 128 files and 8 MB of decompressed pack. A
+			larger pack fails to load rather than partially mounting.
+		</p>
+	</section>
+
+	<section id="limits">
+		<h2>Limits &amp; leaks</h2>
+		<ul>
+			<li><strong>No per-process address spaces.</strong> Paging is identity-mapped; there is no memory protection between processes.</li>
+			<li><strong>128 MB ceiling.</strong> Physical memory above <code>0x08000000</code> is unmapped. A wild pointer there is an instant <code>#PF</code>.</li>
+			<li><strong>User page leak on reap.</strong> Killing a ring-3 process frees its kernel stack and page directory but not all user pages mapped into it; a few pages leak per command run.</li>
+			<li><strong>Heap fragmentation.</strong> Power-of-two size classes make long-running mixed-size allocation wasteful compared with a real allocator.</li>
+			<li><strong>No TLB shootdown.</strong> Cross-CPU mapping changes rely on not-present entries not being cached.</li>
+		</ul>
+	</section>
+
+	<section id="sources">
+		<h2>Source map</h2>
+		<ul class="filelist">
+			<li><code>mm.c</code>, <code>mm.h</code> — E820 + bitmap allocator</li>
+			<li><code>kmalloc.c</code>, <code>kmalloc.h</code> — kernel heap</li>
+			<li><code>paging.c</code>, <code>paging.h</code> — identity map</li>
+			<li><code>mtrr.c</code> — write-combining MTRRs</li>
+			<li><code>process.c</code>, <code>process.h</code> — stacks and user layout</li>
+			<li><code>ramfs.c</code> — pack copy / inflate</li>
+			<li><code>efi/main.c</code> — firmware map conversion</li>
+			<li><code>kernel.ld</code> — low-memory image limits</li>
+		</ul>
+	</section>
+</main>
+
+<footer class="site-footer">
+	<div class="inner">
+		<p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
+		<p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
+	</div>
+</footer>
+</body>
+</html>

+ 336 - 0
docs/network.html

@@ -0,0 +1,336 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Networking | NebOS Architecture</title>
+<meta name="description" content="NebOS networking: the netdev registry and NIC drivers, ARP/ICMP/UDP, DHCP, DNS, the TCP client and listener, TLS 1.3, sys_net ownership, netconsole and netkexec.">
+<link rel="icon" href="favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+
+<header class="site-header">
+	<a class="brand" href="index.html">
+		<span class="brand-mark" aria-hidden="true"></span>
+		<span>NebOS <span class="brand-sub">Architecture</span></span>
+	</a>
+	<nav class="site-nav" aria-label="Architecture sections">
+		<a href="index.html">Overview</a>
+		<a href="boot.html">Boot</a>
+		<a href="memory.html">Memory</a>
+		<a href="cpu.html">CPU</a>
+		<a href="drivers.html">Drivers</a>
+		<a href="filesystems.html">Filesystems</a>
+		<a href="graphics.html">Graphics</a>
+		<a href="network.html" aria-current="page">Network</a>
+		<a href="userland.html">Userland</a>
+		<a href="development.html">Development</a>
+	</nav>
+</header>
+
+<main id="main" class="page">
+	<div class="page-head">
+		<p class="kicker">Networking</p>
+		<h1>A small stack with one receiver owner.</h1>
+		<p class="lede">
+			The NIC and the protocol stack live in the kernel; ring-3 commands
+			drive them through <code>SYS_NET_*</code> and <code>SYS_TCP_*</code>.
+			Only one process may own the receiver at a time, which keeps the
+			polled drivers and the single TCP connection simple.
+		</p>
+		<div class="meta">
+			<span class="pill">ARP · ICMP · UDP · TCP</span>
+			<span class="pill">DHCP · DNS</span>
+			<span class="pill">TLS 1.3 · X25519</span>
+			<span class="pill">netconsole + netkexec</span>
+		</div>
+	</div>
+
+	<nav class="toc" aria-label="On this page">
+		<h2>On this page</h2>
+		<ul>
+			<li><a href="#stack">Protocol stack</a></li>
+			<li><a href="#netdev">NIC drivers</a></li>
+			<li><a href="#core">Link &amp; IP layer</a></li>
+			<li><a href="#dhcp">DHCP &amp; DNS</a></li>
+			<li><a href="#tcp">TCP</a></li>
+			<li><a href="#tls">TLS</a></li>
+			<li><a href="#abi">sys_net ABI</a></li>
+			<li><a href="#console">Netconsole &amp; netkexec</a></li>
+			<li><a href="#http">HTTP clients</a></li>
+			<li><a href="#security">Security posture</a></li>
+			<li><a href="#sources">Source map</a></li>
+		</ul>
+	</nav>
+
+	<section id="stack">
+		<h2>Protocol stack</h2>
+		<p>
+			NebOS does not expose sockets. A ring-3 program asks the kernel for
+			info and configuration, acquires the receiver, then uses raw frame
+			paths or the single TCP connection. HTTP and TLS are libraries linked
+			into the command, not kernel services.
+		</p>
+
+		<figure class="figure">
+			<svg viewBox="0 0 920 380" role="img" aria-labelledby="net-title net-desc">
+				<title id="net-title">NebOS network stack</title>
+				<desc id="net-desc">Ring-3 curl, browser and websrv use uhttp and TLS, then sys_net syscalls, then TCP/DNS/DHCP, IPv4/ARP/ICMP, netdev drivers and the NIC.</desc>
+
+				<rect class="svg-box accent" x="70" y="18" width="780" height="58" rx="9"/>
+				<text class="svg-text" x="92" y="43">curl · browser · websrv · ping · dhcp</text>
+				<text class="svg-sub" x="92" y="63">ring-3 programs</text>
+
+				<path class="svg-line" d="M460 76v20"/>
+				<path class="svg-line" d="M454 90l6 7 6-7"/>
+
+				<rect class="svg-box blue" x="70" y="98" width="380" height="58" rx="9"/>
+				<text class="svg-text" x="92" y="123">uhttp · tls.c</text>
+				<text class="svg-sub" x="92" y="143">HTTP/1.1 · redirects · chunked · TLS 1.3</text>
+
+				<rect class="svg-box" x="470" y="98" width="380" height="58" rx="9"/>
+				<text class="svg-text" x="492" y="123">kernel services</text>
+				<text class="svg-sub" x="492" y="143">sys_fs for WebDAV · netlog · netkexec</text>
+
+				<path class="svg-line blue" d="M260 156v18"/>
+				<path class="svg-line blue" d="M254 168l6 7 6-7"/>
+				<path class="svg-line" d="M660 156v18"/>
+				<path class="svg-line" d="M654 168l6 7 6-7"/>
+
+				<rect class="svg-box green" x="70" y="176" width="780" height="58" rx="9"/>
+				<text class="svg-text" x="92" y="201">SYS_NET_* · SYS_TCP_* · SYS_DNS_RESOLVE · SYS_DHCP_RUN</text>
+				<text class="svg-sub" x="92" y="221">one receiver owner · interrupt-enabled waits</text>
+
+				<path class="svg-line green" d="M460 234v20"/>
+				<path class="svg-line green" d="M454 248l6 7 6-7"/>
+
+				<rect class="svg-box" x="70" y="256" width="780" height="58" rx="9"/>
+				<text class="svg-text" x="92" y="281">tcp.c · dns.c · dhcp.c</text>
+				<text class="svg-sub" x="92" y="301">TCP client + listener · one A query · DISCOVER/OFFER/REQUEST/ACK</text>
+
+				<path class="svg-line" d="M460 314v16"/>
+				<path class="svg-line" d="M454 324l6 7 6-7"/>
+
+				<rect class="svg-box blue" x="70" y="332" width="780" height="44" rx="9"/>
+				<text class="svg-text" x="92" y="359">IPv4 · ARP · ICMP · UDP · netdev registry · NIC driver</text>
+			</svg>
+			<figcaption>
+				<strong>Thin kernel, thick command.</strong> The kernel owns
+				addressing, ARP, routing and the single TCP connection. HTTP, TLS
+				and WebDAV run in ring 3, so a protocol bug kills a command rather
+				than the kernel.
+			</figcaption>
+		</figure>
+	</section>
+
+	<section id="netdev">
+		<h2>NIC drivers</h2>
+		<p>
+			<span class="file">netdev.c</span> keeps a registry of
+			<code>struct netdev</code> drivers; the first one whose probe succeeds
+			becomes active. All drivers are polled and share the same transmit,
+			receive, register-dump and reset interface. <code>netdev</code> with
+			no argument shows the active driver; <code>netdev asix</code> switches
+			to a named one, leaving the current driver untouched if the probe
+			fails.
+		</p>
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Driver</th><th>Hardware</th><th>Transport</th><th>Notes</th></tr>
+				</thead>
+				<tbody>
+					<tr><td><span class="file">e1000e.c</span></td><td>Intel 82540EM, 82577LM, 82578, 82579</td><td>PCI MMIO</td><td>PCI INTx disabled before MMIO; PCH D0; skips the global MAC reset while the link is up.</td></tr>
+					<tr><td><span class="file">r8168.c</span></td><td>RTL8111/8168</td><td>PCIe MMIO</td><td>C+ mode, 64-entry RX ring, polled.</td></tr>
+					<tr><td><span class="file">ne2000.c</span></td><td>RTL8029</td><td>ISA / QEMU PCI</td><td>Simple DP8390 path used by <code>make run-net</code>.</td></tr>
+					<tr><td><span class="file">asix.c</span></td><td>AX88772</td><td>USB bulk</td><td>Runs over the USB core; usable on EHCI/xHCI dongles.</td></tr>
+				</tbody>
+			</table>
+		</div>
+		<p>
+			The management NIC used by netlog and netkexec prefers the ASIX dongle
+			so a direct debug link survives <code>netdev e1000e</code>; otherwise
+			it falls back to the active driver. <code>netregs</code> dumps registers
+			and decoded interrupt status; <code>netloop</code> runs a PHY loopback
+			self-test; <code>netreset</code> re-initialises the active NIC.
+		</p>
+	</section>
+
+	<section id="core">
+		<h2>Link &amp; IP layer</h2>
+		<ul>
+			<li><strong>Ethernet decode</strong> recognises IPv4, ARP and IPv6 frame types (IPv6 is not implemented).</li>
+			<li><strong>ARP</strong> resolves a next hop with three tries, one second apart; <code>net_arp_resolve()</code> polls the active NIC and the caller must own it.</li>
+			<li><strong>Routing</strong> sends off-subnet traffic to the gateway when one is known; <code>net_next_hop()</code> is shared by ping, DNS and TCP.</li>
+			<li><strong>ICMP echo</strong> backs <code>ping</code>, with ARP resolution and round-trip timing.</li>
+			<li><strong>UDP</strong> has send and parse helpers; DNS, DHCP and netlog are its users.</li>
+			<li><strong>Checksums</strong> use the Internet one's-complement sum, with a TCP pseudo-header variant.</li>
+		</ul>
+		<p>
+			The static default address is <code>192.168.178.240</code>. At boot,
+			with a NIC present, a DHCP client runs with a 4-second budget
+			(requesting the current address); if no server answers, the static
+			address stays. The idle WM loop answers ARP/ICMP for the board's IP
+			even when no command is running, so the board is reachable and
+			MAC-resolvable.
+		</p>
+	</section>
+
+	<section id="dhcp">
+		<h2>DHCP &amp; DNS</h2>
+		<h3>DHCP</h3>
+		<p>
+			<span class="file">dhcp.c</span> is a minimal client:
+			DISCOVER → OFFER → REQUEST → ACK. It learns the mask, gateway and DNS
+			server (option 6), and <code>dhcp</code> re-runs it on demand. The
+			configuration is retained across kexec through the boot-info
+			<code>BOOTINFO_FLAG_NET</code> fields.
+		</p>
+		<h3>DNS</h3>
+		<p>
+			<span class="file">dns.c</span> sends one recursive A query over UDP
+			and handles name compression in the response. <code>netdns</code>
+			shows or sets the server; <code>host &lt;name&gt;</code> resolves.
+			Numeric hosts skip DNS entirely.
+		</p>
+	</section>
+
+	<section id="tcp">
+		<h2>TCP</h2>
+		<p>
+			<span class="file">tcp.c</span> deliberately implements one client
+			connection, not a general socket layer: connect, send, receive and
+			close. An 8 KB receive queue lets data arriving during a send survive;
+			the window update is sent whenever the application drains the queue,
+			so a full queue cannot deadlock until the peer's zero-window probe.
+		</p>
+		<ul>
+			<li><strong>MSS / window.</strong> Our MSS is 1460 bytes and the advertised window is 4 KB.</li>
+			<li><strong>Retransmit.</strong> A 500 ms retry timer with a small retry count carries the connection through loss; there is no full congestion-control state machine.</li>
+			<li><strong>Listener.</strong> The server side has one active connection plus three backlog/closing slots. SYN-ACK advertises a zero window while queued; a queued connection may hold 1 KB of early request, and the window opens when <code>tcp_srv_accept()</code> runs.</li>
+			<li><strong>Bursts.</strong> Responses go out in up to four-segment bursts with a cumulative ACK, rather than one segment per ACK.</li>
+			<li><strong>No keep-alive.</strong> With one active connection, an idle persistent connection would block the parallel connections Nautilus opens.</li>
+		</ul>
+		<p>
+			New SYNs and data are also handed to <code>tcp_srv_input()</code> from
+			the active connection's receive/send poll loops, not only between
+			requests, so parallel gvfs clients make progress.
+		</p>
+	</section>
+
+	<section id="tls">
+		<h2>TLS 1.3</h2>
+		<p>
+			<span class="file">tls.c</span> is a ring-3 client with a deliberately
+			narrow cipher suite: <code>TLS_CHACHA20_POLY1305_SHA256</code> and
+			X25519 only. It is stream-oriented over the existing TCP connection
+			and prints the leaf SHA-256 fingerprint for manual comparison.
+		</p>
+		<ul>
+			<li><strong>Not verified.</strong> Phase A provides encryption without authentication; a MITM is undetected. <code>curl</code> warns, and the browser marks HTTPS as unverified.</li>
+			<li><strong>Weak DRBG.</strong> <span class="file">tls_rng.c</span> mixes RDTSC jitter, ticks and the MAC; it is not a hardware-backed CSPRNG.</li>
+			<li><strong>Host tests.</strong> The crypto files are pure freestanding C with host vectors (<code>make test-crypto</code>, <code>tls_test.c</code>).</li>
+		</ul>
+		<div class="warn">
+			<p><strong>Do not treat HTTPS as secure authentication.</strong> The
+			cipher suite is real, but without certificate verification the
+			connection authenticates nothing. Use it for confidentiality on a
+			trusted network, not for secrets against an active attacker.</p>
+		</div>
+	</section>
+
+	<section id="abi">
+		<h2>sys_net ABI &amp; ownership</h2>
+		<p>
+			<span class="file">sys_net.c</span> exposes NIC info, MAC/IP/mask/
+			gateway/DNS getters and setters, raw frame TX/RX, decode, reply,
+			loopback, register dump, reset, speed and MAC overrides. It also
+			exposes the DNS and DHCP clients and the TCP/HTTP helpers.
+		</p>
+		<ul>
+			<li><strong>One owner.</strong> <code>SYS_NET_ACQUIRE</code> takes the receiver for the calling process; the background kexec watcher pauses while a command owns it.</li>
+			<li><strong>Reaper safety.</strong> If the owner dies, <code>sys_net_reap</code> force-releases the receiver through <code>netdev_release_all()</code>.</li>
+			<li><strong>Wait semantics.</strong> ARP, DNS, DHCP and TCP waits re-enable interrupts for their duration and spin on <code>get_ticks_ms()</code>; the syscall stub enters with interrupts off.</li>
+			<li><strong>No sockets.</strong> The connection state lives in the kernel, one connection at a time; this is why the browser opens a fresh connection per fetch job.</li>
+		</ul>
+	</section>
+
+	<section id="console">
+		<h2>Netconsole &amp; netkexec</h2>
+		<p>
+			<span class="file">netlog.c</span> mirrors the serial console and
+			terminal output to UDP port 19290. The mirror is on by default and
+			broadcasts; <code>netconsole host &lt;laptop-ip&gt;</code> narrows it,
+			<code>netconsole off</code>/<code>on</code> toggles it, and
+			<code>netlog &lt;text&gt;</code> sends an ad-hoc line. The producer
+			never blocks: a full buffer drops characters and reports it.
+		</p>
+		<p>
+			<span class="file">netkexec.c</span> receives a new kernel/rootfs over
+			UDP port 19288 using <code>KXN2</code>, and a runtime command pack
+			using <code>KXNP</code>. Datagrams are acknowledged with the next
+			expected offset and verified with a 32-bit checksum before the jump
+			or pack swap. On the host, <code>make netmon</code> and
+			<code>make net-dev</code> wrap these protocols.
+		</p>
+	</section>
+
+	<section id="http">
+		<h2>HTTP clients</h2>
+		<ul>
+			<li><strong>curl</strong> — <code>http://</code> or <code>https://</code> GET with DNS, ARP, redirects (up to five hops), chunked decoding, status/headers/body dump and a TLS warning.</li>
+			<li><strong>uhttp</strong> — shared ring-3 HTTP/1.1 client used by curl and the browser: URL parsing, redirects, chunked decoding, timeouts and TLS.</li>
+			<li><strong>browser</strong> — runs network fetches in a headless <code>curl __fetch</code> helper that writes the body and metadata under <code>/share</code>, so the UI keeps drawing and scrolling. Each fetch opens a fresh connection.</li>
+			<li><strong>websrv</strong> — the server side, speaking HTTP/1.1 + WebDAV over the TCP listener; see <a href="filesystems.html#webdav">Filesystems → WebDAV</a>.</li>
+		</ul>
+		<p>
+			The browser's helper requests identity encoding because inflating
+			multi-megabyte pages in the UI process stalled. If a server still
+			sends gzip, the browser's inflate hook pumps the UI while decoding.
+		</p>
+	</section>
+
+	<section id="security">
+		<h2>Security posture</h2>
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Surface</th><th>State</th><th>Consequence</th></tr>
+				</thead>
+				<tbody>
+					<tr><td>TLS certificates</td><td>Not verified</td><td>Encryption without authentication; MITM is undetected.</td></tr>
+					<tr><td>TLS DRBG</td><td>Weak (RDTSC/ticks/MAC)</td><td>Not suitable for high-value secrets.</td></tr>
+					<tr><td>WebDAV</td><td>No authentication</td><td>Anyone on the LAN can read mounts and write <code>/share</code>.</td></tr>
+					<tr><td>NIC ownership</td><td>One process at a time</td><td>Packet-level commands are mutually exclusive; a killed owner is force-released.</td></tr>
+					<tr><td>Kernel/user isolation</td><td>None (identity map)</td><td>A ring-3 bug can reach any mapped kernel page.</td></tr>
+				</tbody>
+			</table>
+		</div>
+	</section>
+
+	<section id="sources">
+		<h2>Source map</h2>
+		<ul class="filelist">
+			<li><code>netdev.c</code>, <code>netdev.h</code> — registry</li>
+			<li><code>e1000e.c</code>, <code>r8168.c</code>, <code>ne2000.c</code>, <code>asix.c</code></li>
+			<li><code>net.c</code>, <code>net.h</code> — ARP/ICMP/UDP/IP</li>
+			<li><code>dhcp.c</code>, <code>dns.c</code></li>
+			<li><code>tcp.c</code>, <code>tcp.h</code> — client + listener</li>
+			<li><code>tls.c</code>, <code>tls_*.c</code> — TLS 1.3</li>
+			<li><code>sys_net.c</code> — ring-3 service</li>
+			<li><code>netlog.c</code>, <code>netkexec.c</code></li>
+			<li><code>uhttp.c</code>, <code>ucmd_curl.c</code>, <code>ucmd_websrv.c</code></li>
+		</ul>
+	</section>
+</main>
+
+<footer class="site-footer">
+	<div class="inner">
+		<p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
+		<p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
+	</div>
+</footer>
+</body>
+</html>

+ 987 - 0
docs/style.css

@@ -0,0 +1,987 @@
+/* NebOS architecture documentation — shared styles.
+ * Static, dependency-free, and readable offline.  Dark is the default;
+ * the light palette follows the operating system preference. */
+
+:root {
+	color-scheme: dark;
+	--bg: #0c0f14;
+	--bg-soft: #10141b;
+	--panel: #151a23;
+	--panel-2: #1b212c;
+	--panel-3: #222a37;
+	--text: #e7eaf0;
+	--muted: #9aa5b6;
+	--faint: #6d7788;
+	--line: #2a3241;
+	--line-soft: #222936;
+	--accent: #b79cff;
+	--accent-strong: #8b5cf6;
+	--accent-dim: #2a2342;
+	--green: #5dde94;
+	--green-dim: #173326;
+	--amber: #f4cb6b;
+	--amber-dim: #332a16;
+	--red: #ff8279;
+	--red-dim: #351d1e;
+	--blue: #74b9ff;
+	--blue-dim: #162a3c;
+	--code: #090c11;
+	--code-text: #d9e0eb;
+	--shadow: 0 18px 48px rgba(0, 0, 0, 0.32);
+	--radius: 12px;
+	--radius-sm: 8px;
+	--wrap: 1120px;
+	--mono: ui-monospace, "SFMono-Regular", "Cascadia Mono", "Roboto Mono",
+		Menlo, Consolas, "Liberation Mono", monospace;
+	--sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto,
+		"Helvetica Neue", Arial, sans-serif;
+}
+
+@media (prefers-color-scheme: light) {
+	:root {
+		color-scheme: light;
+		--bg: #f6f7f9;
+		--bg-soft: #eef0f4;
+		--panel: #ffffff;
+		--panel-2: #f1f3f7;
+		--panel-3: #e7eaf1;
+		--text: #1c2330;
+		--muted: #566173;
+		--faint: #7b8798;
+		--line: #d7dce6;
+		--line-soft: #e4e8ef;
+		--accent: #6236c8;
+		--accent-strong: #7048d8;
+		--accent-dim: #ece5ff;
+		--green: #087a45;
+		--green-dim: #ddf5e9;
+		--amber: #8a5d00;
+		--amber-dim: #fff2cf;
+		--red: #b42318;
+		--red-dim: #ffe4e1;
+		--blue: #0b63a3;
+		--blue-dim: #dcefff;
+		--code: #f0f2f6;
+		--code-text: #1c2330;
+		--shadow: 0 18px 48px rgba(28, 35, 48, 0.1);
+	}
+}
+
+* {
+	box-sizing: border-box;
+}
+
+html {
+	scroll-behavior: smooth;
+}
+
+body {
+	margin: 0;
+	background:
+		radial-gradient(900px 420px at 12% -8%, rgba(139, 92, 246, 0.13), transparent 70%),
+		radial-gradient(700px 380px at 92% 0%, rgba(43, 108, 176, 0.1), transparent 72%),
+		var(--bg);
+	color: var(--text);
+	font: 16px/1.68 var(--sans);
+	-webkit-font-smoothing: antialiased;
+}
+
+::selection {
+	background: var(--accent-strong);
+	color: #fff;
+}
+
+a {
+	color: var(--accent);
+	text-decoration-thickness: 0.08em;
+	text-underline-offset: 0.18em;
+}
+
+a:hover {
+	color: var(--text);
+}
+
+:focus-visible {
+	outline: 2px solid var(--accent);
+	outline-offset: 3px;
+	border-radius: 4px;
+}
+
+.skip {
+	position: absolute;
+	top: -6rem;
+	left: 1rem;
+	z-index: 100;
+	padding: 0.6rem 0.9rem;
+	border: 1px solid var(--accent);
+	border-radius: var(--radius-sm);
+	background: var(--panel);
+	color: var(--text);
+	font-size: 0.88rem;
+	text-decoration: none;
+}
+
+.skip:focus {
+	top: 0.75rem;
+}
+
+/* ---- header ---------------------------------------------------------- */
+
+.site-header {
+	position: sticky;
+	top: 0;
+	z-index: 20;
+	display: flex;
+	align-items: center;
+	flex-wrap: wrap;
+	gap: 0.9rem 1.4rem;
+	padding: 0.72rem max(1.25rem, calc((100% - var(--wrap)) / 2));
+	border-bottom: 1px solid var(--line);
+	background: var(--bg-soft);
+	box-shadow: 0 1px 0 rgba(255, 255, 255, 0.03);
+}
+
+.brand {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.62rem;
+	color: var(--text);
+	font-weight: 650;
+	letter-spacing: -0.015em;
+	text-decoration: none;
+}
+
+.brand:hover {
+	color: var(--text);
+}
+
+.brand-mark {
+	position: relative;
+	width: 23px;
+	height: 23px;
+	flex: 0 0 auto;
+	border-radius: 7px;
+	background: linear-gradient(135deg, var(--accent-strong), #4f9de8);
+	box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.22);
+}
+
+.brand-mark::after {
+	content: "";
+	position: absolute;
+	inset: 6px;
+	border: 2px solid rgba(255, 255, 255, 0.86);
+	border-left-color: transparent;
+	border-radius: 3px;
+}
+
+.brand-sub {
+	margin-left: 0.15rem;
+	color: var(--muted);
+	font: 500 0.72rem/1 var(--mono);
+	letter-spacing: 0.1em;
+	text-transform: uppercase;
+}
+
+.site-nav {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.15rem;
+	margin-left: auto;
+}
+
+.site-nav a {
+	padding: 0.35rem 0.58rem;
+	border-radius: 7px;
+	color: var(--muted);
+	font-size: 0.84rem;
+	font-weight: 520;
+	text-decoration: none;
+	white-space: nowrap;
+}
+
+.site-nav a:hover {
+	background: var(--panel-2);
+	color: var(--text);
+}
+
+.site-nav a[aria-current="page"] {
+	background: var(--accent-dim);
+	color: var(--accent);
+}
+
+/* ---- layout ---------------------------------------------------------- */
+
+.page {
+	width: min(var(--wrap), 100% - 2.5rem);
+	margin: 0 auto;
+	padding: 3.4rem 0 4.5rem;
+}
+
+.page-head {
+	max-width: 880px;
+}
+
+.kicker {
+	margin: 0 0 0.55rem;
+	color: var(--accent);
+	font: 650 0.72rem/1.3 var(--mono);
+	letter-spacing: 0.16em;
+	text-transform: uppercase;
+}
+
+h1,
+h2,
+h3,
+h4 {
+	color: var(--text);
+	line-height: 1.18;
+	letter-spacing: -0.025em;
+}
+
+h1 {
+	margin: 0;
+	font-size: clamp(2.15rem, 5.4vw, 3.55rem);
+	font-weight: 700;
+}
+
+h2 {
+	margin: 2.6rem 0 0.9rem;
+	padding-top: 1.4rem;
+	border-top: 1px solid var(--line);
+	font-size: clamp(1.35rem, 2.4vw, 1.7rem);
+	font-weight: 650;
+}
+
+h3 {
+	margin: 1.7rem 0 0.5rem;
+	font-size: 1.12rem;
+	font-weight: 650;
+}
+
+h4 {
+	margin: 1.1rem 0 0.35rem;
+	font-size: 0.95rem;
+	font-weight: 650;
+}
+
+p {
+	max-width: 82ch;
+	margin: 0.65rem 0;
+}
+
+ul,
+ol {
+	max-width: 82ch;
+	padding-left: 1.25rem;
+}
+
+li {
+	margin: 0.28rem 0;
+}
+
+li > ul,
+li > ol {
+	margin: 0.3rem 0;
+}
+
+.lede {
+	max-width: 72ch;
+	margin: 0.9rem 0 0;
+	color: var(--muted);
+	font-size: clamp(1.03rem, 1.55vw, 1.22rem);
+	line-height: 1.62;
+}
+
+.meta {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.42rem;
+	margin-top: 1.25rem;
+}
+
+.pill {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.32rem;
+	padding: 0.22rem 0.62rem;
+	border: 1px solid var(--line);
+	border-radius: 999px;
+	background: var(--panel);
+	color: var(--muted);
+	font: 500 0.78rem/1.5 var(--mono);
+}
+
+.pill strong {
+	color: var(--text);
+	font-weight: 600;
+}
+
+.pill.accent {
+	border-color: color-mix(in srgb, var(--accent) 40%, var(--line));
+	color: var(--accent);
+}
+
+.pill.green {
+	border-color: color-mix(in srgb, var(--green) 35%, var(--line));
+	color: var(--green);
+}
+
+/* ---- table of contents ---------------------------------------------- */
+
+.toc {
+	margin: 2.1rem 0 0;
+	padding: 1rem 1.15rem;
+	border: 1px solid var(--line);
+	border-radius: var(--radius);
+	background: var(--panel);
+}
+
+.toc h2 {
+	margin: 0 0 0.6rem;
+	padding: 0;
+	border: 0;
+	font-size: 0.78rem;
+	font-weight: 650;
+	letter-spacing: 0.12em;
+	text-transform: uppercase;
+	color: var(--muted);
+}
+
+.toc ul {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.38rem;
+	max-width: none;
+	margin: 0;
+	padding: 0;
+	list-style: none;
+}
+
+.toc a {
+	display: inline-block;
+	padding: 0.2rem 0.58rem;
+	border: 1px solid var(--line);
+	border-radius: 999px;
+	color: var(--muted);
+	font-size: 0.8rem;
+	text-decoration: none;
+}
+
+.toc a:hover {
+	border-color: var(--accent);
+	color: var(--accent);
+}
+
+section {
+	scroll-margin-top: 5.5rem;
+}
+
+/* ---- cards ----------------------------------------------------------- */
+
+.grid {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(235px, 1fr));
+	gap: 0.95rem;
+	margin: 1.2rem 0;
+}
+
+.card {
+	position: relative;
+	display: block;
+	padding: 1.12rem 1.15rem 1.2rem;
+	border: 1px solid var(--line);
+	border-radius: var(--radius);
+	background: linear-gradient(180deg, var(--panel), var(--bg-soft));
+	color: inherit;
+	text-decoration: none;
+	transition: border-color 120ms ease, transform 120ms ease, box-shadow 120ms ease;
+}
+
+a.card:hover {
+	border-color: color-mix(in srgb, var(--accent) 65%, var(--line));
+	box-shadow: var(--shadow);
+	color: inherit;
+	transform: translateY(-2px);
+}
+
+.card::before {
+	content: "";
+	position: absolute;
+	top: -1px;
+	left: 1rem;
+	right: 1rem;
+	height: 2px;
+	border-radius: 2px;
+	background: linear-gradient(90deg, var(--accent-strong), transparent);
+	opacity: 0;
+	transition: opacity 120ms ease;
+}
+
+a.card:hover::before {
+	opacity: 1;
+}
+
+.card h3 {
+	margin: 0 0 0.32rem;
+	font-size: 1.05rem;
+}
+
+.card p {
+	margin: 0;
+	color: var(--muted);
+	font-size: 0.91rem;
+	line-height: 1.55;
+}
+
+.card .card-tag {
+	display: inline-block;
+	margin-top: 0.75rem;
+	color: var(--accent);
+	font: 500 0.72rem/1 var(--mono);
+	letter-spacing: 0.05em;
+	text-transform: uppercase;
+}
+
+/* ---- callouts -------------------------------------------------------- */
+
+.note,
+.warn,
+.tip {
+	max-width: 86ch;
+	margin: 1.15rem 0;
+	padding: 0.82rem 1rem;
+	border: 1px solid var(--line);
+	border-left: 3px solid var(--blue);
+	border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+	background: var(--blue-dim);
+	color: var(--text);
+	font-size: 0.93rem;
+}
+
+.warn {
+	border-left-color: var(--amber);
+	background: var(--amber-dim);
+}
+
+.tip {
+	border-left-color: var(--green);
+	background: var(--green-dim);
+}
+
+.note strong,
+.warn strong,
+.tip strong {
+	color: var(--text);
+}
+
+.note p:first-child,
+.warn p:first-child,
+.tip p:first-child {
+	margin-top: 0;
+}
+
+.note p:last-child,
+.warn p:last-child,
+.tip p:last-child {
+	margin-bottom: 0;
+}
+
+/* ---- tables ---------------------------------------------------------- */
+
+.table-wrap {
+	max-width: 100%;
+	margin: 1.1rem 0;
+	overflow-x: auto;
+	border: 1px solid var(--line);
+	border-radius: var(--radius);
+	background: var(--panel);
+}
+
+table {
+	width: 100%;
+	border-collapse: collapse;
+	font-size: 0.9rem;
+}
+
+th,
+td {
+	padding: 0.58rem 0.78rem;
+	border-bottom: 1px solid var(--line-soft);
+	text-align: left;
+	vertical-align: top;
+}
+
+th {
+	background: var(--panel-2);
+	color: var(--muted);
+	font: 600 0.74rem/1.45 var(--mono);
+	letter-spacing: 0.06em;
+	text-transform: uppercase;
+	white-space: nowrap;
+}
+
+tr:last-child td {
+	border-bottom: 0;
+}
+
+tbody tr:hover {
+	background: color-mix(in srgb, var(--panel-2) 55%, transparent);
+}
+
+td code,
+th code {
+	white-space: nowrap;
+}
+
+/* ---- code ------------------------------------------------------------ */
+
+code {
+	padding: 0.08em 0.34em;
+	border: 1px solid var(--line-soft);
+	border-radius: 5px;
+	background: var(--panel-2);
+	color: var(--text);
+	font: 0.88em/1.4 var(--mono);
+}
+
+pre {
+	max-width: 100%;
+	margin: 1rem 0;
+	padding: 1rem 1.1rem;
+	overflow-x: auto;
+	border: 1px solid var(--line);
+	border-radius: var(--radius);
+	background: var(--code);
+	color: var(--code-text);
+	font: 0.83rem/1.6 var(--mono);
+	tab-size: 8;
+}
+
+pre code {
+	padding: 0;
+	border: 0;
+	background: none;
+	color: inherit;
+	font-size: inherit;
+	white-space: pre;
+}
+
+.file {
+	display: inline-block;
+	padding: 0.05rem 0.38rem;
+	border: 1px solid color-mix(in srgb, var(--accent) 30%, var(--line));
+	border-radius: 5px;
+	background: var(--accent-dim);
+	color: var(--accent);
+	font: 0.82em/1.45 var(--mono);
+	white-space: nowrap;
+}
+
+.tag {
+	display: inline-block;
+	padding: 0.02rem 0.42rem;
+	border: 1px solid var(--line);
+	border-radius: 999px;
+	background: var(--panel-2);
+	color: var(--muted);
+	font: 0.72em/1.5 var(--mono);
+	letter-spacing: 0.03em;
+	white-space: nowrap;
+}
+
+.tag.green {
+	border-color: color-mix(in srgb, var(--green) 35%, var(--line));
+	background: var(--green-dim);
+	color: var(--green);
+}
+
+.tag.amber {
+	border-color: color-mix(in srgb, var(--amber) 35%, var(--line));
+	background: var(--amber-dim);
+	color: var(--amber);
+}
+
+.tag.blue {
+	border-color: color-mix(in srgb, var(--blue) 35%, var(--line));
+	background: var(--blue-dim);
+	color: var(--blue);
+}
+
+/* ---- charts and diagrams -------------------------------------------- */
+
+.figure {
+	margin: 1.35rem 0;
+	padding: 1.05rem 1.15rem 0.95rem;
+	border: 1px solid var(--line);
+	border-radius: var(--radius);
+	background:
+		linear-gradient(180deg, color-mix(in srgb, var(--panel-2) 45%, transparent), transparent),
+		var(--panel);
+}
+
+.figure svg {
+	display: block;
+	width: 100%;
+	height: auto;
+}
+
+.figure figcaption {
+	margin-top: 0.8rem;
+	color: var(--muted);
+	font-size: 0.83rem;
+	line-height: 1.55;
+}
+
+.figure figcaption strong {
+	color: var(--text);
+	font-weight: 600;
+}
+
+.svg-box {
+	fill: var(--panel-2);
+	stroke: var(--line);
+	stroke-width: 1.5;
+}
+
+.svg-box.accent {
+	fill: var(--accent-dim);
+	stroke: var(--accent);
+}
+
+.svg-box.green {
+	fill: var(--green-dim);
+	stroke: var(--green);
+}
+
+.svg-box.blue {
+	fill: var(--blue-dim);
+	stroke: var(--blue);
+}
+
+.svg-box.amber {
+	fill: var(--amber-dim);
+	stroke: var(--amber);
+}
+
+.svg-text {
+	fill: var(--text);
+	font-family: var(--mono);
+	font-size: 13px;
+	font-weight: 600;
+}
+
+.svg-sub {
+	fill: var(--muted);
+	font-family: var(--mono);
+	font-size: 11px;
+}
+
+.svg-tiny {
+	fill: var(--faint);
+	font-family: var(--mono);
+	font-size: 10px;
+}
+
+.svg-line {
+	fill: none;
+	stroke: var(--faint);
+	stroke-width: 1.5;
+}
+
+.svg-line.accent {
+	stroke: var(--accent);
+}
+
+.svg-line.green {
+	stroke: var(--green);
+}
+
+.svg-line.blue {
+	stroke: var(--blue);
+}
+
+.svg-line.amber {
+	stroke: var(--amber);
+}
+
+.svg-dash {
+	stroke-dasharray: 5 4;
+}
+
+.diagram-legend {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.55rem 1.1rem;
+	margin-top: 0.7rem;
+	color: var(--muted);
+	font-size: 0.78rem;
+}
+
+.swatch {
+	display: inline-block;
+	width: 0.72rem;
+	height: 0.72rem;
+	margin-right: 0.35rem;
+	border: 1px solid var(--line);
+	border-radius: 3px;
+	background: var(--panel-2);
+	vertical-align: -0.04rem;
+}
+
+.swatch.accent {
+	border-color: var(--accent);
+	background: var(--accent-dim);
+}
+
+.swatch.green {
+	border-color: var(--green);
+	background: var(--green-dim);
+}
+
+.swatch.blue {
+	border-color: var(--blue);
+	background: var(--blue-dim);
+}
+
+.swatch.amber {
+	border-color: var(--amber);
+	background: var(--amber-dim);
+}
+
+/* Horizontal bar chart (HTML, no JavaScript). */
+.bars {
+	display: grid;
+	gap: 0.62rem;
+	margin: 0.4rem 0 0.2rem;
+}
+
+.bar-row {
+	display: grid;
+	grid-template-columns: minmax(7.5rem, 12rem) 1fr 3.6rem;
+	gap: 0.8rem;
+	align-items: center;
+	font-size: 0.84rem;
+}
+
+.bar-label {
+	color: var(--text);
+	font-family: var(--mono);
+	font-size: 0.78rem;
+}
+
+.bar-track {
+	height: 0.78rem;
+	overflow: hidden;
+	border: 1px solid var(--line-soft);
+	border-radius: 999px;
+	background: var(--panel-2);
+}
+
+.bar-fill {
+	display: block;
+	width: var(--w, 0%);
+	height: 100%;
+	border-radius: inherit;
+	background: linear-gradient(90deg, var(--accent-strong), var(--accent));
+}
+
+.bar-fill.green {
+	background: linear-gradient(90deg, var(--green), color-mix(in srgb, var(--green) 55%, var(--blue)));
+}
+
+.bar-fill.blue {
+	background: linear-gradient(90deg, var(--blue), var(--accent));
+}
+
+.bar-value {
+	color: var(--muted);
+	font-family: var(--mono);
+	font-size: 0.76rem;
+	text-align: right;
+	white-space: nowrap;
+}
+
+.chart-note {
+	margin: 0.75rem 0 0;
+	color: var(--faint);
+	font-size: 0.78rem;
+}
+
+/* ---- details / source map ------------------------------------------- */
+
+details {
+	margin: 1rem 0;
+	border: 1px solid var(--line);
+	border-radius: var(--radius-sm);
+	background: var(--panel);
+}
+
+summary {
+	padding: 0.7rem 0.9rem;
+	cursor: pointer;
+	color: var(--text);
+	font-size: 0.9rem;
+	font-weight: 550;
+}
+
+summary:hover {
+	color: var(--accent);
+}
+
+details[open] summary {
+	border-bottom: 1px solid var(--line);
+}
+
+details .details-body {
+	padding: 0.1rem 0.9rem 0.6rem;
+}
+
+.filelist {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(230px, 1fr));
+	gap: 0.45rem 1rem;
+	max-width: none;
+	margin: 0.7rem 0;
+	padding: 0;
+	list-style: none;
+}
+
+.filelist li {
+	margin: 0;
+	color: var(--muted);
+	font-size: 0.86rem;
+}
+
+.filelist code {
+	font-size: 0.8rem;
+}
+
+/* ---- footer ---------------------------------------------------------- */
+
+.site-footer {
+	margin-top: 2rem;
+	border-top: 1px solid var(--line);
+	background: var(--bg-soft);
+}
+
+.site-footer .inner {
+	display: flex;
+	flex-wrap: wrap;
+	justify-content: space-between;
+	gap: 0.5rem 1.5rem;
+	width: min(var(--wrap), 100% - 2.5rem);
+	margin: 0 auto;
+	padding: 1.35rem 0 1.5rem;
+	color: var(--muted);
+	font-size: 0.82rem;
+}
+
+.site-footer p {
+	max-width: none;
+	margin: 0;
+}
+
+.site-footer code {
+	font-size: 0.78rem;
+}
+
+/* ---- small screens --------------------------------------------------- */
+
+@media (max-width: 760px) {
+	.site-header {
+		padding: 0.65rem 1.1rem;
+	}
+
+	.site-nav {
+		width: 100%;
+		margin-left: 0;
+		flex-wrap: nowrap;
+		gap: 0.1rem;
+		overflow-x: auto;
+		padding-bottom: 0.15rem;
+		scrollbar-width: thin;
+	}
+
+	.site-nav a {
+		flex: 0 0 auto;
+		padding: 0.3rem 0.45rem;
+		font-size: 0.79rem;
+	}
+
+	.page {
+		width: min(var(--wrap), 100% - 1.7rem);
+		padding-top: 2.2rem;
+	}
+
+	.grid {
+		grid-template-columns: 1fr;
+	}
+
+	.bar-row {
+		grid-template-columns: 6.8rem 1fr 3.1rem;
+		gap: 0.5rem;
+	}
+
+	.filelist {
+		grid-template-columns: 1fr;
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	html {
+		scroll-behavior: auto;
+	}
+
+	.card,
+	a.card:hover {
+		transition: none;
+		transform: none;
+	}
+}
+
+@media print {
+	:root {
+		color-scheme: light;
+		--bg: #fff;
+		--bg-soft: #fff;
+		--panel: #fff;
+		--panel-2: #f4f4f4;
+		--text: #111;
+		--muted: #444;
+		--line: #bbb;
+		--accent: #4a2bb3;
+		--code: #f5f5f5;
+	}
+
+	body {
+		background: #fff;
+		font-size: 11pt;
+	}
+
+	.site-header,
+	.toc,
+	.skip {
+		display: none;
+	}
+
+	.page {
+		width: 100%;
+		padding: 0;
+	}
+
+	a {
+		color: #111;
+		text-decoration: underline;
+	}
+
+	.figure,
+	.table-wrap,
+	pre,
+	.card {
+		break-inside: avoid;
+	}
+
+	h2 {
+		break-after: avoid;
+	}
+}

+ 344 - 0
docs/userland.html

@@ -0,0 +1,344 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Userland | NebOS Architecture</title>
+<meta name="description" content="NebOS userland: ring-3 address space, ELF loading, the syscall ABI, the shell and PATH dispatch, the 42-command pack, GUI applications and the browser.">
+<link rel="icon" href="favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+
+<header class="site-header">
+	<a class="brand" href="index.html">
+		<span class="brand-mark" aria-hidden="true"></span>
+		<span>NebOS <span class="brand-sub">Architecture</span></span>
+	</a>
+	<nav class="site-nav" aria-label="Architecture sections">
+		<a href="index.html">Overview</a>
+		<a href="boot.html">Boot</a>
+		<a href="memory.html">Memory</a>
+		<a href="cpu.html">CPU</a>
+		<a href="drivers.html">Drivers</a>
+		<a href="filesystems.html">Filesystems</a>
+		<a href="graphics.html">Graphics</a>
+		<a href="network.html">Network</a>
+		<a href="userland.html" aria-current="page">Userland</a>
+		<a href="development.html">Development</a>
+	</nav>
+</header>
+
+<main id="main" class="page">
+	<div class="page-head">
+		<p class="kicker">Userland</p>
+		<h1>Commands are ELFs. The shell is a dispatcher.</h1>
+		<p class="lede">
+			Ring-3 programs are freestanding ELFs linked at <code>0x40000000</code>.
+			The shell resolves a command name against builtins, the per-terminal
+			PATH and the kernel command registry, then spawns it with one
+			argument string. The command pack supplies 42 PATH commands by default.
+		</p>
+		<div class="meta">
+			<span class="pill">int 0x80</span>
+			<span class="pill">one string argument</span>
+			<span class="pill">42 PATH commands</span>
+			<span class="pill">8 TTYs · 8 windows</span>
+		</div>
+	</div>
+
+	<nav class="toc" aria-label="On this page">
+		<h2>On this page</h2>
+		<ul>
+			<li><a href="#model">Ring-3 model</a></li>
+			<li><a href="#spawn">Spawn path</a></li>
+			<li><a href="#syscalls">Syscall ABI</a></li>
+			<li><a href="#shell">Shell &amp; PATH</a></li>
+			<li><a href="#registry">Kernel commands</a></li>
+			<li><a href="#pack">Command pack</a></li>
+			<li><a href="#apps">GUI applications</a></li>
+			<li><a href="#browser">Browser</a></li>
+			<li><a href="#legacy">Legacy ring-0 programs</a></li>
+			<li><a href="#sources">Source map</a></li>
+		</ul>
+	</nav>
+
+	<section id="model">
+		<h2>Ring-3 model</h2>
+		<p>
+			A user process gets a page directory cloned from the kernel identity
+			map, a 2 MB image/stack window at <code>0x40000000</code>, an optional
+			4 MB canvas at <code>0x50000000</code> and a growable heap at
+			<code>0x60000000</code>. The kernel remains mapped because paging is
+			identity-mapped; this is isolation in privilege level only, not a
+			separate address space.
+		</p>
+		<ul>
+			<li><strong>No libc.</strong> Commands include <span class="file">ucmd_lib.h</span> for syscall wrappers and string helpers.</li>
+			<li><strong>One argument.</strong> The shell passes the raw remainder of the line as a C string at the top of the user stack; <code>_start(const char *arg)</code> needs no crt0.</li>
+			<li><strong>Inherited context.</strong> Each process inherits the spawning terminal's cwd and TTY id; the file syscalls resolve relative paths against the PCB cwd.</li>
+			<li><strong>Page-fault policy.</strong> A ring-3 fault kills the process and prints a short message; it does not halt the kernel.</li>
+		</ul>
+		<div class="note">
+			<p><strong>Not a sandbox.</strong> Because physical and virtual addresses
+			are identical and the kernel is mapped, a ring-3 bug can read or write
+			any mapped kernel page. The privilege boundary protects against
+			accidental corruption from ordinary code, not against malicious code.</p>
+		</div>
+	</section>
+
+	<section id="spawn">
+		<h2>Spawn path</h2>
+		<figure class="figure">
+			<svg viewBox="0 0 920 232" role="img" aria-labelledby="spawn-title spawn-desc">
+				<title id="spawn-title">Command spawn path</title>
+				<desc id="spawn-desc">A shell line is matched against builtins, then the PATH, then the kernel registry. A PATH hit loads the ELF through the VFS and creates a ring-3 process; a kernel registry hit spawns a kernel thread.</desc>
+
+				<rect class="svg-box" x="20" y="24" width="160" height="58" rx="9"/>
+				<text class="svg-text" x="38" y="49">shell line</text>
+				<text class="svg-sub" x="38" y="69">word + remainder</text>
+
+				<rect class="svg-box blue" x="216" y="24" width="160" height="58" rx="9"/>
+				<text class="svg-text" x="234" y="49">builtins</text>
+				<text class="svg-sub" x="234" y="69">cd · path · help · clear</text>
+
+				<rect class="svg-box accent" x="412" y="24" width="180" height="58" rx="9"/>
+				<text class="svg-text" x="430" y="49">PATH lookup</text>
+				<text class="svg-sub" x="430" y="69">/ramfs/bin by default</text>
+
+				<rect class="svg-box" x="628" y="24" width="270" height="58" rx="9"/>
+				<text class="svg-text" x="646" y="49">kernel registry</text>
+				<text class="svg-sub" x="646" y="69">privileged / inline commands</text>
+
+				<path class="svg-line" d="M180 53h24"/>
+				<path class="svg-line" d="M196 47l7 6-7 6"/>
+				<path class="svg-line" d="M376 53h24"/>
+				<path class="svg-line" d="M392 47l7 6-7 6"/>
+				<path class="svg-line" d="M592 53h24"/>
+				<path class="svg-line" d="M608 47l7 6-7 6"/>
+
+				<rect class="svg-box green" x="216" y="146" width="376" height="58" rx="9"/>
+				<text class="svg-text" x="236" y="171">VFS load → process_create_user</text>
+				<text class="svg-sub" x="236" y="191">ELF segments · page directory · 8-page stack · arg</text>
+
+				<rect class="svg-box amber" x="628" y="146" width="270" height="58" rx="9"/>
+				<text class="svg-text" x="646" y="171">kernel process</text>
+				<text class="svg-sub" x="646" y="191">ring 0 · pinned to the BSP</text>
+
+				<path class="svg-line accent" d="M502 82v54"/>
+				<path class="svg-line accent" d="M496 128l6 7 6-7"/>
+				<path class="svg-line" d="M763 82v54"/>
+				<path class="svg-line" d="M757 128l6 7 6-7"/>
+			</svg>
+			<figcaption>
+				<strong>A packed command can shadow a kernel command.</strong>
+				The PATH is searched before the kernel registry, so a new
+				<code>bin/&lt;name&gt;</code> changes behaviour without editing the
+				kernel. Builtins are handled inline, before either lookup.
+			</figcaption>
+		</figure>
+	</section>
+
+	<section id="syscalls">
+		<h2>Syscall ABI</h2>
+		<p>
+			The gate is <code>int 0x80</code>. <code>eax</code> carries the
+			number, <code>ebx</code>/<code>ecx</code>/<code>edx</code> the first
+			three arguments, and the negative <code>SYS_E*</code> codes are
+			stable. The wrappers in <span class="file">ucmd_lib.h</span> cover
+			zero to three arguments.
+		</p>
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Group</th><th>Numbers</th><th>Purpose</th></tr>
+				</thead>
+				<tbody>
+					<tr><td>Console &amp; time</td><td>1–4, 56, 69</td><td>putstr, ticks, sleep, exit, RTC time/date</td></tr>
+					<tr><td>Files</td><td>5–11, 48, 98</td><td>whole-file read/write, list, unlink, mkdir/rmdir, mounts, cwd, stat</td></tr>
+					<tr><td>System info</td><td>12–16, 49–51, 91–92, 102</td><td>memory, E820, mouse, storage, blkdev, procinfo, cursor, CPU temp, sensors, EC</td></tr>
+					<tr><td>Network</td><td>17–47</td><td>NIC config/acquire, raw frames, DHCP/DNS, TCP client, ARP, cwd</td></tr>
+					<tr><td>Window &amp; WM</td><td>55, 57–72, 80, 83–87</td><td>key poll, WM attach/info/map/present/create_term, window create/present/input/resize</td></tr>
+					<tr><td>Process &amp; memory</td><td>73–79, 81, 88–90</td><td>TTY, spawn, alive, kill, chdir, scheduler info, heap alloc/grow/free</td></tr>
+					<tr><td>TCP server</td><td>93–97, 99–101</td><td>listen, accept, server recv/send/close, peer, speed, MAC set</td></tr>
+				</tbody>
+			</table>
+		</div>
+		<p>
+			The file service is whole-file, not stream-oriented. The network
+			service has a single TCP connection and one NIC owner. There is no
+			<code>fork</code>, <code>exec</code> or shared memory: a command
+			either runs as its own process from an ELF or calls a kernel command.
+		</p>
+	</section>
+
+	<section id="shell">
+		<h2>Shell &amp; PATH</h2>
+		<p>
+			The windowed shell is <span class="file">ucmd_term.c</span>; the
+			kernel-side <span class="file">terminal.c</span> holds the privileged
+			command registry used through <code>SYS_SPAWN_KCMD</code>. There is
+			no kernel terminal fallback; the WM spawns the first terminal once
+			storage is ready. Each terminal has a current working directory and
+			a PATH (default <code>/ramfs/bin</code>). Pressing Tab completes
+			builtin and PATH names; <code>help</code> lists both.
+		</p>
+		<ul>
+			<li><strong>Dispatch order.</strong> Builtins → PATH file → kernel command. A PATH hit loads the ELF through the VFS and spawns it as ring 3.</li>
+			<li><strong>Builtins.</strong> <code>cd</code>, <code>path</code>, <code>help</code>, <code>clear</code>; the ring-3 shell also handles <code>ps</code> and <code>kill</code> inline. <code>bootlog</code> is a kernel command.</li>
+			<li><strong>Arguments.</strong> The raw remainder of the line is passed verbatim; commands parse their own flags.</li>
+			<li><strong>Working directory.</strong> The prompt shows <code>[dir] &gt;</code>; <code>cd</code> changes only the current terminal's cwd, and spawned commands inherit it.</li>
+			<li><strong>Windows.</strong> A window receives keys through its window key queue (<code>SYS_WIN_KEY_WAIT</code>) or the generic <code>SYS_KEY_POLL</code>; closing the window kills its owner process.</li>
+		</ul>
+	</section>
+
+	<section id="registry">
+		<h2>Kernel commands</h2>
+		<p>
+			These commands must run in ring 0 or inline in the shell; they are not
+			files in the pack. The split keeps privileged hardware access out of
+			ring 3 while most user-facing tools remain replaceable ELFs.
+		</p>
+		<div class="table-wrap">
+			<table>
+				<thead>
+					<tr><th>Group</th><th>Commands</th></tr>
+				</thead>
+				<tbody>
+					<tr><td>Shell</td><td><code>cd</code> <code>path</code> <code>help</code> <code>clear</code> <code>bootlog</code></td></tr>
+					<tr><td>Process / scheduler</td><td><code>ps</code> <code>sched</code> <code>renice</code> <code>kill</code> <code>idle</code> <code>cpufreq</code> <code>power</code></td></tr>
+					<tr><td>Hardware / debug</td><td><code>display</code> <code>gfxbench</code> <code>lsusb</code> <code>lspci</code> <code>peek</code> <code>poke</code> <code>format</code> <code>dbg</code> <code>serial</code></td></tr>
+					<tr><td>Network control</td><td><code>netdev</code></td></tr>
+					<tr><td>Boot / power</td><td><code>reboot</code> <code>poweroff</code> <code>kexec</code> <code>run</code> <code>space</code> <code>prog</code></td></tr>
+				</tbody>
+			</table>
+		</div>
+		<p>
+			<code>run</code> and the embedded <code>prog</code>/<code>space</code>
+			programs are the remaining ring-0 user-code path: binaries load at
+			<code>0x80000</code> and call the program API at <code>0x7FF00</code>.
+			Everything else user-facing is a ring-3 ELF.
+		</p>
+	</section>
+
+	<section id="pack">
+		<h2>Command pack</h2>
+		<p>
+			The pack is built from the <code>UCMDS</code> list in the Makefile as
+			<code>bin/&lt;name&gt;</code>, plus <code>hello</code> and the real
+			<code>browser.app</code> and <code>gallery.app</code>. It is mounted
+			read-only at <code>/ramfs</code>; the shell's default PATH points at
+			<code>/ramfs/bin</code>.
+		</p>
+		<div class="grid">
+			<div class="card">
+				<h3>Files &amp; text</h3>
+				<p><code>ls</code> <code>cat</code> <code>save</code> <code>rm</code> <code>mkdir</code> <code>rmdir</code> <code>edit</code> <code>files</code> <code>view</code></p>
+			</div>
+			<div class="card">
+				<h3>System</h3>
+				<p><code>cpuinfo</code> <code>meminfo</code> <code>storage</code> <code>top</code> <code>mouseinfo</code> <code>sensors</code> <code>spin</code> <code>clock</code> <code>colors</code></p>
+			</div>
+			<div class="card">
+				<h3>Network</h3>
+				<p><code>netinfo</code> <code>netip</code> <code>netdns</code> <code>host</code> <code>dhcp</code> <code>ping</code> <code>pong</code> <code>netsend</code> <code>netrecv</code> <code>netlog</code> <code>netconsole</code> <code>netregs</code> <code>netloop</code> <code>netreset</code> <code>net100</code> <code>netmac</code> <code>curl</code> <code>websrv</code></p>
+			</div>
+			<div class="card">
+				<h3>GUI</h3>
+				<p><code>wm</code> <code>term</code> <code>files</code> <code>view</code> <code>mines</code> <code>solitaire</code> <code>gallery</code> <code>browser</code> <code>clock</code> <code>colors</code></p>
+			</div>
+		</div>
+		<p>
+			The launchers <code>bin/browser</code> and <code>bin/gallery</code>
+			forward their argument and cwd, and prefer a development copy under
+			<code>/share</code> (<code>BROWSER</code> or <code>GALLERY</code>)
+			before the pack copy and the FAT fallback on <code>root.img</code>.
+			This lets <code>make browser-dev</code> and <code>make gallery-dev</code>
+			update an app without rebuilding the pack.
+		</p>
+	</section>
+
+	<section id="apps">
+		<h2>GUI applications</h2>
+		<ul>
+			<li><strong>files</strong> — browser for the VFS; opens text in <code>edit</code>, images in <code>view</code>, HTML in <code>browser</code>. First user of ngui.</li>
+			<li><strong>gallery</strong> — live widget and primitive showcase; the real app ships in the pack.</li>
+			<li><strong>solitaire</strong> — Klondike with drag-and-drop, scoring and a win animation.</li>
+			<li><strong>mines</strong> — second ngui canvas app; shares the toolkit and event model.</li>
+			<li><strong>view</strong> — fit/1:1/zoom/pan image viewer, animated GIF playback.</li>
+			<li><strong>edit</strong> — text editor that draws its own text with the 8x16 font.</li>
+			<li><strong>clock</strong> / <strong>colors</strong> — small window canvas demos.</li>
+			<li><strong>wm</strong> / <strong>term</strong> — the ring-3 window manager and terminal launcher used by the desktop.</li>
+		</ul>
+	</section>
+
+	<section id="browser">
+		<h2>Browser</h2>
+		<p>
+			The real browser is <code>bin/browser.app</code> in the pack. It links
+			ngui, the image library, inflate, TLS and uhttp. It owns a 960×640
+			window, a URL bar, history, a status bar and inline images. Network
+			work runs in a headless <code>curl __fetch</code> helper that writes
+			the body and metadata under <code>/share</code>, so the UI keeps
+			drawing and scrolling.
+		</p>
+		<ul>
+			<li><strong>HTML/CSS subset.</strong> External and inline stylesheets, tag/class/id and descendant/child selectors, colours, backgrounds, font size, weights, margins, padding, borders, alignment, percentage widths, basic floats and <code>@media</code> blocks evaluated at a fixed 1000 px viewport.</li>
+			<li><strong>Not supported.</strong> JavaScript, forms, flex/grid, CSS variables, absolute/fixed positioning, standalone image documents, tables with column widths, video/audio.</li>
+			<li><strong>Caps.</strong> 2 MB page body, 832 KB CSS, 6144 DOM nodes, 2304 rules, 16 images; images are downscaled to at most 1000 px wide and decoded into a 24 MB shared arena.</li>
+			<li><strong>Fetching.</strong> Each network fetch starts a one-shot helper process and a fresh TCP/TLS connection; images load one per loop within the viewport plus 160 px.</li>
+			</ul>
+		<p>
+			The browser's default canvas is dark, matching the ngui theme. Pages
+			that set dark text but rely on a white default background can be hard
+			to read; pages with their own full background and colour rules are
+			unaffected. See <a href="graphics.html#images">Graphics → Image
+			library</a> for the decoder limits.
+		</p>
+	</section>
+
+	<section id="legacy">
+		<h2>Legacy ring-0 programs</h2>
+		<p>
+			<code>run &lt;name&gt;</code>, <code>prog</code> and <code>space</code>
+			are the last programs that execute in ring 0. They load as raw
+			binaries at <code>0x80000</code> and use the function-pointer API at
+			<code>0x7FF00</code>. <code>prog</code>/<code>space</code> are also
+			embedded in the kernel image, so a board with no readable filesystem
+			can still run them.
+		</p>
+		<p>
+			These programs draw directly over the WM, which keeps repainting its
+			desktop, so they are demos rather than windowed applications. Moving
+			them to ring 3 would let the fixed low-memory block
+			(<code>0x7FF00</code>/<code>0x80000</code>) go away.
+		</p>
+	</section>
+
+	<section id="sources">
+		<h2>Source map</h2>
+		<ul class="filelist">
+			<li><code>syscall.c</code>, <code>syscall_stub.S</code>, <code>syscall.h</code></li>
+			<li><code>process.c</code> — ELF load and spawn</li>
+			<li><code>elf.c</code> — ELF parser</li>
+			<li><code>ucmd_term.c</code> — windowed shell, scrollback, PATH</li>
+			<li><code>terminal.c</code> — privileged kernel command registry</li>
+			<li><code>ucmd_lib.h</code> — user shim</li>
+			<li><code>ucmd.ld</code> — ring-3 link address</li>
+			<li><code>Makefile</code> — <code>UCMDS</code> and pack rules</li>
+			<li><code>ucmd_*.c</code> — commands</li>
+			<li><code>browser.c</code>, <code>browser_html.c</code>, <code>gallery.c</code></li>
+			<li><code>run.c</code>, <code>run_api.h</code>, <code>prog.c</code>, <code>space.c</code></li>
+		</ul>
+	</section>
+</main>
+
+<footer class="site-footer">
+	<div class="inner">
+		<p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
+		<p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
+	</div>
+</footer>
+</body>
+</html>

+ 1 - 1
efi/efi.h

@@ -1,4 +1,4 @@
-/* Minimal UEFI definitions for the Nebs OS x86-64 loader.
+/* Minimal UEFI definitions for the NebOS x86-64 loader.
  *
  * Only the tables and protocols the loader uses are declared, but the fields
  * before them are in their exact UEFI order so the offsets match the

+ 2 - 2
efi/main.c

@@ -1,4 +1,4 @@
-/* Nebs OS UEFI loader (x86-64).
+/* NebOS UEFI loader (x86-64).
  *
  * The kernel is a 32-bit i586 image linked at 0x7E00.  This loader gives it
  * the same two boot structures the real-mode VESA stage produces:
@@ -172,7 +172,7 @@ static void fail_before(EFI_SYSTEM_TABLE *st, const char *msg)
 	com1_puts("nebos-efi: ");
 	com1_puts(msg);
 	com1_puts("\n");
-	conout_puts(st, "Nebs OS EFI loader: ");
+	conout_puts(st, "NebOS EFI loader: ");
 	conout_puts(st, msg);
 	conout_puts(st, "\n");
 	halt_forever();

+ 1 - 69
io.c

@@ -72,9 +72,7 @@ static struct text_screen io_fallback;
 
 static struct text_screen *io_current_screen(void)
 {
-	struct process *p = current_proc();
-	struct text_screen *s = p ? p->screen : 0;
-	return s ? s : &io_fallback;
+	return &io_fallback;
 }
 
 /* IRQ1: read the controller status first and only read data when the output
@@ -189,23 +187,7 @@ static int io_tty(void)
 	return tty_valid(id) ? id : 0;
 }
 
-void io_clear_screen(void)
-{
-	int id = io_tty();
-
-	if (id) {
-		tty_write_str(id, "\x1b[2J\x1b[H");
-		return;
-	}
-	screen_clear(io_current_screen());
-}
 
-int io_did_scroll(void)
-{
-	if (io_tty())
-		return 0;
-	return screen_did_scroll(io_current_screen());
-}
 
 void io_putchar(char c)
 {
@@ -247,60 +229,10 @@ void io_puthex(unsigned int n)
 	screen_puthex(io_current_screen(), n);
 }
 
-unsigned int io_get_cursor(void)
-{
-	if (io_tty())
-		return 0;
-	return screen_get_cursor(io_current_screen());
-}
 
-void io_set_cursor(unsigned int pos)
-{
-	if (io_tty()) {
-		char buf[16];
-		unsigned int row = pos / 64 + 1, col = pos % 64 + 1, i = 0;
-
-		buf[i++] = 0x1B; buf[i++] = '[';
-		buf[i++] = (char)('0' + row / 10);
-		buf[i++] = (char)('0' + row % 10);
-		buf[i++] = ';';
-		buf[i++] = (char)('0' + col / 10);
-		buf[i++] = (char)('0' + col % 10);
-		buf[i++] = 'H'; buf[i] = '\0';
-		io_putstr(buf);
-		return;
-	}
-	screen_set_cursor(io_current_screen(), pos);
-}
 
-void io_cursor_show_block(void)
-{
-	struct text_screen *s;
 
-	if (io_tty())
-		return;
-	s = io_current_screen();
-	s->cursor_visible = 1;
-	screen_damage_cursor(s);
-}
 
-void io_cursor_hide_block(void)
-{
-	struct text_screen *s;
-
-	if (io_tty())
-		return;
-	s = io_current_screen();
-	s->cursor_visible = 0;
-	screen_damage_cursor(s);
-}
-
-void io_vga_write(unsigned int pos, unsigned short value)
-{
-	if (io_tty())
-		return;
-	screen_put_at(io_current_screen(), pos, value);
-}
 
 void io_drain_keyboard(void)
 {

+ 0 - 7
io.h

@@ -16,16 +16,9 @@ unsigned int io_get_rows(void);
 #define IO_DATETIME_POS   (io_get_cols() - IO_DATETIME_LEN)
 
 void io_init(void);
-void io_clear_screen(void);
-int io_did_scroll(void);  /* returns 1 once after a scroll, then 0 until next scroll */
 void io_putchar(char c);
 void io_putstr(const char *s);
 void io_puthex(unsigned int n);  /* print n as 8 hex digits, no 0x prefix */
-unsigned int io_get_cursor(void);
-void io_set_cursor(unsigned int pos);
-void io_cursor_show_block(void);
-void io_cursor_hide_block(void);
-void io_vga_write(unsigned int pos, unsigned short value);
 void io_drain_keyboard(void);
 
 /* Poll keyboard; returns 0 = no key, 1..255 = ASCII, or an IO_KEY_* code. */

+ 5 - 12
kernel.c

@@ -21,7 +21,6 @@
 #include "process.h"
 #include "ramfs.h"
 #include "sched.h"
-#include "sys_gfx.h"
 #include "thermal.h"
 #include "timer.h"
 #include "tpec.h"
@@ -237,14 +236,11 @@ static void system_housekeeping(void)
 	mouse_poll_update();
 #ifndef NOWM
 	wm_pump_keyboard();
-	wm_blink_cursor();
 #endif
 	netlog_flush();
 #ifndef NOWM
 	wm_handle_kexec();
 	wm_server_supervise();
-	if (wm_server_can_reap())
-		sys_gfx_collect();
 	if (!wm_server_frame_active())
 		vga_fb_flush_budget(VGA_FLUSH_BUDGET_BYTES);
 #else
@@ -495,9 +491,6 @@ void kernel_main(void)
 	 * while storage and the network are still being probed. */
 	wm_server_init();
 	boot_trace("wm init");
-	/* The WM's first frame covers this console; stop drawing before it can
-	 * run, or a later stage line would appear on top of the desktop. */
-	bootcon_set_enabled(0);
 	wm_server_start();
 	boot_trace("wm");
 #else
@@ -530,12 +523,12 @@ void kernel_main(void)
 	vfs_mount_all();
 	boot_trace("storage");
 
-	/* The first terminal is spawned only now: while the boot scan was
-	 * rebuilding the mount table, no user command could touch the disks.
-	 * The desktop itself was already painted from /ramfs. */
+	/* The WM spawns the first terminal once it sees boot_ready: while the
+	 * boot scan was rebuilding the mount table, no user command could touch
+	 * the disks.  The desktop itself was already painted from /ramfs. */
 #ifndef NOWM
-	wm_spawn_terminal();
-	boot_trace("terminal");
+	wm_server_boot_ready();
+	boot_trace("terminal ready");
 #else
 	boot_trace("terminal off");
 #endif

+ 1 - 1
netkexec_send.c

@@ -1,4 +1,4 @@
-/* Push a kernel + rootfs pack to a Nebs OS board over UDP (the board's WM
+/* Push a kernel + rootfs pack to a NebOS board over UDP (the board's WM
  * loop auto-detects the header and jumps into the new kernel).
  *
  *   netkexec_send <board-ip> <port> <entry-hex> <kernel> [pack]

+ 2 - 13
process.c

@@ -15,7 +15,6 @@
 #include "serial.h"
 #include "smp.h"
 #include "sys_fs.h"
-#include "sys_gfx.h"
 #include "sys_mem.h"
 #include "sys_net.h"
 #include "syscall.h"
@@ -161,7 +160,6 @@ static void proc_commit(struct process *p, int slot, const char *name,
 	p->stride = 0;
 	p->vruntime = 0;
 	p->slice_start = 0;
-	p->screen = parent ? parent->screen : (void *)0;
 	p->tty = parent ? parent->tty : 0;
 	if (parent)
 		cwd_copy(p, parent->cwd);
@@ -189,7 +187,6 @@ void process_init(void)
 	idle_procs[0].pid        = 0;
 	idle_procs[0].slot       = PROC_MAX;
 	idle_procs[0].esp        = 0;
-	idle_procs[0].screen     = (void *)0;
 	idle_procs[0].stack_base = 0;  /* bootstrap stack, never freed */
 	idle_procs[0].cr3        = paging_current_cr3();
 	idle_procs[0].kstack_top = (unsigned int)__boot_stack_top;
@@ -540,13 +537,6 @@ int process_create_user(const char *name, const void *image, unsigned int size,
 
 /* Set the output screen of the currently-running process (used by a terminal
    at startup to bind itself to its own screen). */
-void process_set_screen(struct text_screen *screen)
-{
-	struct process *p = current_proc();
-
-	if (p)
-		p->screen = screen;
-}
 
 /* Render target override for the running process (0 = the screen).  Lives in
  * the PCB so a preempted layer draw can never leak into another process. */
@@ -635,7 +625,7 @@ unsigned int process_zombie_count(void)
 
 /* Free switched-out dead processes.  Runs in the kworker (or the idle
  * fallback), not in the PIT handler.  Preemption is disabled while the
- * resources are torn down: sys_gfx_reap()/tty_reap()/the page-table walk are
+ * resources are torn down: tty_reap()/the page-table walk are
  * not re-entrant, matching the old IRQ-context reaper. */
 void process_reap_dead(void)
 {
@@ -653,7 +643,6 @@ void process_reap_dead(void)
 		struct process *next = p->zombie_next;
 
 		sys_net_reap(p->pid);   /* release a held NIC */
-		sys_gfx_reap(p->pid);   /* flag a gfx session dead */
 		tty_reap(p->pid);       /* drop its terminal queue */
 		if (p->stack_base)
 			mm_free_page(p->stack_base);
@@ -665,7 +654,7 @@ void process_reap_dead(void)
 			paging_release_user_range(p->cr3,
 				USER_BASE, USER_STACK_TOP - USER_BASE, 1);
 			paging_release_user_range(p->cr3,
-				USER_GFX_BASE, USER_GFX_RANGE, 0);
+				USER_WIN_BASE, USER_WIN_RANGE, 0);
 			sys_mem_release(p);
 			/* WM surface mappings: page tables only; the shadow/
 			 * terminal/canvas pages belong to the window server. */

+ 4 - 8
process.h

@@ -30,7 +30,6 @@
 #define PROC_NAME_LEN 12
 #define PROC_CWD_MAX  64
 
-struct text_screen;  /* forward decl (see screen.h) */
 struct sys_procinfo; /* forward decl (see syscall.h; `top` snapshot) */
 struct surface;      /* forward decl (see vga.h; render target override) */
 
@@ -40,7 +39,6 @@ struct process {
 	unsigned int pid;
 	unsigned int slot;           /* index in procs[], PROC_MAX for idle */
 	char         name[PROC_NAME_LEN];
-	struct text_screen *screen;  /* output target for io_putchar & co. */
 	unsigned int stack_base;     /* page to free on exit, or 0 (bootstrap/fallback) */
 	unsigned int cr3;            /* physical address of this process's page dir */
 	unsigned int heap_pages;     /* pages mapped at USER_HEAP_BASE, or 0 */
@@ -86,11 +84,10 @@ struct process {
 #define USER_BASE        0x40000000   /* user program link/load address */
 #define USER_STACK_TOP   0x40200000   /* user stack top (grows down) */
 #define USER_STACK_PAGES 8            /* user stack size in 4 KB pages */
-/* Where sys_gfx maps a command's canvas back buffer (see sys_gfx.c).  The
- * mapping is released by the reaper without freeing the canvas pages: the
- * gfx session owns those. */
-#define USER_GFX_BASE    0x50000000
-#define USER_GFX_RANGE   0x00400000   /* one 4 MB slot */
+/* Where a canvas window's back buffer is mapped.  The mapping is released by
+ * the reaper without freeing the canvas pages: the window owns those. */
+#define USER_WIN_BASE    0x50000000
+#define USER_WIN_RANGE   0x00400000   /* one 4 MB slot */
 /* Anonymous per-process heap (SYS_MEM_ALLOC/GROW/FREE): one growable arena
  * above the WM mappings.  Freed by the reaper. */
 #define USER_HEAP_BASE   0x60000000u
@@ -116,7 +113,6 @@ int process_create_user(const char *name, const void *image, unsigned int size,
 int process_create_user_tty(const char *name, const void *image,
 			unsigned int size, const char *arg, const char *cwd,
 			unsigned int tty);
-void process_set_screen(struct text_screen *screen);
 /* Render target override for the running process (0 = the screen). */
 struct surface *process_render_target(void);
 void process_set_render_target(struct surface *s);

+ 1 - 42
screen.c

@@ -7,7 +7,7 @@
 
 /* ---- Damage tracking ----
  *
- * The WM repaints only the cell block that changed, so every mutation of the
+ * The boot console tracks only the cell block that changed, so every mutation of the
  * cell buffer -- or of the cursor, which is drawn as an overlay -- has to mark
  * it: screen_damage_cell() grows the block around a cell, screen_damage_all()
  * covers the whole grid (a scroll or a clear) and screen_damage_cursor() marks
@@ -15,7 +15,6 @@
  */
 static void screen_damage_cell(struct text_screen *s, unsigned int col, unsigned int row)
 {
-	s->damage_seq++;
 	if (!s->dirty) {
 		s->dirty = 1;
 		s->dmg_col0 = s->dmg_col1 = col;
@@ -34,7 +33,6 @@ static void screen_damage_cell(struct text_screen *s, unsigned int col, unsigned
 
 static void screen_damage_all(struct text_screen *s)
 {
-	s->damage_seq++;
 	s->dirty = 1;
 	s->dmg_col0 = 0;
 	s->dmg_col1 = s->cols - 1;
@@ -53,22 +51,7 @@ void screen_damage_cursor(struct text_screen *s)
 	screen_damage_cell(s, pos % s->cols, pos / s->cols);
 }
 
-int screen_damage_block(const struct text_screen *s, unsigned int *col0,
-		unsigned int *row0, unsigned int *cols, unsigned int *rows)
-{
-	if (!s->dirty)
-		return 0;
-	*col0 = s->dmg_col0;
-	*row0 = s->dmg_row0;
-	*cols = s->dmg_col1 - s->dmg_col0 + 1;
-	*rows = s->dmg_row1 - s->dmg_row0 + 1;
-	return 1;
-}
 
-void screen_clear_damage(struct text_screen *s)
-{
-	s->dirty = 0;
-}
 
 void screen_init(struct text_screen *s)
 {
@@ -77,8 +60,6 @@ void screen_init(struct text_screen *s)
 	s->cursor = 0;
 	s->cursor_attr = (SCREEN_ATTR << 8);
 	s->cursor_visible = 0;
-	s->scrolled = 0;
-	s->damage_seq = 0;
 	screen_clear(s);
 }
 
@@ -89,7 +70,6 @@ void screen_clear(struct text_screen *s)
 		s->cells[i] = (unsigned short)((SCREEN_ATTR << 8) | ' ');
 	s->cursor = 0;
 	screen_damage_all(s);
-	s->scrolled = 0;
 }
 
 static void screen_scroll_up(struct text_screen *s)
@@ -117,7 +97,6 @@ void screen_putchar(struct text_screen *s, char c)
 		if (s->cursor >= total) {
 			screen_scroll_up(s);
 			s->cursor = total - ncols;
-			s->scrolled = 1;
 		}
 		s->cursor_attr = (SCREEN_ATTR << 8);
 		screen_damage_cursor(s);
@@ -160,20 +139,7 @@ void screen_puthex(struct text_screen *s, unsigned int n)
 	screen_putstr(s, buf);
 }
 
-unsigned int screen_get_cursor(const struct text_screen *s)
-{
-	return s->cursor;
-}
 
-void screen_set_cursor(struct text_screen *s, unsigned int pos)
-{
-	if (pos >= s->cols * s->rows)
-		return;
-	screen_damage_cursor(s);      /* erase the old cursor cell */
-	s->cursor = pos;
-	s->cursor_attr = (SCREEN_ATTR << 8);
-	screen_damage_cursor(s);
-}
 
 void screen_put_at(struct text_screen *s, unsigned int pos, unsigned short value)
 {
@@ -183,10 +149,3 @@ void screen_put_at(struct text_screen *s, unsigned int pos, unsigned short value
 	}
 }
 
-int screen_did_scroll(struct text_screen *s)
-{
-	if (!s->scrolled)
-		return 0;
-	s->scrolled = 0;
-	return 1;
-}

+ 3 - 19
screen.h

@@ -14,16 +14,10 @@ struct text_screen {
 	unsigned int cursor;          /* linear index 0..cols*rows-1 */
 	unsigned int cursor_attr;
 	unsigned int cursor_visible;
-	/* Pending damage: the inclusive cell block [dmg_col0..dmg_col1] x
-	   [dmg_row0..dmg_row1] that changed since the last render, so the WM
-	   repaints a keystroke's cell instead of the whole window content.
-	   Only the helpers below update it -- screen_damage_block() reports it
-	   and screen_clear_damage() drops it after rendering. */
-	int dirty;                    /* content changed since last WM render */
+	/* Cell rendering bookkeeping for the boot console. */
+	int dirty;                    /* content changed since the last draw */
 	unsigned int dmg_col0, dmg_col1;
 	unsigned int dmg_row0, dmg_row1;
-	unsigned int damage_seq;      /* bumped on every damage mark (WM ACK) */
-	int scrolled;                 /* one-shot, replaces io_did_scroll */
 };
 
 void screen_init(struct text_screen *s);
@@ -31,18 +25,8 @@ void screen_clear(struct text_screen *s);
 void screen_putchar(struct text_screen *s, char c);
 void screen_putstr(struct text_screen *s, const char *str);
 void screen_puthex(struct text_screen *s, unsigned int n);
-unsigned int screen_get_cursor(const struct text_screen *s);
-void screen_set_cursor(struct text_screen *s, unsigned int pos);
 void screen_put_at(struct text_screen *s, unsigned int pos, unsigned short value);
-int screen_did_scroll(struct text_screen *s);
-
-/* Pending damage as a cell block: returns 1 and fills col0, row0, cols and
-   rows when something changed, 0 when the screen is clean. */
-int screen_damage_block(const struct text_screen *s, unsigned int *col0,
-		unsigned int *row0, unsigned int *cols, unsigned int *rows);
-void screen_clear_damage(struct text_screen *s);
-/* Mark the cell the cursor sits in (a blink or a cursor move only changes
-   that cell, but both the old and the new position must be repainted). */
+/* Mark the cell the cursor sits in. */
 void screen_damage_cursor(struct text_screen *s);
 
 #endif

+ 0 - 281
sys_gfx.c

@@ -1,281 +0,0 @@
-/* Window graphics sessions: one double-buffered canvas per window, mapped
- * into the owning ring-3 process.  The process draws into the mapped back
- * buffer; SYS_GFX_PRESENT copies it into the front buffer, which is the only
- * thing the WM ever composites - so a half-drawn frame can never reach the
- * screen (the copy runs with interrupts off).  Sessions are keyed by the
- * owner's pid and by the terminal screen (the screen pointer is what a
- * spawned command inherits, so it identifies the window without any new
- * plumbing in process.c). */
-
-#include "sys_gfx.h"
-#include "mm.h"
-#include "paging.h"
-#include "process.h"
-#include "wm.h"
-
-#define GFX_MAX_SESSIONS MAX_WINDOWS
-#define GFX_USER_BASE    USER_GFX_BASE   /* canvas mapping for the owner */
-#define GFX_KEY_RING     16
-
-struct gfx_session {
-	int used;
-	int dead;             /* owner gone: free on the next WM collect */
-	unsigned int pid;
-	unsigned int cr3;     /* owner's page directory (to unmap on END) */
-	struct term *term;
-	struct gfx_canvas c;  /* front buffer: what the WM composites */
-	unsigned short *back; /* back buffer: mapped to the owner */
-	unsigned int back_pages;
-	int keys[GFX_KEY_RING];
-	unsigned int key_head, key_tail;
-};
-
-static struct gfx_session sessions[GFX_MAX_SESSIONS];
-
-static inline void invlpg_va(unsigned int va)
-{
-	__asm__ volatile ("invlpg (%0)" : : "r"(va) : "memory");
-}
-
-static struct gfx_session *by_pid(unsigned int pid)
-{
-	unsigned int i;
-
-	for (i = 0; i < GFX_MAX_SESSIONS; i++)
-		if (sessions[i].used && !sessions[i].dead && sessions[i].pid == pid)
-			return &sessions[i];
-	return 0;
-}
-
-static struct gfx_session *by_screen(struct text_screen *s)
-{
-	unsigned int i;
-
-	for (i = 0; i < GFX_MAX_SESSIONS; i++)
-		if (sessions[i].used && !sessions[i].dead &&
-		    &sessions[i].term->screen == s)
-			return &sessions[i];
-	return 0;
-}
-
-static void free_back(struct gfx_session *s)
-{
-	unsigned int i;
-
-	if (!s->back)
-		return;
-	for (i = 0; i < s->back_pages; i++)
-		mm_free_page((unsigned int)s->back + i * PAGE_SIZE);
-	s->back = 0;
-	s->back_pages = 0;
-}
-
-static void unmap_all(struct gfx_session *s)
-{
-	unsigned int i;
-
-	if (!s->cr3 || !s->back)
-		return;
-	for (i = 0; i < s->back_pages; i++)
-		paging_unmap_page(s->cr3, GFX_USER_BASE + i * PAGE_SIZE);
-	s->cr3 = 0;
-}
-
-int sys_gfx_begin(struct sys_gfx_info *info)
-{
-	struct gfx_session *s = 0;
-	struct term *t;
-	unsigned int w, h, i, pages;
-
-	if (!info)
-		return -1;
-	if (by_pid(current_proc()->pid))
-		return -1;                       /* one session per process */
-	t = wm_term_for_screen(current_proc()->screen);
-	if (!t)
-		return -1;                       /* no window (not spawned by a terminal) */
-	if (by_screen(&t->screen))
-		return -1;                       /* one gfx command per window */
-
-	for (i = 0; i < GFX_MAX_SESSIONS; i++)
-		if (!sessions[i].used) {
-			s = &sessions[i];
-			break;
-		}
-	if (!s)
-		return -1;
-	if (wm_content_size(t, &w, &h) != 0)
-		return -1;
-	if (gfx_alloc(&s->c, w, h) != 0)
-		return -1;
-
-	pages = (w * h * 2 + PAGE_SIZE - 1) / PAGE_SIZE;
-	s->back = (unsigned short *)mm_alloc_pages(pages);
-	if (!s->back) {
-		gfx_free(&s->c);
-		return -1;
-	}
-	s->back_pages = pages;
-	for (i = 0; i < w * h; i++)     /* fresh memory is not zeroed */
-		s->back[i] = 0;
-
-	for (i = 0; i < pages; i++) {
-		if (!paging_map_page(current_proc()->cr3,
-				     GFX_USER_BASE + i * PAGE_SIZE,
-				     (unsigned int)s->back + i * PAGE_SIZE,
-				     PTE_USER | PTE_WRITABLE | PTE_PRESENT)) {
-			while (i--)
-				paging_unmap_page(current_proc()->cr3,
-						  GFX_USER_BASE + i * PAGE_SIZE);
-			free_back(s);
-			gfx_free(&s->c);
-			return -1;
-		}
-		invlpg_va(GFX_USER_BASE + i * PAGE_SIZE);
-	}
-
-	s->used = 1;
-	s->dead = 0;
-	s->pid = current_proc()->pid;
-	s->cr3 = current_proc()->cr3;
-	s->term = t;
-	s->key_head = s->key_tail = 0;
-
-	wm_content_changed(&t->screen);   /* the WM switches to the canvas */
-
-	info->width = w;
-	info->height = h;
-	info->fb = (void *)GFX_USER_BASE;
-	return 0;
-}
-
-int sys_gfx_present(void)
-{
-	struct gfx_session *s = by_pid(current_proc()->pid);
-	const unsigned short *src;   /* the caller's own view of its canvas */
-	unsigned int n, i;
-
-	if (!s)
-		return -1;
-	n = s->c.w * s->c.h;
-
-	/* The syscall runs on the caller's page directory, so read the canvas
-	 * through the caller's mapping: that is exactly the memory the command
-	 * drew into and presented. */
-	src = (const unsigned short *)GFX_USER_BASE;
-
-	/* Publish: copy the finished frame into the composited front buffer.
-	 * The syscall runs with interrupts off, so the WM can never observe (or
-	 * blit) a half-copied frame. */
-	for (i = 0; i + 1 < n; i += 2)
-		((unsigned int *)s->c.px)[i / 2] = ((const unsigned int *)src)[i / 2];
-	if (n & 1)
-		s->c.px[n - 1] = src[n - 1];
-	s->c.seq++;
-	return 0;
-}
-
-int sys_gfx_end(void)
-{
-	struct gfx_session *s = by_pid(current_proc()->pid);
-
-	if (!s)
-		return -1;
-	unmap_all(s);
-	/* The front canvas is still mapped into the WM.  Mark the session dead
-	 * and let sys_gfx_collect() unmap it from the WM before freeing it. */
-	s->dead = 1;
-	wm_content_changed(&s->term->screen);
-	return 0;
-}
-
-int sys_gfx_key_poll(void)
-{
-	struct gfx_session *s = by_pid(current_proc()->pid);
-	int k;
-
-	if (!s)
-		return wm_server_key_poll();   /* generic canvas window */
-	if (s->key_tail == s->key_head)
-		return 0;
-	k = s->keys[s->key_tail];
-	s->key_tail = (s->key_tail + 1) % GFX_KEY_RING;
-	return k;
-}
-
-/* WM: the canvas to composite for a window's screen, or NULL. */
-struct gfx_canvas *sys_gfx_canvas_for(struct text_screen *screen)
-{
-	struct gfx_session *s = by_screen(screen);
-
-	return s ? &s->c : 0;
-}
-
-/* WM: hand a key to the focused window's gfx command.  1 = consumed. */
-int sys_gfx_push_key(struct text_screen *screen, int k)
-{
-	struct gfx_session *s = by_screen(screen);
-	unsigned int next;
-
-	if (!s)
-		return 0;
-	next = (s->key_head + 1) % GFX_KEY_RING;
-	if (next != s->key_tail) {
-		s->keys[s->key_head] = k;
-		s->key_head = next;
-	}
-	return 1;      /* consumed even when the ring is full (drop, don't leak) */
-}
-
-/* WM: the window is closing; stop its gfx command and free its canvas. */
-void sys_gfx_kill_for_screen(struct text_screen *screen)
-{
-	struct gfx_session *s = by_screen(screen);
-
-	if (!s)
-		return;
-	process_kill(s->pid);
-	s->dead = 1;   /* freed by the next sys_gfx_collect() */
-	wm_content_changed(screen);
-}
-
-/* Reaper hook (schedule(), IRQ context): only flag the session. */
-void sys_gfx_reap(unsigned int pid)
-{
-	unsigned int i;
-
-	for (i = 0; i < GFX_MAX_SESSIONS; i++)
-		if (sessions[i].used && !sessions[i].dead && sessions[i].pid == pid)
-			sessions[i].dead = 1;
-}
-
-/* WM loop: free dead sessions away from the renderer (the reaper can run
- * while the WM is mid-blit, so freeing there would be unsafe). */
-void sys_gfx_collect(void)
-{
-	unsigned int i;
-	int freed = 0;
-
-	/* The WM may still be composing the front canvas we are about to free.
-	 * It calls back after PRESENT; the idle loop also retries. */
-	if (wm_server_frame_active())
-		return;
-
-	for (i = 0; i < GFX_MAX_SESSIONS; i++) {
-		if (sessions[i].used && sessions[i].dead) {
-			struct text_screen *screen = &sessions[i].term->screen;
-
-			/* Drop the WM's read-only mapping before the canvas pages
-			 * can be reused.  Only this session's canvas: a newer
-			 * session may already be mapped for the same screen. */
-			wm_server_unmap_canvas(screen, sessions[i].c.px);
-			gfx_free(&sessions[i].c);
-			free_back(&sessions[i]);
-			sessions[i].used = 0;
-			wm_content_changed(screen);
-			freed = 1;
-		}
-	}
-	if (freed)
-		wm_request_redraw();
-}

+ 0 - 22
sys_gfx.h

@@ -1,22 +0,0 @@
-/* Window graphics service for ring-3 commands (see sys_gfx.c). */
-#ifndef SYS_GFX_H
-#define SYS_GFX_H
-
-#include "gfx.h"
-#include "syscall.h"
-
-struct text_screen;
-
-int  sys_gfx_begin(struct sys_gfx_info *info);
-int  sys_gfx_present(void);
-int  sys_gfx_end(void);
-int  sys_gfx_key_poll(void);
-
-/* WM-facing helpers. */
-struct gfx_canvas *sys_gfx_canvas_for(struct text_screen *screen);
-int  sys_gfx_push_key(struct text_screen *screen, int k);   /* 1 = consumed */
-void sys_gfx_kill_for_screen(struct text_screen *screen);   /* window close */
-void sys_gfx_reap(unsigned int pid);                        /* IRQ context */
-void sys_gfx_collect(void);                                 /* WM loop */
-
-#endif

+ 5 - 0
sys_wm.c

@@ -137,6 +137,11 @@ int sys_wm_present(const struct wm_present_info *in)
 	return wm_server_present(&p);
 }
 
+int sys_wm_key_poll(void)
+{
+	return wm_server_key_poll();
+}
+
 int sys_wm_sync(void)
 {
 	return wm_server_sync();

+ 1 - 0
sys_wm.h

@@ -15,6 +15,7 @@ int sys_wm_close(unsigned int index);
 int sys_wm_poll(struct wm_status *out);
 int sys_wm_begin(void);
 int sys_wm_present(const struct wm_present_info *in);
+int sys_wm_key_poll(void);
 int sys_wm_sync(void);
 
 int sys_win_create(const struct win_create *in, struct win_info *out);

+ 1 - 13
syscall.c

@@ -7,7 +7,6 @@
 #include "rtc.h"
 #include "serial.h"
 #include "sys_fs.h"
-#include "sys_gfx.h"
 #include "sys_info.h"
 #include "sys_mem.h"
 #include "sys_net.h"
@@ -180,19 +179,8 @@ static int syscall_dispatch_locked(int num, int a1, int a2, int a3)
 	case SYS_PROCINFO:
 		return process_procinfo((unsigned int)a1,
 					(struct sys_procinfo *)a2);
-	case SYS_GET_CURSOR:
-		return (int)io_get_cursor();
-	case SYS_SET_CURSOR:
-		io_set_cursor((unsigned int)a1);
-		return 0;
-	case SYS_GFX_BEGIN:
-		return sys_gfx_begin((struct sys_gfx_info *)a1);
-	case SYS_GFX_PRESENT:
-		return sys_gfx_present();
-	case SYS_GFX_END:
-		return sys_gfx_end();
 	case SYS_KEY_POLL:
-		return sys_gfx_key_poll();
+		return sys_wm_key_poll();
 	case SYS_RTC_HMS: {
 		struct sys_time *out = (struct sys_time *)a1;
 		unsigned int h, m, s;

+ 1 - 18
syscall.h

@@ -72,17 +72,7 @@
 /* Process snapshot for the `top` command (see process.c). */
 #define SYS_PROCINFO     49  /* (unsigned int index, struct sys_procinfo *out)
 				-> 1 when found, 0 at the end of the table */
-#define SYS_GET_CURSOR   50  /* () -> cursor position of the caller's screen */
-#define SYS_SET_CURSOR   51  /* (unsigned int pos) -> 0 */
-
-/* Window graphics service (see sys_gfx.c): a ring-3 command maps its terminal
- * window's RGB565 back buffer and draws directly into it; SYS_GFX_PRESENT
- * copies it into the composited front buffer (double buffering, so the WM
- * never shows a half-drawn frame).  One session per process and per window. */
-#define SYS_GFX_BEGIN    52  /* (struct sys_gfx_info *out) -> 0/-1 */
-#define SYS_GFX_PRESENT  53  /* () -> 0/-1; publish a finished frame */
-#define SYS_GFX_END      54  /* () -> 0/-1; unmap + free the canvas */
-#define SYS_KEY_POLL     55  /* () -> 0 none, ASCII, or IO_KEY_*; gfx session only */
+#define SYS_KEY_POLL     55  /* () -> 0 none, ASCII, or IO_KEY_* for the caller's window */
 #define SYS_RTC_HMS      56  /* (struct sys_time *out) -> 0/-1 */
 
 /* Window-manager service (see wm_abi.h).  Only the kernel-spawned WM process
@@ -280,13 +270,6 @@ struct sys_tpec_sensors {
 	unsigned int fan_level;
 };
 
-/* Window canvas handed to a ring-3 graphics command (see sys_gfx.c). */
-struct sys_gfx_info {
-	unsigned int width;    /* canvas (= window content) size in pixels */
-	unsigned int height;
-	void *fb;              /* user VA of the mapped RGB565 canvas */
-};
-
 /* Wall clock for the ring-3 clock (see rtc.c). */
 struct sys_time {
 	unsigned int hour;     /* 0-23 */

Tiedoston diff-näkymää rajattu, sillä se on liian suuri
+ 6 - 1001
terminal.c


+ 0 - 49
terminal.h

@@ -2,66 +2,17 @@
 #ifndef TERMINAL_H
 #define TERMINAL_H
 
-#include "sched.h"
 #include "screen.h"
 #include "vfs.h"
 
-#define CURSOR_MS    500
-#define LINE_MAX     64
-#define HISTORY_SIZE 32
-#define KEY_BUF_SIZE 16
-
 struct term {
 	struct text_screen screen;
-	char history[HISTORY_SIZE][LINE_MAX];
-	unsigned int history_count;
-	unsigned int history_next;
-	char line[LINE_MAX];
-	unsigned int line_len;
-	unsigned int line_pos;
-	unsigned int line_start;
-	unsigned int history_browse;
-	int fg_pid;                 /* foreground child pid, or -1 when none */
 	char cwd[VFS_PATH_MAX];     /* absolute current working directory */
 	char path[VFS_PATH_MAX];    /* command search path (colon separated) */
-	/* Per-terminal key queue: the kworker pushes, the terminal pops. */
-	int keys[KEY_BUF_SIZE];
-	unsigned int key_head;
-	unsigned int key_tail;
-	struct wait_queue key_wq;
 };
 
-/* Entry point for a terminal process (arg = struct term *). */
-void term_entry(void *arg);
-void term_run(struct term *t);
-
 /* Ring-3 terminal: run a privileged kernel command as a kernel process with
  * output on `tty` (the command table and handlers stay in terminal.c). */
 int term_kcmd_spawn(const char *name, const char *args, unsigned int tty);
 
-/* Single-producer (WM) / single-consumer (terminal) key queue. */
-static inline void term_key_push(struct term *t, int k)
-{
-	unsigned int next = (t->key_head + 1) % KEY_BUF_SIZE;
-	if (next != t->key_tail) {
-		t->keys[t->key_head] = k;
-		t->key_head = next;
-	}
-}
-
-static inline int term_key_pop(struct term *t)
-{
-	int k;
-	if (t->key_tail == t->key_head)
-		return 0;
-	k = t->keys[t->key_tail];
-	t->key_tail = (t->key_tail + 1) % KEY_BUF_SIZE;
-	return k;
-}
-
-static inline void term_key_wake(struct term *t)
-{
-	wait_wake_one(&t->key_wq);
-}
-
 #endif

+ 2 - 2
testdata/browser/demo.html

@@ -1,6 +1,6 @@
 <html>
 <head>
-<title>Nebs demo</title>
+<title>NebOS demo</title>
 <style>
 body { margin: 10px; color: #e4e6f0; }
 h1 { color: #ff8a66; }
@@ -14,7 +14,7 @@ td { padding-right: 18px; }
 <body>
 <h1>Local browser demo</h1>
 <p>This page came from <b>/floppy1/DEMO.HTM</b> and was rendered by the
-Nebs browser: HTML, a little CSS and an inline image, with no JavaScript.</p>
+NebOS browser: HTML, a little CSS and an inline image, with no JavaScript.</p>
 
 <div class="note">
 <b>Inline styles and classes:</b>

+ 0 - 118
text_canvas.c

@@ -1,118 +0,0 @@
-/* 8x16 text-cell renderer for window content canvases (see text_canvas.h).
- *
- * The cell grid is the terminal's internal state (char + VGA attribute); this
- * file is the only place that knows the terminal cell geometry.  The window
- * server calls it with the damaged cell block and composites the resulting
- * RGB565 canvas.  No kernel dependencies, so the host test exercises the same
- * code. */
-
-#include "text_canvas.h"
-#include "font_8x16.h"
-
-#define TEXT_CURSOR_W 2
-
-/* Standard VGA palette expanded to RGB565; the same values as fbtext.c's
- * attr_to_rgb() and the userland WM palette. */
-static const unsigned short text_pal565[16] = {
-	0x0000, /*  0 black */
-	0x0015, /*  1 blue */
-	0x0540, /*  2 green */
-	0x0555, /*  3 cyan */
-	0xA800, /*  4 red */
-	0xA815, /*  5 magenta */
-	0xAAA0, /*  6 brown */
-	0xAD55, /*  7 light gray */
-	0x52AA, /*  8 dark gray */
-	0x52BF, /*  9 light blue */
-	0x57EA, /* 10 light green */
-	0x57FF, /* 11 light cyan */
-	0xFAAA, /* 12 light red */
-	0xFABF, /* 13 light magenta */
-	0xFFEA, /* 14 yellow */
-	0xFFFF, /* 15 white */
-};
-
-static void put_cell(struct text_canvas *c, unsigned int col, unsigned int row,
-		     unsigned char ch, unsigned char attr, int cursor)
-{
-	unsigned int x0 = col * TEXT_CELL_W;
-	unsigned int y0 = row * TEXT_CELL_H;
-	unsigned short fg = text_pal565[attr & 0x0F];
-	unsigned short bg = text_pal565[(attr >> 4) & 0x0F];
-	const unsigned char *glyph;
-	unsigned int gy, gx;
-
-	if (!c || !c->px || x0 >= c->w || y0 >= c->h)
-		return;
-
-	glyph = &font_8x16[(unsigned int)ch * FONT_8X16_ROWS];
-	for (gy = 0; gy < TEXT_CELL_H; gy++) {
-		unsigned int y = y0 + gy;
-		unsigned short *dst;
-		unsigned char bits;
-
-		if (y >= c->h)
-			break;
-		dst = c->px + (unsigned long)y * c->w;
-		bits = (gy < FONT_8X16_ROWS) ? glyph[gy] : 0;
-		for (gx = 0; gx < TEXT_CELL_W; gx++) {
-			unsigned int x = x0 + gx;
-
-			if (x >= c->w)
-				break;
-			dst[x] = (bits & (0x80u >> gx)) ? fg : bg;
-		}
-	}
-
-	if (!cursor)
-		return;
-
-	/* Block cursor: a full-cell-height bar in the first two columns. */
-	for (gy = 0; gy < TEXT_CELL_H; gy++) {
-		unsigned int y = y0 + gy;
-		unsigned short *dst;
-		unsigned int x;
-
-		if (y >= c->h)
-			break;
-		dst = c->px + (unsigned long)y * c->w;
-		for (x = 0; x < TEXT_CURSOR_W; x++) {
-			if (x0 + x >= c->w)
-				break;
-			dst[x0 + x] = text_pal565[15];
-		}
-	}
-}
-
-void text_canvas_render(struct text_canvas *c,
-			const unsigned short *cells,
-			unsigned int cols, unsigned int rows,
-			unsigned int col0, unsigned int row0,
-			unsigned int ncols, unsigned int nrows,
-			unsigned int cursor, int cursor_visible, int focused)
-{
-	unsigned int col, row;
-
-	if (!c || !c->px || !cells || !cols || !rows)
-		return;
-	if (col0 >= cols || row0 >= rows)
-		return;
-	if (ncols > cols - col0)
-		ncols = cols - col0;
-	if (nrows > rows - row0)
-		nrows = rows - row0;
-	if (!ncols || !nrows)
-		return;
-
-	for (row = row0; row < row0 + nrows; row++) {
-		for (col = col0; col < col0 + ncols; col++) {
-			unsigned int idx = row * cols + col;
-			unsigned short cell = cells[idx];
-			unsigned char ch = (unsigned char)(cell & 0xFF);
-			unsigned char attr = (unsigned char)(cell >> 8);
-			int cur = (idx == cursor && cursor_visible && focused);
-
-			put_cell(c, col, row, ch, attr, cur);
-		}
-	}
-}

+ 0 - 28
text_canvas.h

@@ -1,28 +0,0 @@
-/* 8x16 text-cell renderer for window content canvases.
- *
- * The terminal keeps its 64x32 char+attribute grid; the window server renders
- * damaged cells into an RGB565 canvas and the WM composites that canvas like
- * any other window content.  Freestanding and host-testable. */
-#ifndef TEXT_CANVAS_H
-#define TEXT_CANVAS_H
-
-#define TEXT_CELL_W 8
-#define TEXT_CELL_H 16
-
-struct text_canvas {
-	unsigned short *px;   /* RGB565, w*h, tightly packed */
-	unsigned int w, h;
-};
-
-/* Render the cell block [col0, col0+ncols) x [row0, row0+nrows) of a
- * cols x rows cell grid at the canvas top-left.  Every pixel of the block is
- * written (background included).  `cursor` is a linear cell index; the cursor
- * bar is drawn when visible and focused.  Out-of-range cells are clipped. */
-void text_canvas_render(struct text_canvas *c,
-			const unsigned short *cells,
-			unsigned int cols, unsigned int rows,
-			unsigned int col0, unsigned int row0,
-			unsigned int ncols, unsigned int nrows,
-			unsigned int cursor, int cursor_visible, int focused);
-
-#endif

+ 0 - 233
text_canvas_test.c

@@ -1,233 +0,0 @@
-/* Host test for the 8x16 terminal-cell renderer (make test-textcanvas).
- * Exercises the renderer directly; no kernel headers are involved. */
-
-#include <stdio.h>
-#include "text_canvas.h"
-#include "font_8x16.h"
-
-#define COLS 64u
-#define ROWS 32u
-#define W (COLS * TEXT_CELL_W)
-#define H (ROWS * TEXT_CELL_H)
-
-/* Hash of the fully rendered reference grid.  Regenerate only when the font,
- * palette or cell metrics intentionally change. */
-#define GOLDEN 0x8598C6C9u
-
-static unsigned short cells[COLS * ROWS];
-static unsigned short fb[W * H];
-static int failures;
-
-/* Same standard VGA palette as text_canvas.c, in RGB565. */
-static const unsigned short pal565[16] = {
-	0x0000, 0x0015, 0x0540, 0x0555,
-	0xA800, 0xA815, 0xAAA0, 0xAD55,
-	0x52AA, 0x52BF, 0x57EA, 0x57FF,
-	0xFAAA, 0xFABF, 0xFFEA, 0xFFFF,
-};
-
-static void expect(unsigned int x, unsigned int y, unsigned short want,
-		   const char *what)
-{
-	unsigned short got;
-
-	if (x >= W || y >= H) {
-		printf("FAIL %s: (%u,%u) out of range\n", what, x, y);
-		failures++;
-		return;
-	}
-	got = fb[y * W + x];
-	if (got != want) {
-		printf("FAIL %s at (%u,%u): got 0x%04X want 0x%04X\n",
-		       what, x, y, got, want);
-		failures++;
-	}
-}
-
-static int glyph_bit(char ch, unsigned int row, unsigned int col)
-{
-	return (font_8x16[(unsigned int)(unsigned char)ch * FONT_8X16_ROWS +
-			  row] >> (7 - col)) & 1;
-}
-
-static void fill_cells(unsigned short value)
-{
-	unsigned int i;
-
-	for (i = 0; i < COLS * ROWS; i++)
-		cells[i] = value;
-}
-
-static void put_text(unsigned int col, unsigned int row, const char *s,
-		     unsigned char attr)
-{
-	unsigned int i;
-
-	for (i = 0; s[i] && col + i < COLS; i++)
-		cells[row * COLS + col + i] =
-			(unsigned short)(((unsigned short)attr << 8) |
-					(unsigned char)s[i]);
-}
-
-static unsigned int hash565(const unsigned short *px, unsigned int n)
-{
-	unsigned int h = 2166136261u;
-	unsigned int i;
-
-	for (i = 0; i < n; i++) {
-		h = (h ^ (px[i] & 0xFF)) * 16777619u;
-		h = (h ^ (px[i] >> 8)) * 16777619u;
-	}
-	return h;
-}
-
-int main(void)
-{
-	struct text_canvas c = { fb, W, H };
-	unsigned int cursor = 3 * COLS + 5;
-	unsigned int i, hash;
-
-	fill_cells(0x0720);              /* space, light gray on black */
-	put_text(0, 0, "Nebs OS 8x16", 0x0F);
-	put_text(0, 1, "0123456789", 0x1E);
-	put_text(2, 2, "ABCDEFGH", 0x4A);
-	cells[1 * COLS + 12] = 0x1E20;   /* blue background space */
-	cells[3 * COLS + 4] = 0x4A20;    /* red background space sentinel */
-	cells[3 * COLS + 5] = 0x0020;    /* black space under the cursor */
-
-	/* The full render must cover every pixel. */
-	for (i = 0; i < W * H; i++)
-		fb[i] = 0xDEAD;
-	text_canvas_render(&c, cells, COLS, ROWS, 0, 0, COLS, ROWS,
-			   cursor, 1, 1);
-	for (i = 0; i < W * H; i++) {
-		if (fb[i] == 0xDEAD) {
-			printf("FAIL full render left sentinel at pixel %u\n", i);
-			failures++;
-			break;
-		}
-	}
-
-	hash = hash565(fb, W * H);
-	if (hash != GOLDEN) {
-		printf("FAIL full render hash 0x%08X, expected 0x%08X\n",
-		       hash, GOLDEN);
-		failures++;
-	}
-
-	/* 8x16 glyph mapping: 'A' at (2,2), attr 0x4A = light green on red. */
-	{
-		unsigned int row, bit;
-		int set_seen = 0, clear_seen = 0;
-
-		for (row = 0; row < FONT_8X16_ROWS; row++) {
-			for (bit = 0; bit < 8; bit++) {
-				unsigned int x = 2 * TEXT_CELL_W + bit;
-				unsigned int y = 2 * TEXT_CELL_H + row;
-				int on = glyph_bit('A', row, bit);
-
-				if (on && !set_seen) {
-					expect(x, y, pal565[10], "glyph set");
-					set_seen = 1;
-				}
-				if (!on && !clear_seen) {
-					expect(x, y, pal565[4], "glyph clear");
-					clear_seen = 1;
-				}
-			}
-		}
-		if (!set_seen || !clear_seen) {
-			printf("FAIL glyph test could not find set/clear bits\n");
-			failures++;
-		}
-	}
-
-	/* Cell boundary: row 0 background at y=15, row 1 at y=16. */
-	expect(12 * TEXT_CELL_W, 15, pal565[0], "row 0 bottom");
-	expect(12 * TEXT_CELL_W, 16, pal565[1], "row 1 top");
-
-	/* Cursor: black space at (5,3), white 2x16 bar. */
-	expect(5 * TEXT_CELL_W + 0, 3 * TEXT_CELL_H + 0, pal565[15],
-	       "cursor x0");
-	expect(5 * TEXT_CELL_W + 1, 3 * TEXT_CELL_H + 0, pal565[15],
-	       "cursor x1");
-	expect(5 * TEXT_CELL_W + 2, 3 * TEXT_CELL_H + 0, pal565[0],
-	       "cursor x2");
-	expect(5 * TEXT_CELL_W + 0, 3 * TEXT_CELL_H + 15, pal565[15],
-	       "cursor bottom");
-	expect(5 * TEXT_CELL_W + 0, 4 * TEXT_CELL_H, pal565[0],
-	       "cursor next row");
-
-	/* Unfocused windows must not show the cursor. */
-	text_canvas_render(&c, cells, COLS, ROWS, 0, 0, COLS, ROWS,
-			   cursor, 1, 0);
-	expect(5 * TEXT_CELL_W + 0, 3 * TEXT_CELL_H + 0, pal565[0],
-	       "cursor unfocused");
-
-	/* Block update: only cell (5,3) changes. */
-	expect(4 * TEXT_CELL_W, 3 * TEXT_CELL_H, pal565[4],
-	       "sentinel before block");
-	cells[3 * COLS + 5] = (0x0F << 8) | 'X';
-	text_canvas_render(&c, cells, COLS, ROWS, 5, 3, 1, 1,
-			   0xFFFFFFFFu, 0, 0);
-	expect(4 * TEXT_CELL_W, 3 * TEXT_CELL_H, pal565[4],
-	       "sentinel after block");
-	expect(5 * TEXT_CELL_W, 4 * TEXT_CELL_H, pal565[0],
-	       "row 4 after block");
-	{
-		unsigned int row, bit;
-		int set_seen = 0, clear_seen = 0;
-
-		for (row = 0; row < FONT_8X16_ROWS; row++) {
-			for (bit = 0; bit < 8; bit++) {
-				unsigned int x = 5 * TEXT_CELL_W + bit;
-				unsigned int y = 3 * TEXT_CELL_H + row;
-				int on = glyph_bit('X', row, bit);
-
-				if (on && !set_seen) {
-					expect(x, y, pal565[15], "X set");
-					set_seen = 1;
-				}
-				if (!on && !clear_seen) {
-					expect(x, y, pal565[0], "X clear");
-					clear_seen = 1;
-				}
-			}
-		}
-		if (!set_seen || !clear_seen) {
-			printf("FAIL X glyph test could not find bits\n");
-			failures++;
-		}
-	}
-
-	/* A block at the last cell must clamp without touching the canvas
-	 * bounds, and still render the cell. */
-	cells[(ROWS - 1) * COLS + (COLS - 1)] = (0x0F << 8) | 'X';
-	text_canvas_render(&c, cells, COLS, ROWS, COLS - 1, ROWS - 1, 4, 4,
-			   0xFFFFFFFFu, 0, 0);
-	{
-		unsigned int row, bit;
-		int set_seen = 0;
-
-		for (row = 0; row < FONT_8X16_ROWS && !set_seen; row++)
-			for (bit = 0; bit < 8; bit++)
-				if (glyph_bit('X', row, bit)) {
-					expect((COLS - 1) * TEXT_CELL_W + bit,
-					       (ROWS - 1) * TEXT_CELL_H + row,
-					       pal565[15], "edge block");
-					set_seen = 1;
-					break;
-				}
-		if (!set_seen) {
-			printf("FAIL edge block glyph bits not found\n");
-			failures++;
-		}
-	}
-
-	if (failures) {
-		printf("%d text canvas test(s) failed\n", failures);
-		return 1;
-	}
-	printf("all text canvas tests passed\n");
-	return 0;
-}

+ 0 - 25
ucmd_lib.h

@@ -160,16 +160,6 @@ static inline unsigned int u_ticks_ms(void)
 
 /* Cursor position of this process's terminal screen (linear cell index);
  * used by `top` to repaint its frame in place. */
-static inline unsigned int u_get_cursor(void)
-{
-	return (unsigned int)u_syscall0(SYS_GET_CURSOR);
-}
-
-static inline void u_set_cursor(unsigned int pos)
-{
-	u_syscall1(SYS_SET_CURSOR, (int)pos);
-}
-
 static inline void u_sleep_ms(unsigned int ms)
 {
 	u_syscall1(SYS_SLEEP_MS, (int)ms);
@@ -362,21 +352,6 @@ static inline int u_chdir(const char *path)
 	return u_syscall1(SYS_CHDIR, (int)path);
 }
 
-static inline int u_gfx_begin(struct sys_gfx_info *info)
-{
-	return u_syscall1(SYS_GFX_BEGIN, (int)info);
-}
-
-static inline int u_gfx_present(void)
-{
-	return u_syscall0(SYS_GFX_PRESENT);
-}
-
-static inline int u_gfx_end(void)
-{
-	return u_syscall0(SYS_GFX_END);
-}
-
 static inline int u_key_poll(void)
 {
 	return u_syscall0(SYS_KEY_POLL);

+ 1 - 1
ucmd_solitaire.c

@@ -216,7 +216,7 @@ static const char *const howto_lines[] = {
 };
 
 static const char *const about_lines[] = {
-	"Nebs OS edition",
+	"NebOS edition",
 	"",
 	"A Windows 95 style Klondike.",
 	"Drag, drop, and bounce."

+ 3 - 3
ucmd_websrv.c

@@ -222,7 +222,7 @@ static int send_headers(int code, const char *reason, const char *ctype,
 	rad((unsigned int)code);
 	ra(" ");
 	ra(reason);
-	ra("\r\nServer: Nebs OS/0.2.0\r\n");
+	ra("\r\nServer: NebOS/0.2.0\r\n");
 	ra((rq.keep_alive && code < 400) ? "Connection: keep-alive\r\n"
 					 : "Connection: close\r\n");
 	ra("Cache-Control: no-store\r\n");
@@ -335,7 +335,7 @@ static int send_multistatus_begin(void)
 {
 	resp_len = 0;
 	ra("HTTP/1.1 207 Multi-Status\r\n");
-	ra("Server: Nebs OS/0.2.0\r\n");
+	ra("Server: NebOS/0.2.0\r\n");
 	ra("Content-Type: text/xml; charset=\"utf-8\"\r\n");
 	ra("Transfer-Encoding: chunked\r\n");
 	ra(rq.keep_alive ? "Connection: keep-alive\r\n"
@@ -1167,7 +1167,7 @@ static int list_child(unsigned int index, const char *dir, char *out,
 static void do_options2(void)
 {
 	resp_len = 0;
-	ra("HTTP/1.1 200 OK\r\nServer: Nebs OS/0.2.0\r\n");
+	ra("HTTP/1.1 200 OK\r\nServer: NebOS/0.2.0\r\n");
 	ra("DAV: 1, 2\r\nMS-Author-Via: DAV\r\n");
 	ra("Allow: OPTIONS, GET, HEAD, PUT, DELETE, MKCOL, PROPFIND, "
 	   "PROPPATCH, MOVE, LOCK, UNLOCK\r\n");

+ 16 - 0
ucmd_wm.c

@@ -31,6 +31,7 @@ static int resize_id = -1;
 static unsigned int resize_mx, resize_my, resize_ow, resize_oh;
 static unsigned int prev_buttons;
 static int full_redraw = 1;
+static int boot_term_spawned;
 static unsigned int bar_kexec_busy, bar_kexec_progress, bar_kexec_total;
 static int bar_temp_c = -1;
 static char bar_msg[24];
@@ -366,6 +367,21 @@ static void do_update(struct wm_status *st)
 		(st->kexec_busy && st->kexec_progress != bar_kexec_progress);
 	unsigned int msg_now = u_ticks_ms();
 
+	/* Spawn the first terminal once the kernel says the storage scan is
+	 * done, so a shell command can never race the mount table. */
+	if (st->boot_ready && !boot_term_spawned) {
+		boot_term_spawned = 1;
+		if (!free_window_slot()) {
+			bar_notice("window limit");
+			full_redraw = 1;
+		} else if (u_wm_create_term() < 0) {
+			bar_notice("cannot start term");
+			full_redraw = 1;
+		} else {
+			full_redraw = 1;
+		}
+	}
+
 	if (bar_msg_dirty ||
 	    (bar_msg_until && (int)(msg_now - bar_msg_until) >= 0)) {
 		bar_dirty = 1;

+ 1 - 1
version.h

@@ -3,7 +3,7 @@
 #ifndef VERSION_H
 #define VERSION_H
 
-#define OS_NAME    "Nebs OS"
+#define OS_NAME    "NebOS"
 #define OS_VERSION "0.2.0"
 
 #endif

Tiedoston diff-näkymää rajattu, sillä se on liian suuri
+ 95 - 799
wm.c


+ 5 - 22
wm.h

@@ -2,8 +2,8 @@
 #ifndef WM_H
 #define WM_H
 
-#include "terminal.h"
 #include "gfx.h"
+#include "sched.h"
 #include "wm_abi.h"
 
 #define MAX_WINDOWS WM_MAX_WINDOWS
@@ -14,9 +14,8 @@ struct window {
 	unsigned int pw, ph;     /* pixel size */
 	char title[16];
 	int focused;
-	unsigned int pid;        /* owning terminal process pid (0 = none) */
-	struct term *term;
-	/* Generic canvas window (gfx commands): no terminal, own front/back. */
+	unsigned int pid;        /* owning process pid (0 = none) */
+	/* Every window is a ring-3 canvas client. */
 	int canvas_window;
 	struct gfx_canvas canvas;
 	unsigned short *back;
@@ -37,18 +36,11 @@ struct window {
 	unsigned int mapped_gen;
 	unsigned int mapped_pages;
 	const void *mapped_src;
-	/* Fallback kernel terminal canvas: the window server renders the cell
-	 * grid into this RGB565 canvas and the WM composites it like any other
-	 * window content. */
-	int text_ready;
-	unsigned int text_dmg_x, text_dmg_y, text_dmg_w, text_dmg_h;
 };
 
-void wm_run(void);
 /* Idle-loop services: these stay in the kernel even while the WM process is
- * stopped, so keyboard routing, cursor blink and kexec recovery keep working. */
+ * stopped, so keyboard routing and kexec recovery keep working. */
 void wm_pump_keyboard(void);
-void wm_blink_cursor(void);
 void wm_handle_kexec(void);
 int  wm_spawn_terminal(void);
 
@@ -81,18 +73,9 @@ int  wm_server_key_poll(void);
 int  wm_server_key_wait(unsigned int timeout_ms);
 int  wm_server_win_pointer(struct win_pointer *out);
 int  wm_server_win_event(struct win_event *out);
-void wm_content_changed(struct text_screen *screen);
-void wm_server_unmap_screen(struct text_screen *screen);
-void wm_server_unmap_canvas(struct text_screen *screen, const void *canvas);
+void wm_server_boot_ready(void);
 struct window *wm_focused_window(void);
 int  wm_is_focused(const struct window *w);
 void wm_request_redraw(void);
 
-/* The terminal whose screen is `screen`, or NULL (the sys_gfx service uses the
- * inherited screen pointer to find a command's window). */
-struct term *wm_term_for_screen(struct text_screen *screen);
-
-/* Pixel size of a window's content area (its canvas size).  Returns 0/-1. */
-int wm_content_size(struct term *t, unsigned int *w, unsigned int *h);
-
 #endif

+ 1 - 0
wm_abi.h

@@ -74,6 +74,7 @@ struct wm_mouse_info {
 struct wm_status {
 	struct wm_mouse_info mouse;
 	unsigned int full_redraw;
+	unsigned int boot_ready;   /* storage is mounted; spawn the first terminal */
 	unsigned int kexec_busy;
 	unsigned int kexec_progress;
 	unsigned int kexec_total;

Kaikkia tiedostoja ei voida näyttää, sillä liian monta tiedostoa muuttui tässä diffissä