From c7540c31d45dac68fa1852f5d25645d569b2da9d Mon Sep 17 00:00:00 2001
From: salmonik <salmonik@tuta.io>
Date: Sat, 1 Aug 2026 14:09:14 +0200
Subject: klog: kernel log ring + /dev/klog + klog shell command

- rsnix/src/klog.rs: RAM ring of the last 128 serial log lines (128
  chars each), fed by serial_println! so every boot/low-level message
  is captured for free.  Sequence numbers per line, wrap/drop
  accounting; the ring never allocates (const-constructible static).
- /dev/klog char device; shell 'klog' is a thin alias for cat
  /dev/klog with the same filters/redirection, so 'klog -t 5',
  'klog -g fat' and 'klog WRITING /disk/.../boot.log' all work.
  klog rejects positional args (usage) and input keywords.
- Shell user-facing output (banner, prompt, term_print/term_println,
  pipeline sink, halt/poweroff) now writes to serial directly instead
  of through serial_println!, keeping echo/cat output out of the boot
  log (a streaming cat /dev/mem would otherwise wrap the ring).
- serial_println! macro hooks klog::append_fmt via format_args! (no
  alloc at call sites); klog::dump formats the log for the device.

Verified in QEMU: 28 boot lines captured (seq 0..27), shell output
absent from the ring, klog WRITING persists a boot log (mtype-checked),
wrap verified with a temporary 140-line boot loop (128 kept / 40
dropped, seq 40..167, oldest-live correct; loop reverted); full
test-disk round trip still fsck-clean.
---
 CONTEXT.md | 36 ++++++++++++++++++++++++++++--------
 1 file changed, 28 insertions(+), 8 deletions(-)

(limited to 'CONTEXT.md')

diff --git a/CONTEXT.md b/CONTEXT.md
index c6bd5f9..86822d1 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -255,6 +255,34 @@ Workspace of four crates, all built for the `x86_64-unknown-uefi` target:
     monitor (`--sock`, US layout, named keys for punctuation; bare
     `-`/`.`/`/` are not valid sendkey names)
 
+✅ **`klog` kernel log ring** — a RAM ring of the last 128 serial log
+  lines (128 chars each, ~16 KB), fed by `serial_println!` (one choke
+  point — every boot/low-level message captured for free).  Sequence
+  numbers per line + wrap/drop accounting; a dump header reports how
+  many lines were lost to wrap.  Exposed as the `/dev/klog` char
+  device; the shell `klog` command is a thin alias for `cat
+  /dev/klog` (same filters/redirection), so `klog -t 5`, `klog -g
+  fat`, and `klog WRITING /disk/…/boot.log` (persists the boot log)
+  all work.  The ring never allocates (const-constructible static);
+  only the dump allocates, at shell time.  `klog` rejects positional
+  args (usage) and input keywords ("does not accept input").
+
+  **Design consequence: shell output must not feed the ring.**  The
+  plan's "hook `serial_println!`" only works if that macro is
+  kernel-logging-only — but the shell printed prompts/errors/results
+  through it, which would have flooded the boot log with echo/cat
+  output (a `cat /dev/mem` would wrap the ring).  The shell now
+  writes user-facing output (banner, prompt, `term_print`/
+  `term_println`, pipeline sink, halt/poweroff) directly to the
+  serial port via `serial::write_str`; tty echo already did.  Only
+  kernel messages (rsnix modules + `rsdos/main.rs`) go through
+  `serial_println!` now.  Verified in QEMU: 28 boot lines captured
+  (seq 0..27, first `=== rsnix boot ===`, last `boot: entering
+  shell`), `echo hello` output absent from the ring, `klog WRITING`
+  persists a boot log (mtype-verified), wrap behavior verified with a
+  temporary 140-line boot loop (128 kept / 40 dropped, seq 40..167,
+  oldest live line correct — loop reverted after the test).
+
 ## Known issues / perf notes
 
 - **Scroll cost** — scrolling still shifts the whole framebuffer (a
@@ -289,14 +317,6 @@ Workspace of four crates, all built for the `x86_64-unknown-uefi` target:
 
 ## Pending decisions (agreed, not yet implemented)
 
-- **`klog` kernel log ring**: capture all boot/low-level messages by
-  appending to a RAM ring buffer inside `serial_println!` (one choke
-  point, every existing message captured for free).  Ring: 128 lines ×
-  128 chars ≈ 16 KB, sequence numbers, wrap/drop accounting.
-- **`klog` command** = thin alias for `cat /dev/klog` plus filters
-  `-h` (head) and `-t` (tail); no log levels, no timestamps, nothing
-  fancier.  `/dev/klog` is a char device so `klog WRITING /disk/…/boot.log`
-  persists a boot log via the existing redirection.
 - **Disk recognition scope — keep simple for now**: no pre-EBS UEFI
   block-device census, no GPT/MBR partition parsing, no NVMe driver.
   (Revisit later: Linux-style recognition = PCI scan → ahci/nvme →
-- 
cgit v1.2.3