From ab7d87bcde31c1681ea09c30534dde840a58d6fa Mon Sep 17 00:00:00 2001
From: salmonik <salmonik@tuta.io>
Date: Sat, 1 Aug 2026 22:28:34 +0200
Subject: rsnix v0.5.2: fault diagnostics + real-hardware scroll-crash
 hardening
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The real-hardware scroll crash (white bands + instant freeze, QEMU-clean)
was invisible because the only trace was a single serial line on machines
with no serial console.  This makes every crash self-identifying and
hardens the real-hardware failure surfaces:

- Every CPU exception vector 0-31 now has an IDT entry (macro-generated
  stubs; 8/14 keep their IST stacks).  A fault in the shell prints a
  white-on-red band to the framebuffer via gop::dump_lines (raw fb
  writes bypassing the vt, fully clamped) plus a parseable serial line:
  '!!! <kind> vec=N err=… rip=… cr2=… rsp=… rflags=… task=N "name"',
  then halts — instead of converging to a cryptic double fault.
  Background-task faults abort the task as before.
- Boot log now reports the authoritative post-SetMode geometry:
  'gop: fb base=… size=… pitch=… WxH bpp=… bgr=…', so the next real
  machine's report identifies whether pitch*height exceeds the mapping.
- Framebuffer writes (clear, push_rect, shift_up_n bulk push, cursor
  overlay) are clamped to the firmware's framebuffer_size: a pitch-
  padded mode degrades to a truncated view instead of faulting past
  the mapping.
- The GOP framebuffer region is excluded from the page allocator (and
  subtracted from the heap's conventional-region pick) even when the
  firmware lists it as ConventionalMemory — kernel allocations can
  never overwrite the display again.  The GOP protocol is located and
  peeked before the memory map is captured so the exclusion is known
  at heap-init time.
- Shell gains a hidden 'fault' command (deliberate unmapped write) and
  'make test-fault' verifies the dump: vec=14, cr2=0x400000000000,
  task=0, halt — no triple fault.  All other suites re-pass.
- CONTEXT.md: fault-dump format documented for real-hardware reports.
---
 CONTEXT.md | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

(limited to 'CONTEXT.md')

diff --git a/CONTEXT.md b/CONTEXT.md
index 375bf57..f068035 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -113,10 +113,13 @@ Workspace version is `a.b.c` (single version for all crates):
 
 Bump the workspace version in the root `Cargo.toml` when a change of
 that class lands — do not leave the version to drift.  Current:
-`0.5.1` — the GUI era landed with 0.5.0 (graphics layer + cursor
-compositor) and the canvas was fixed at 800×600 as a `c` bump; a
-future major GUI overhaul (graphics windows beyond the text surface)
-would be the `a` bump (1.0.0).
+`0.5.2` — the GUI era landed with 0.5.0 (graphics layer + cursor
+compositor); 0.5.1 fixed the canvas at 800×600; 0.5.2 added fault
+diagnostics (screen + serial dumps for every CPU exception) and
+real-hardware hardening (framebuffer-size clamping, fb-region exclusion
+from the allocators, authoritative fb geometry logging).  A future
+major GUI overhaul (graphics windows beyond the text surface) would be
+the `a` bump (1.0.0).
 
 ## Project layout
 
@@ -388,6 +391,18 @@ Workspace of four crates, all built for the `x86_64-unknown-uefi` target:
     hardware pushes only 24 bytes at same privilege, so the extra
     fields are inert there; the synthetic frames set them
     explicitly either way.
+- `interrupts`/`sched` fault dumps (0.5.2): every CPU exception
+    vector 0-31 has an IDT entry (macro-generated stubs; 8/14 keep
+    their ISTs).  Any fault in the shell (task ≤ 1) prints a
+    white-on-red band via `gop::dump_lines` (raw fb, bypasses vt,
+    clamped) *and* a parseable serial line — `!!! <kind> vec=N
+    err=… rip=… cr2=… rsp=… rflags=… task=N "name"` — then halts;
+    faults in background tasks abort the task instead.  Real
+    hardware has no serial console, so the screen band is how a
+    crash reports itself; a non-canonical write shows vec=13 (GP,
+    cr2=0), an unmapped canonical address shows vec=14 with cr2=
+    the address.  `fault` shell command + `make test-fault` verify
+    the path.
 - Panic handling: a task panic (or guard-page overflow) is caught,
     logged as `sched: task N "name" panicked: …`, the task is marked
     Done, and the scheduler switches away — the shell keeps running.
-- 
cgit v1.2.3