re-org docs

2026-07-23 00:25:34 +01:00
parent 52d6e372fd
commit 757c6f14c3
52 changed files with 156 additions and 156 deletions
@@ -0,0 +1,100 @@
+# Logging
+
+Output is a *diagnostic convenience, never a correctness dependency*: the kernel
+and every service must run correctly with zero output channels. On top of that
+rule, danos has **per-process logging** — every process's output is attributed
+by the kernel and lands in its own file on the flash volume, which is what makes
+a headless real machine (no serial port) debuggable. The display (the
+framebuffer surface) is a separate concern with one bootstrap exception: the
+kernel's framebuffer console (`system/kernel/console.zig`) joins the log sinks
+at boot, so the whole transcript shows on screen until the display service
+claims the framebuffer and silences it; after that only panic/fatal messages
+are mirrored to it explicitly (`system/kernel/kernel.zig`).
+
+## The pipeline
+
+```
+process std.log ──▶ debug_write(level) ──▶ tagged kernel ring ──▶ logger service ──▶ /var/log/<boot-stamp>/<binary-path>.log
+kernel log.print ─┘                            │
+                                               └▶ serial / 0xE9 sinks (QEMU, -Dserial)
+```
+
+1. **Emit.** A program calls `std.log.info("mounted {s}", .{path})` — the
+   runtime's `logFn` (installed for every binary by the root shim,
+   `library/kernel/logging.zig`) formats one line and issues one `debug_write`
+   carrying the level. The payload does NOT contain the process's name.
+   `logging.write` remains as the raw/bring-up path (panics, test
+   fixtures); raw bytes ride the same ring, attributed all the same.
+
+2. **Stamp.** The kernel wraps every payload LINE in a record stamped with the
+   sender's pid, task name (its binary path, e.g. `/system/services/fat`),
+   level, a per-boot sequence number, and a monotonic timestamp
+   (`system/kernel/log.zig` + `log-ring.zig`). Attribution is structural — a
+   payload cannot forge another sender's tag, and an embedded newline just ends
+   the record, so the forged "prefix" lands inside the forger's own next line.
+
+3. **Retain.** The 512 KiB ring overwrites oldest-first; sequence gaps make any
+   loss countable. `klog_read` (#32) copies stream bytes from a free-running
+   offset; `klog_status` (#45) returns the cursors plus the wall-clock time of
+   boot. The framing (`abi.KlogRecordHeader`) is 32 bytes + name + payload,
+   8-byte aligned.
+
+4. **Render.** Registered sinks (serial under `-Dserial`, the 0xE9 debug
+   console, and the framebuffer console until the display service claims the
+   screen) get a live transcript: kernel/raw output verbatim, leveled records
+   as `<binary path>: message` — one composed write per line, under the log's
+   own spinlock (never the big kernel lock; panic paths try-acquire with a
+   bound and fall back to sinks-only). Sinks are best-effort and self-guarding;
+   a serial-less machine just goes quiet.
+
+5. **Persist.** The **logger service** (`system/services/logger`) drains the
+   ring every 250 ms and demultiplexes records into one file per source under
+   `/var/log/<boot-stamp>/`, e.g.
+
+   ```
+   /var/log/2026-07-21T150434Z/kernel.log
+   /var/log/2026-07-21T150434Z/system/services/fat.log
+   /var/log/2026-07-21T150434Z/system/drivers/usb-storage.log
+   ```
+
+   The boot stamp is the RTC anchor from `klog_status` (FAT-safe: no colons; a
+   dead RTC yields the 1970 directory rather than no logs). Each line carries
+   the record's monotonic timestamp and level. Storage is best-effort and late:
+   the ring buffers a whole boot many times over, and the first successful
+   `makePath` of the per-boot directory (also the readiness probe) triggers a
+   full backlog write. Files close — which is the fat server's SCSI cache
+   flush — after a ~2 s quiet period, bounding data-at-risk without per-record
+   flush thrash. At shutdown init stops the logger FIRST (it is last in the
+   boot order), so its final drain runs over a live storage chain.
+
+## Why a ring in the kernel, not a logging server
+
+The storage stack must be able to log. If the fat server wrote its own log file
+through the VFS it would rendezvous-deadlock on itself; if processes sent
+records to a logging server over IPC, early boot would need a buffer that is —
+a ring, one hop later. The kernel ring is that buffer, placed where every
+process (and the kernel itself) can reach it with one syscall, before any
+service exists. The logger service is a *reader*, not a hop.
+
+Two disciplines keep it honest:
+
+- the logger announces itself **once** — a periodic status line would feed the
+  very stream it drains;
+- lost records surface as an explicit `-- N records lost --` line, computed
+  from sequence gaps, never silently.
+
+## Last-resort channels
+
+Unchanged, and independent of the sink list so they survive a total output
+failure: `checkpoint` (a one-byte POST code on port 0x80) and `recordPanic`
+(a fixed breadcrumb record, `log.panic_record`, findable in a RAM dump; magic
+written last so a reader only trusts a complete record).
+
+## Accepted gaps
+
+- A write-spamming process can evict other processes' unread records from the
+  ring (a per-process quota is future work); the loss is at least visible via
+  sequence gaps in every affected file.
+- `/var/log` files have no privacy until the VFS grows permissions.
+- Records emitted after the logger's final shutdown drain reach serial and the
+  ring but not the files.