danos/docs/logging.md

Logging: the diagnostic log vs. the display

danos separates two things that are easy to conflate: the diagnostic log — the machine-readable stream of what the kernel is doing — and the display, the framebuffer surface the OS draws on. They are different concerns with different lifetimes, so they're different code paths.

The guiding rule: output is a diagnostic convenience, never a correctness dependency. The kernel must boot and run correctly with zero output channels — no serial, no screen. Logging that can take the kernel down isn't robust; it's a liability. This is the same resilience posture the rest of the kernel follows.

The log is multi-sink

src/kernel/log.zig is the diagnostic log. It fans a message out to a set of registered sinks, each best-effort and self-guarding:

log.addSink(arch.serialWrite);              // the serial UART
if (arch.debugconPresent()) log.addSink(arch.debugconWrite); // 0xE9 debug console
// later: log.addSink(fs.logWrite);         // a file on a ramdisk / USB / SSD
log.write("…");  log.print("x={d}\n", .{x});

Properties that matter:

• No allocation. The sink table is a fixed array, so the log works before the heap is up and inside a panic.
• Best-effort. A sink whose device is absent is a no-op (e.g. writing to a missing UART just goes nowhere — the TX-wait is bounded so it can't hang). A message reaches whatever channels exist; if none do, the kernel runs on, silent.
• Order-independent. Every registered sink gets every message. Adding the file logger later is one addSink call and zero changes to call sites.

The framebuffer is not a log sink

The framebuffer is a general graphics surface, not inherently a text terminal. Today src/kernel/console.zig paints a text grid on it as a bootstrap console, but that's a stop-gap: once the driver machinery exists the framebuffer becomes a proper graphics device driver, and the text crutch goes away. So the log must not assume it — routing the verbose log through a pixel console would bake in "the OS is text".

Instead the two paths are explicit:

verbose diagnostics ──► log ──► serial, debugcon, (file later)
user status / panics ──► status() ──► log (above)  +  framebuffer (if present)

A handful of user-facing lines (kernel initialised, a panic) go through main.zig's status() / statusPrint(), which write to the log and paint the framebuffer when one is present. Everything else uses log.* and never touches the screen. console.write is a no-op when the firmware gave us no framebuffer.

Optional framebuffer (headless machines)

A framebuffer is not guaranteed — a headless server exposes no UEFI Graphics Output Protocol. That used to be fatal (the loader failed the boot). Now the loader hands over a "no framebuffer" descriptor (base == 0) rather than failing, and Framebuffer.present() (in src/root.zig) gates every on-screen path. A headless, serial-less machine boots and runs correctly — it just goes quiet.

Last-resort channels (no text output at all)

Two signals bypass the sink list, because they must survive even a total output-channel failure:

• log.checkpoint(code) — a one-byte POST code to I/O port 0x80 (a POST card or BMC shows it). main.zig emits one at each boot milestone (cp_paging, cp_heap, …) and on a fault/panic, so "where did it hang?" is answerable with no text output whatsoever. Writing 0x80 is universally safe.
• log.recordPanic(msg) — stamps the panic message into a fixed record (log.panic_record, with a magic written last). A post-mortem — an attached debugger, a RAM dump, or a future file/pstore reader — recovers what killed it even though nothing was on screen.

The panic and CPU-exception handlers fan out to every sink, emit a POST code, and drop the breadcrumb — they never assume a console.

The 0xE9 debug console

Port 0xE9 is the Bochs/QEMU debug console. It's detected safely: the port returns 0xE9 when read if present, and 0xFF on real hardware, so debugconPresent() only enables the sink when it's really there. Under QEMU it's captured with -debugcon file:…, giving CI a log channel independent of -serial.

The robustness spectrum

The result handles every combination — framebuffer only, serial only, both, or neither. With no channels at all the kernel still boots and runs; port-0x80 checkpoints track progress and the panic breadcrumb captures failures. Runs blind but correct is the goal, not always has output.

Related

• framebuffer.md — the display surface itself (pitch, format), the thing that becomes a graphics device driver.
• efi.md — where the loader captures (or, headless, doesn't capture) the framebuffer before ExitBootServices.
• device-interrupts.md — the serial UART bring-up the log's primary sink rides on.
• resilience.md — why "never let a missing peripheral take the kernel down" is a core design stance.