Bläddra i källkod

Remove various legacy code and introduce docs pages

Johannes Zellner 1 vecka sedan
förälder
incheckning
2538f5201d
45 ändrade filer med 4817 tillägg och 2871 borttagningar
  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
 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).
 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.
 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
 ## Build & run
 
 
 Toolchain: `gcc` (32-bit multilib), `as`/`ld`/`objcopy`, `mtools` (`mcopy`/`mkfs.fat`), `qemu`.
 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
 - **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,
   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
   (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
   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
   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
   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
   trampoline (`kexec_tramp.S`) clears CR0.PG before the copy so it can overwrite
   the old kernel's page tables safely.
   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`,
 - **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
   `nv50.c`, `pci.h` — VESA LFB + shadow buffer.  Drawing goes into a
   `struct surface` render target: `vga_target()` is the screen's shadow buffer
   `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
   mode itself), the cursor staging registers are engine-only, and a channel
   that has run cannot be restarted — see the header of `nv50.c`.
   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,
 - **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,
 - **Fatal exception screen**: `panic.c/h`, `timer.S` — on a ring-0 fault,
   dumps vector/error code, GPRs, CRs, EIP instruction bytes and stack
   dumps vector/error code, GPRs, CRs, EIP instruction bytes and stack
   return-address candidates straight into the LFB (and COM1) before halting;
   return-address candidates straight into the LFB (and COM1) before halting;
   see the panic section below.
   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),
 - **Filesystem**: `fat.c` (FAT12/16/32 read/write, device-parameterized),
   `vfs.c` (mounts every FAT device under `/`), `fatdetect.c`/`fatformat.c`,
   `vfs.c` (mounts every FAT device under `/`), `fatdetect.c`/`fatformat.c`,
   `blkdev.c` (floppy + IDE + SATA registry), `ata.c` (ATA PIO, either the
   `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
   shared ARP resolution (`net_arp_resolve`) and routing (`net_next_hop`), frame
   decode, `net_checksum()`/`net_checksum_tcp()`.  `dhcp.c` — minimal DHCP client
   decode, `net_checksum()`/`net_checksum_tcp()`.  `dhcp.c` — minimal DHCP client
   (DISCOVER →
   (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
   the static address when no server answers; `dhcp` re-runs it; learns the DNS
   server from option 6). `netcmd.c` — the
   server from option 6). `netcmd.c` — the
   `netinfo`/`netrecv`/`netsend`/`netip`/`dhcp`/`pong`/`ping`/`netregs`
   `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.
   net users, so being preempted mid-wait is safe.
 
 
   The server side is the WebDAV command: `tcp.c` has a small listener (one
   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
   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
   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
   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
 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
 hosts skip DNS).  `https` uses the phase-A TLS 1.3 client (no certificate
 verification; the leaf fingerprint is printed).  On
 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.
 current address) and falls back to the static default when no server answers.
 The board also answers ARP/ICMP for its IP while idle.
 The board also answers ARP/ICMP for its IP while idle.
 `lspci` lists every PCI function (one line each); with a filter (`lspci 8168`,
 `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 kernel-dev     # kernel only; the new kernel keeps the running rootfs
 make cmds-dev       # runtime raw-pack update, no reboot
 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:
 to COM1, so a serial monitor can confirm the new build headlessly:
 
 
 ```sh
 ```sh
@@ -1010,7 +1055,7 @@ directly at boot — no keystroke injection needed:
      -display none -vga std
      -display none -vga std
    # ...then: cat -A /tmp/opencode/serial.log
    # ...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.
    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;
 4. **Revert before committing** — remove the `io.c` echo and any boot-time call;
    `git status` should show `io.c` and `kernel.c` unchanged.
    `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
     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
     on the other CPUs for its duration.  `bkl_pause()`/`bkl_resume()` is used
     for serial/network waits, not yet for disk I/O.
     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)
 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
     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
     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
     also open extensionless files in the viewer.  Automatic decode-at-scale
     for oversized images is still missing.
     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
     files are buffered whole (4 MB cap; a larger PUT gets 413), directory
     `MOVE` is 501, `PROPPATCH` is answered 200 without persisting, and there
     `MOVE` is 501, `PROPPATCH` is answered 200 without persisting, and there
     is no authentication.  Sends use a four-segment window, and keep-alive is
     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,--image-base,0x0 -Wl,--dynamicbase \
               -Wl,--enable-reloc-section -Wl,--no-insert-timestamp
               -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
 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
 font_8x16.o: font_8x16.c font_8x16.h
 	$(CC) $(CFLAGS) -o $@ $<
 	$(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
 fbtext.o: fbtext.c fbtext.h font_8x8.h vga.h
 	$(CC) $(CFLAGS) -o $@ $<
 	$(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
 gfx.o: gfx.c gfx.h mm.h vga.h
 	$(CC) $(CFLAGS) -o $@ $<
 	$(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
 display.o: display.c io.h vga.h gpu.h ati.h nvidia.h radeon.h mouse.h fbtext.h
 	$(CC) $(CFLAGS) -o $@ $<
 	$(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
 syscall_stub.o: syscall_stub.S irqret.inc
 	$(AS) $(ASFLAGS) -o $@ $<
 	$(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,$^)
 	$(LD) $(KERNEL_LDFLAGS) -o $@ $(filter-out kernel.ld,$^)
 
 
 MBR_LDFLAGS = -T mbr.ld -nostdlib -m elf_i386
 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)
 	gcc -O1 -g -fwrapv -fsanitize=address,undefined -I. -o img_test_asan $(IMGTEST_SRCS)
 	./img_test_asan
 	./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
 mkpack: mkpack.c
 	gcc -O2 -o $@ $<
 	gcc -O2 -o $@ $<
 
 
@@ -967,7 +954,7 @@ run-serial:
 
 
 monitor:
 monitor:
 	@echo "Watching $(SERIAL_DEV) @ $(SERIAL_BAUD) baud (Ctrl-A Ctrl-X to exit)."
 	@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)
 	picocom $(SERIAL_DEV) --baud $(SERIAL_BAUD)
 
 
 send: $(PROGRAM).bin send_serial
 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
 	./netkexec_send $(BOARD_IP) $(NETKEXEC_PORT) 0x$$entry kernel.bin
 
 
 clean:
 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();
 	browser_rules_alloc();
 	{
 	{
 		static const char home[] =
 		static const char home[] =
-			"<html><head><title>Nebs Browser</title><style>"
+			"<html><head><title>NebOS Browser</title><style>"
 			"body { margin: 10px; color: #e4e6f0; }"
 			"body { margin: 10px; color: #e4e6f0; }"
 			"h1 { color: #7fb0ff; }"
 			"h1 { color: #7fb0ff; }"
 			".box { background-color: #262b3a; margin: 12px; "
 			".box { background-color: #262b3a; margin: 12px; "
@@ -1602,7 +1602,7 @@ static void load_home(int push)
 			"a { color: #7fb0ff; }"
 			"a { color: #7fb0ff; }"
 			"pre { background-color: #32384a; }"
 			"pre { background-color: #32384a; }"
 			"</style></head><body>"
 			"</style></head><body>"
-			"<h1>Nebs Browser</h1>"
+			"<h1>NebOS Browser</h1>"
 			"<p>A small HTML/CSS browser built on <b>ngui</b>, the "
 			"<p>A small HTML/CSS browser built on <b>ngui</b>, the "
 			"shared HTTP client and the image library.</p>"
 			"shared HTTP client and the image library.</p>"
 			"<div class=\"box\"><b>Try:</b>"
 			"<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
  * 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
  * 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 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:
  * 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("nebos-efi: ");
 	com1_puts(msg);
 	com1_puts(msg);
 	com1_puts("\n");
 	com1_puts("\n");
-	conout_puts(st, "Nebs OS EFI loader: ");
+	conout_puts(st, "NebOS EFI loader: ");
 	conout_puts(st, msg);
 	conout_puts(st, msg);
 	conout_puts(st, "\n");
 	conout_puts(st, "\n");
 	halt_forever();
 	halt_forever();

+ 1 - 69
io.c

@@ -72,9 +72,7 @@ static struct text_screen io_fallback;
 
 
 static struct text_screen *io_current_screen(void)
 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
 /* 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;
 	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)
 void io_putchar(char c)
 {
 {
@@ -247,60 +229,10 @@ void io_puthex(unsigned int n)
 	screen_puthex(io_current_screen(), 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)
 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)
 #define IO_DATETIME_POS   (io_get_cols() - IO_DATETIME_LEN)
 
 
 void io_init(void);
 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_putchar(char c);
 void io_putstr(const char *s);
 void io_putstr(const char *s);
 void io_puthex(unsigned int n);  /* print n as 8 hex digits, no 0x prefix */
 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);
 void io_drain_keyboard(void);
 
 
 /* Poll keyboard; returns 0 = no key, 1..255 = ASCII, or an IO_KEY_* code. */
 /* 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 "process.h"
 #include "ramfs.h"
 #include "ramfs.h"
 #include "sched.h"
 #include "sched.h"
-#include "sys_gfx.h"
 #include "thermal.h"
 #include "thermal.h"
 #include "timer.h"
 #include "timer.h"
 #include "tpec.h"
 #include "tpec.h"
@@ -237,14 +236,11 @@ static void system_housekeeping(void)
 	mouse_poll_update();
 	mouse_poll_update();
 #ifndef NOWM
 #ifndef NOWM
 	wm_pump_keyboard();
 	wm_pump_keyboard();
-	wm_blink_cursor();
 #endif
 #endif
 	netlog_flush();
 	netlog_flush();
 #ifndef NOWM
 #ifndef NOWM
 	wm_handle_kexec();
 	wm_handle_kexec();
 	wm_server_supervise();
 	wm_server_supervise();
-	if (wm_server_can_reap())
-		sys_gfx_collect();
 	if (!wm_server_frame_active())
 	if (!wm_server_frame_active())
 		vga_fb_flush_budget(VGA_FLUSH_BUDGET_BYTES);
 		vga_fb_flush_budget(VGA_FLUSH_BUDGET_BYTES);
 #else
 #else
@@ -495,9 +491,6 @@ void kernel_main(void)
 	 * while storage and the network are still being probed. */
 	 * while storage and the network are still being probed. */
 	wm_server_init();
 	wm_server_init();
 	boot_trace("wm 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();
 	wm_server_start();
 	boot_trace("wm");
 	boot_trace("wm");
 #else
 #else
@@ -530,12 +523,12 @@ void kernel_main(void)
 	vfs_mount_all();
 	vfs_mount_all();
 	boot_trace("storage");
 	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
 #ifndef NOWM
-	wm_spawn_terminal();
-	boot_trace("terminal");
+	wm_server_boot_ready();
+	boot_trace("terminal ready");
 #else
 #else
 	boot_trace("terminal off");
 	boot_trace("terminal off");
 #endif
 #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).
  * loop auto-detects the header and jumps into the new kernel).
  *
  *
  *   netkexec_send <board-ip> <port> <entry-hex> <kernel> [pack]
  *   netkexec_send <board-ip> <port> <entry-hex> <kernel> [pack]

+ 2 - 13
process.c

@@ -15,7 +15,6 @@
 #include "serial.h"
 #include "serial.h"
 #include "smp.h"
 #include "smp.h"
 #include "sys_fs.h"
 #include "sys_fs.h"
-#include "sys_gfx.h"
 #include "sys_mem.h"
 #include "sys_mem.h"
 #include "sys_net.h"
 #include "sys_net.h"
 #include "syscall.h"
 #include "syscall.h"
@@ -161,7 +160,6 @@ static void proc_commit(struct process *p, int slot, const char *name,
 	p->stride = 0;
 	p->stride = 0;
 	p->vruntime = 0;
 	p->vruntime = 0;
 	p->slice_start = 0;
 	p->slice_start = 0;
-	p->screen = parent ? parent->screen : (void *)0;
 	p->tty = parent ? parent->tty : 0;
 	p->tty = parent ? parent->tty : 0;
 	if (parent)
 	if (parent)
 		cwd_copy(p, parent->cwd);
 		cwd_copy(p, parent->cwd);
@@ -189,7 +187,6 @@ void process_init(void)
 	idle_procs[0].pid        = 0;
 	idle_procs[0].pid        = 0;
 	idle_procs[0].slot       = PROC_MAX;
 	idle_procs[0].slot       = PROC_MAX;
 	idle_procs[0].esp        = 0;
 	idle_procs[0].esp        = 0;
-	idle_procs[0].screen     = (void *)0;
 	idle_procs[0].stack_base = 0;  /* bootstrap stack, never freed */
 	idle_procs[0].stack_base = 0;  /* bootstrap stack, never freed */
 	idle_procs[0].cr3        = paging_current_cr3();
 	idle_procs[0].cr3        = paging_current_cr3();
 	idle_procs[0].kstack_top = (unsigned int)__boot_stack_top;
 	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
 /* Set the output screen of the currently-running process (used by a terminal
    at startup to bind itself to its own screen). */
    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
 /* 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. */
  * 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
 /* Free switched-out dead processes.  Runs in the kworker (or the idle
  * fallback), not in the PIT handler.  Preemption is disabled while the
  * 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. */
  * not re-entrant, matching the old IRQ-context reaper. */
 void process_reap_dead(void)
 void process_reap_dead(void)
 {
 {
@@ -653,7 +643,6 @@ void process_reap_dead(void)
 		struct process *next = p->zombie_next;
 		struct process *next = p->zombie_next;
 
 
 		sys_net_reap(p->pid);   /* release a held NIC */
 		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 */
 		tty_reap(p->pid);       /* drop its terminal queue */
 		if (p->stack_base)
 		if (p->stack_base)
 			mm_free_page(p->stack_base);
 			mm_free_page(p->stack_base);
@@ -665,7 +654,7 @@ void process_reap_dead(void)
 			paging_release_user_range(p->cr3,
 			paging_release_user_range(p->cr3,
 				USER_BASE, USER_STACK_TOP - USER_BASE, 1);
 				USER_BASE, USER_STACK_TOP - USER_BASE, 1);
 			paging_release_user_range(p->cr3,
 			paging_release_user_range(p->cr3,
-				USER_GFX_BASE, USER_GFX_RANGE, 0);
+				USER_WIN_BASE, USER_WIN_RANGE, 0);
 			sys_mem_release(p);
 			sys_mem_release(p);
 			/* WM surface mappings: page tables only; the shadow/
 			/* WM surface mappings: page tables only; the shadow/
 			 * terminal/canvas pages belong to the window server. */
 			 * terminal/canvas pages belong to the window server. */

+ 4 - 8
process.h

@@ -30,7 +30,6 @@
 #define PROC_NAME_LEN 12
 #define PROC_NAME_LEN 12
 #define PROC_CWD_MAX  64
 #define PROC_CWD_MAX  64
 
 
-struct text_screen;  /* forward decl (see screen.h) */
 struct sys_procinfo; /* forward decl (see syscall.h; `top` snapshot) */
 struct sys_procinfo; /* forward decl (see syscall.h; `top` snapshot) */
 struct surface;      /* forward decl (see vga.h; render target override) */
 struct surface;      /* forward decl (see vga.h; render target override) */
 
 
@@ -40,7 +39,6 @@ struct process {
 	unsigned int pid;
 	unsigned int pid;
 	unsigned int slot;           /* index in procs[], PROC_MAX for idle */
 	unsigned int slot;           /* index in procs[], PROC_MAX for idle */
 	char         name[PROC_NAME_LEN];
 	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 stack_base;     /* page to free on exit, or 0 (bootstrap/fallback) */
 	unsigned int cr3;            /* physical address of this process's page dir */
 	unsigned int cr3;            /* physical address of this process's page dir */
 	unsigned int heap_pages;     /* pages mapped at USER_HEAP_BASE, or 0 */
 	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_BASE        0x40000000   /* user program link/load address */
 #define USER_STACK_TOP   0x40200000   /* user stack top (grows down) */
 #define USER_STACK_TOP   0x40200000   /* user stack top (grows down) */
 #define USER_STACK_PAGES 8            /* user stack size in 4 KB pages */
 #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
 /* Anonymous per-process heap (SYS_MEM_ALLOC/GROW/FREE): one growable arena
  * above the WM mappings.  Freed by the reaper. */
  * above the WM mappings.  Freed by the reaper. */
 #define USER_HEAP_BASE   0x60000000u
 #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,
 int process_create_user_tty(const char *name, const void *image,
 			unsigned int size, const char *arg, const char *cwd,
 			unsigned int size, const char *arg, const char *cwd,
 			unsigned int tty);
 			unsigned int tty);
-void process_set_screen(struct text_screen *screen);
 /* Render target override for the running process (0 = the screen). */
 /* Render target override for the running process (0 = the screen). */
 struct surface *process_render_target(void);
 struct surface *process_render_target(void);
 void process_set_render_target(struct surface *s);
 void process_set_render_target(struct surface *s);

+ 1 - 42
screen.c

@@ -7,7 +7,7 @@
 
 
 /* ---- Damage tracking ----
 /* ---- 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
  * 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()
  * 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
  * 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)
 static void screen_damage_cell(struct text_screen *s, unsigned int col, unsigned int row)
 {
 {
-	s->damage_seq++;
 	if (!s->dirty) {
 	if (!s->dirty) {
 		s->dirty = 1;
 		s->dirty = 1;
 		s->dmg_col0 = s->dmg_col1 = col;
 		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)
 static void screen_damage_all(struct text_screen *s)
 {
 {
-	s->damage_seq++;
 	s->dirty = 1;
 	s->dirty = 1;
 	s->dmg_col0 = 0;
 	s->dmg_col0 = 0;
 	s->dmg_col1 = s->cols - 1;
 	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);
 	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)
 void screen_init(struct text_screen *s)
 {
 {
@@ -77,8 +60,6 @@ void screen_init(struct text_screen *s)
 	s->cursor = 0;
 	s->cursor = 0;
 	s->cursor_attr = (SCREEN_ATTR << 8);
 	s->cursor_attr = (SCREEN_ATTR << 8);
 	s->cursor_visible = 0;
 	s->cursor_visible = 0;
-	s->scrolled = 0;
-	s->damage_seq = 0;
 	screen_clear(s);
 	screen_clear(s);
 }
 }
 
 
@@ -89,7 +70,6 @@ void screen_clear(struct text_screen *s)
 		s->cells[i] = (unsigned short)((SCREEN_ATTR << 8) | ' ');
 		s->cells[i] = (unsigned short)((SCREEN_ATTR << 8) | ' ');
 	s->cursor = 0;
 	s->cursor = 0;
 	screen_damage_all(s);
 	screen_damage_all(s);
-	s->scrolled = 0;
 }
 }
 
 
 static void screen_scroll_up(struct text_screen *s)
 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) {
 		if (s->cursor >= total) {
 			screen_scroll_up(s);
 			screen_scroll_up(s);
 			s->cursor = total - ncols;
 			s->cursor = total - ncols;
-			s->scrolled = 1;
 		}
 		}
 		s->cursor_attr = (SCREEN_ATTR << 8);
 		s->cursor_attr = (SCREEN_ATTR << 8);
 		screen_damage_cursor(s);
 		screen_damage_cursor(s);
@@ -160,20 +139,7 @@ void screen_puthex(struct text_screen *s, unsigned int n)
 	screen_putstr(s, buf);
 	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)
 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;          /* linear index 0..cols*rows-1 */
 	unsigned int cursor_attr;
 	unsigned int cursor_attr;
 	unsigned int cursor_visible;
 	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_col0, dmg_col1;
 	unsigned int dmg_row0, dmg_row1;
 	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);
 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_putchar(struct text_screen *s, char c);
 void screen_putstr(struct text_screen *s, const char *str);
 void screen_putstr(struct text_screen *s, const char *str);
 void screen_puthex(struct text_screen *s, unsigned int n);
 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);
 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);
 void screen_damage_cursor(struct text_screen *s);
 
 
 #endif
 #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);
 	return wm_server_present(&p);
 }
 }
 
 
+int sys_wm_key_poll(void)
+{
+	return wm_server_key_poll();
+}
+
 int sys_wm_sync(void)
 int sys_wm_sync(void)
 {
 {
 	return wm_server_sync();
 	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_poll(struct wm_status *out);
 int sys_wm_begin(void);
 int sys_wm_begin(void);
 int sys_wm_present(const struct wm_present_info *in);
 int sys_wm_present(const struct wm_present_info *in);
+int sys_wm_key_poll(void);
 int sys_wm_sync(void);
 int sys_wm_sync(void);
 
 
 int sys_win_create(const struct win_create *in, struct win_info *out);
 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 "rtc.h"
 #include "serial.h"
 #include "serial.h"
 #include "sys_fs.h"
 #include "sys_fs.h"
-#include "sys_gfx.h"
 #include "sys_info.h"
 #include "sys_info.h"
 #include "sys_mem.h"
 #include "sys_mem.h"
 #include "sys_net.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:
 	case SYS_PROCINFO:
 		return process_procinfo((unsigned int)a1,
 		return process_procinfo((unsigned int)a1,
 					(struct sys_procinfo *)a2);
 					(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:
 	case SYS_KEY_POLL:
-		return sys_gfx_key_poll();
+		return sys_wm_key_poll();
 	case SYS_RTC_HMS: {
 	case SYS_RTC_HMS: {
 		struct sys_time *out = (struct sys_time *)a1;
 		struct sys_time *out = (struct sys_time *)a1;
 		unsigned int h, m, s;
 		unsigned int h, m, s;

+ 1 - 18
syscall.h

@@ -72,17 +72,7 @@
 /* Process snapshot for the `top` command (see process.c). */
 /* Process snapshot for the `top` command (see process.c). */
 #define SYS_PROCINFO     49  /* (unsigned int index, struct sys_procinfo *out)
 #define SYS_PROCINFO     49  /* (unsigned int index, struct sys_procinfo *out)
 				-> 1 when found, 0 at the end of the table */
 				-> 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 */
 #define SYS_RTC_HMS      56  /* (struct sys_time *out) -> 0/-1 */
 
 
 /* Window-manager service (see wm_abi.h).  Only the kernel-spawned WM process
 /* 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;
 	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). */
 /* Wall clock for the ring-3 clock (see rtc.c). */
 struct sys_time {
 struct sys_time {
 	unsigned int hour;     /* 0-23 */
 	unsigned int hour;     /* 0-23 */

Filskillnaden har hållts tillbaka eftersom den är för stor
+ 6 - 1001
terminal.c


+ 0 - 49
terminal.h

@@ -2,66 +2,17 @@
 #ifndef TERMINAL_H
 #ifndef TERMINAL_H
 #define TERMINAL_H
 #define TERMINAL_H
 
 
-#include "sched.h"
 #include "screen.h"
 #include "screen.h"
 #include "vfs.h"
 #include "vfs.h"
 
 
-#define CURSOR_MS    500
-#define LINE_MAX     64
-#define HISTORY_SIZE 32
-#define KEY_BUF_SIZE 16
-
 struct term {
 struct term {
 	struct text_screen screen;
 	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 cwd[VFS_PATH_MAX];     /* absolute current working directory */
 	char path[VFS_PATH_MAX];    /* command search path (colon separated) */
 	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
 /* 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). */
  * 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);
 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
 #endif

+ 2 - 2
testdata/browser/demo.html

@@ -1,6 +1,6 @@
 <html>
 <html>
 <head>
 <head>
-<title>Nebs demo</title>
+<title>NebOS demo</title>
 <style>
 <style>
 body { margin: 10px; color: #e4e6f0; }
 body { margin: 10px; color: #e4e6f0; }
 h1 { color: #ff8a66; }
 h1 { color: #ff8a66; }
@@ -14,7 +14,7 @@ td { padding-right: 18px; }
 <body>
 <body>
 <h1>Local browser demo</h1>
 <h1>Local browser demo</h1>
 <p>This page came from <b>/floppy1/DEMO.HTM</b> and was rendered by the
 <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">
 <div class="note">
 <b>Inline styles and classes:</b>
 <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);
 /* Cursor position of this process's terminal screen (linear cell index);
  * used by `top` to repaint its frame in place. */
  * 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)
 static inline void u_sleep_ms(unsigned int ms)
 {
 {
 	u_syscall1(SYS_SLEEP_MS, (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);
 	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)
 static inline int u_key_poll(void)
 {
 {
 	return u_syscall0(SYS_KEY_POLL);
 	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[] = {
 static const char *const about_lines[] = {
-	"Nebs OS edition",
+	"NebOS edition",
 	"",
 	"",
 	"A Windows 95 style Klondike.",
 	"A Windows 95 style Klondike.",
 	"Drag, drop, and bounce."
 	"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);
 	rad((unsigned int)code);
 	ra(" ");
 	ra(" ");
 	ra(reason);
 	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"
 	ra((rq.keep_alive && code < 400) ? "Connection: keep-alive\r\n"
 					 : "Connection: close\r\n");
 					 : "Connection: close\r\n");
 	ra("Cache-Control: no-store\r\n");
 	ra("Cache-Control: no-store\r\n");
@@ -335,7 +335,7 @@ static int send_multistatus_begin(void)
 {
 {
 	resp_len = 0;
 	resp_len = 0;
 	ra("HTTP/1.1 207 Multi-Status\r\n");
 	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("Content-Type: text/xml; charset=\"utf-8\"\r\n");
 	ra("Transfer-Encoding: chunked\r\n");
 	ra("Transfer-Encoding: chunked\r\n");
 	ra(rq.keep_alive ? "Connection: keep-alive\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)
 static void do_options2(void)
 {
 {
 	resp_len = 0;
 	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("DAV: 1, 2\r\nMS-Author-Via: DAV\r\n");
 	ra("Allow: OPTIONS, GET, HEAD, PUT, DELETE, MKCOL, PROPFIND, "
 	ra("Allow: OPTIONS, GET, HEAD, PUT, DELETE, MKCOL, PROPFIND, "
 	   "PROPPATCH, MOVE, LOCK, UNLOCK\r\n");
 	   "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 resize_mx, resize_my, resize_ow, resize_oh;
 static unsigned int prev_buttons;
 static unsigned int prev_buttons;
 static int full_redraw = 1;
 static int full_redraw = 1;
+static int boot_term_spawned;
 static unsigned int bar_kexec_busy, bar_kexec_progress, bar_kexec_total;
 static unsigned int bar_kexec_busy, bar_kexec_progress, bar_kexec_total;
 static int bar_temp_c = -1;
 static int bar_temp_c = -1;
 static char bar_msg[24];
 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);
 		(st->kexec_busy && st->kexec_progress != bar_kexec_progress);
 	unsigned int msg_now = u_ticks_ms();
 	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 ||
 	if (bar_msg_dirty ||
 	    (bar_msg_until && (int)(msg_now - bar_msg_until) >= 0)) {
 	    (bar_msg_until && (int)(msg_now - bar_msg_until) >= 0)) {
 		bar_dirty = 1;
 		bar_dirty = 1;

+ 1 - 1
version.h

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

Filskillnaden har hållts tillbaka eftersom den är för stor
+ 95 - 799
wm.c


+ 5 - 22
wm.h

@@ -2,8 +2,8 @@
 #ifndef WM_H
 #ifndef WM_H
 #define WM_H
 #define WM_H
 
 
-#include "terminal.h"
 #include "gfx.h"
 #include "gfx.h"
+#include "sched.h"
 #include "wm_abi.h"
 #include "wm_abi.h"
 
 
 #define MAX_WINDOWS WM_MAX_WINDOWS
 #define MAX_WINDOWS WM_MAX_WINDOWS
@@ -14,9 +14,8 @@ struct window {
 	unsigned int pw, ph;     /* pixel size */
 	unsigned int pw, ph;     /* pixel size */
 	char title[16];
 	char title[16];
 	int focused;
 	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;
 	int canvas_window;
 	struct gfx_canvas canvas;
 	struct gfx_canvas canvas;
 	unsigned short *back;
 	unsigned short *back;
@@ -37,18 +36,11 @@ struct window {
 	unsigned int mapped_gen;
 	unsigned int mapped_gen;
 	unsigned int mapped_pages;
 	unsigned int mapped_pages;
 	const void *mapped_src;
 	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
 /* 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_pump_keyboard(void);
-void wm_blink_cursor(void);
 void wm_handle_kexec(void);
 void wm_handle_kexec(void);
 int  wm_spawn_terminal(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_key_wait(unsigned int timeout_ms);
 int  wm_server_win_pointer(struct win_pointer *out);
 int  wm_server_win_pointer(struct win_pointer *out);
 int  wm_server_win_event(struct win_event *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);
 struct window *wm_focused_window(void);
 int  wm_is_focused(const struct window *w);
 int  wm_is_focused(const struct window *w);
 void wm_request_redraw(void);
 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
 #endif

+ 1 - 0
wm_abi.h

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

Vissa filer visades inte eftersom för många filer har ändrats