debugger: the kernel can be asked a question

docs/plan/debugger.md, milestones D0, D1 and D2. What they replace is the
ninety-second loop -- add a cprintf, rebuild, boot, read the serial log --
which answers exactly the one question you thought of before the rebuild.

The rule the shape follows: **it observes, it does not control.** No
stepping, no software breakpoints, no stopping the world. Half the bugs
this kernel produces are timing -- an interrupt storm, a level-triggered
line nobody acknowledges, a driver that faults only on its second start --
and every one of them disappears when you halt the machine to look. And
the layering rule, which is the circularity rule the display already has:
a debugger that needs lwIP cannot debug lwIP.

D0 -- symbols. tools/ksyms.pl turns the first link pass into a table the
second pass carries. Two passes is enough because .ksym is placed after
.text and .rodata, so carrying the table cannot move anything recorded in
it; the build lists both passes' text symbols and refuses to link if they
ever disagree, because a symbol table that is subtly wrong gives confident
false answers. ksym.c reads it through weak symbols, so pass one -- which
has no table -- still links. A crash chain now reads panic+0x5f <-
proc_sysrq_cmd+0x99 <- ... <- syscall+0xf6.

D1 -- a log that outlives the kernel. Every character through consputc()
lands in a byte ring with a timestamp per line, readable as /proc/kmsg.
It sits in a region carved before the page allocator gets anything, with a
magic header, so a kernel finds the previous kernel's log still there --
including the whole PSOGM report. panic.c's own comment said "there is no
core dump and no log to go back to"; that is no longer true.

  The obvious place for it is the top of RAM beside the DMA arena. That
  was the first attempt and the magic came back as ASCII on the reboot,
  because the top of usable memory is exactly where the firmware makes its
  own allocations. It lives above the kernel image instead, which is a
  stable address across boots of the same build.

D2 -- the introspection registry. A subsystem publishes its state with one
line at the bottom of the file that owns the data:

  dbg_register("dma", dma_dump, "the DMA arena's free extents");

Seven views -- dma, mem, proc, vma, claims, pci, sock -- reachable three
ways: sysrq 'g' (always, no process and no filesystem), /dev/dbg (echo a
line, cat the answer), and schdbg. The protocol is lines of text because
the same bytes have to work where nothing can allocate or frame a record,
and because a protocol you cannot drive by hand is one you cannot debug.
struct sbuf moved out of kernel/dev/procfs.c into include/sbuf.h rather
than being written a second time.

Several views exist because of a specific bug. `vma` is the table that
decides whether exit() frees a page, and the DMA ownership bug that made
this worth building was a block that was never in it.

Also fixed, found by building with clang for the first time in a while:
struct iovec was defined in both posix.h and socket.h, and every file that
included both was a redefinition. GCC 15 defaults to C23, which permits an
identical struct redeclaration, so the gcc path never noticed -- while
clang defaults to gnu17 and rejected it, breaking the one toolchain
shell.nix exists to provide and the UEFI loader requires. Both are now
guarded.

D3 (`whose <addr>`, the cross-subsystem ownership query) and D4 (hardware
watchpoints on DR0-DR3) are not built and are described honestly as
missing in the architecture doc's "What it does not do".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2

include/dbg.h

@@ -0,0 +1,55 @@
+#pragma once
+
+#include "types.h"
+
+struct sbuf;
+
+// Asking the kernel a question.
+//
+// docs/plan/debugger.md milestone D2. The thing this exists to end is the
+// ninety-second loop: add a cprintf, rebuild, boot, read the serial log, and
+// learn the answer to exactly the one question you thought of before the
+// rebuild.
+//
+// The interesting part is not the views. It is that a subsystem publishes its
+// own state with **one line at the bottom of the file that owns the data**, and
+// nothing central has to be edited to add one:
+//
+//     dbg_register("dma", dma_dump, "the DMA arena's free extents");
+//
+// That is the difference between something that stays current and something
+// that does not. /proc/sysrq is the version that does not -- a switch in one
+// file with a letter per action, which is why after two years it holds three
+// self-tests and no state at all.
+//
+// Views run in ordinary process context, from a write to /dev/dbg or from
+// sysrq, so they may take locks. **They must not be called from panic().**
+
+// The argument is whatever followed the view's name on the command line, or
+// "" when there was none. Most views ignore it; the ones that can produce a
+// hundred lines use it to narrow -- `vma 4` rather than `vma`. It is also the
+// shape milestone D3 needs, since `whose <addr>` is nothing but an argument.
+typedef void (*dbg_view_fn)(struct sbuf *out, const char *arg);
+
+// Publish a view. `what` is one line, shown by `help`.
+//
+// Safe to call from any subsystem's init, in any order: the table is static
+// and needs no initialisation of its own.
+void dbg_register(const char *name, dbg_view_fn fn, const char *what);
+
+// Run one command line and render the answer. Returns the number of bytes
+// written into `out`.
+//
+// The protocol is lines of text -- see docs/plan/debugger.md for why that and
+// not a typed binary format. Commands:
+//
+//   help            what this kernel can be asked
+//   all             every view, in registration order
+//   <name> [arg]    that view, optionally narrowed
+int dbg_command(const char *line, struct sbuf *out);
+
+// Every view, straight to the console. This is what sysrq 'g' runs, and it is
+// the level-0 path from the plan: no process, no filesystem, no client.
+void dbg_dump_all(void);
+
+#define DBG_MAJOR 10

include/defs.h

@@ -59,6 +59,7 @@ int             pciuser_read(struct inode*, uint64, char*, int);
 int             pciuser_write(struct inode*, uint64, char*, int);
 int             pciuser_mmio_ok(uint64 phys, uint64 len);
 void            pciuser_release_all(struct proc*);
+int             pciuser_owner_pid(int idx);
 int             proc_reincarnate(int status);
 void            proc_kill_init(void);
 extern uint     init_generation;
@@ -363,6 +364,23 @@ void            ioapicinit(void);
 
 // dma.c — see include/dma.h for the full contract
 void            dma_init(void*, void*);
+
+// dbg.c -- /dev/dbg, the introspection registry. See include/dbg.h.
+int             dbg_read(struct inode*, uint64, char*, int);
+int             dbg_write(struct inode*, uint64, char*, int);
+
+// klog.c -- the kernel log that outlives the kernel. See include/klog.h.
+void            klog_init(void *base, uint64 bytes);
+void            klog_putc(int c);
+int             klog_read(uint64 off, char *dst, int n);
+uint64          klog_len(void);
+uint64          klog_prev_bytes(void);
+int             klog_recovered(void);
+
+// ksym.c -- naming a kernel address. See docs/plan/debugger.md, D0.
+int             ksym_ready(void);
+const char*     ksym_lookup(uint64 addr, uint64 *off);
+int             ksym_fmt(char *buf, int cap, uint64 addr);
 void           *dma_alloc(uint64 size, uint64 align);
 void            dma_free(void*, uint64 size);
 addr_t          dma_phys(const void*);

include/klog.h

@@ -0,0 +1,44 @@
+#pragma once
+
+#include "types.h"
+
+// The kernel log that outlives the kernel.
+//
+// docs/plan/debugger.md milestone D1. Until this existed, `cprintf` wrote to a
+// serial line and a screen and was then gone: a panic's report could be read
+// only by whoever was watching at the time, and a triple fault left nothing at
+// all. panic.c said so in its own header comment -- *"there is no core dump and
+// no log to go back to"* -- and that sentence is what this deletes.
+//
+// The buffer is a byte ring in a region carved off physical memory *before*
+// kalloc or the DMA arena are given anything, at a fixed distance below
+// PHYSTOP, so its address is a property of the machine rather than of this
+// boot. Nothing allocates it, nothing frees it, and a reboot that leaves DRAM
+// alone leaves it intact -- which is what makes the last words of a crashed
+// kernel readable from the one that comes after.
+
+#define KLOG_BYTES   (128 * 1024)     // ring plus header
+#define KLOG_MAGIC   0x676f4c6bu      // "kLog"
+#define KLOG_VERSION 1
+
+// Kept at the head of the region. Everything in it has to survive a reboot, so
+// it is all fixed-width and there are no pointers: the only thing that says
+// where the data is, is that it follows.
+struct klog_hdr {
+  uint32 magic;
+  uint32 version;
+  uint32 size;          // bytes of data[], = KLOG_BYTES - sizeof(struct klog_hdr)
+  uint32 boot;          // how many kernels have written here
+  uint64 head;          // total bytes ever written; the ring is head mod size
+  uint64 mark;          // head as it stood when this boot started
+  uint32 sum;           // over the fields above -- see klog.c
+  uint32 pad;
+  char   data[];
+};
+
+void   klog_init(void *base, uint64 bytes);
+void   klog_putc(int c);
+int    klog_read(uint64 off, char *dst, int n);
+uint64 klog_len(void);
+uint64 klog_prev_bytes(void);
+int    klog_recovered(void);

include/param.h

@@ -29,7 +29,7 @@
 #define NOFILE       128  // open files per process
 #define NFILE        512  // open files per system
 #define NINODE       200  // maximum number of active i-nodes
-#define NDEV          10  // maximum major device number
+#define NDEV          11  // maximum major device number
 #define RAMDISK_DEV    2  // memory-backed block device (kernel/dev/ramdisk.c)
 #define USBDISK_DEV    3  // USB mass storage (kernel/drivers/usb_storage.c)
 

include/posix.h

@@ -4,10 +4,25 @@
 #include "types.h"
 #include "date.h"
 
+// struct iovec is declared in two headers on purpose, and guarded so that
+// including both is not an error.
+//
+// posix.h has it because readv/writev need it; this file has it because a
+// userspace program including <socket.h> for sendmsg must get a complete
+// struct msghdr without also having to know about a kernel header. Both
+// definitions are identical and both are Linux's layout.
+//
+// The guard is not cosmetic. C23 permits redeclaring a struct with identical
+// members and GCC 15 defaults to C23, so the duplicate was invisible on the
+// gcc path -- while clang defaults to gnu17 and rejected it, which broke the
+// one toolchain shell.nix exists to provide and which the UEFI loader needs.
+#ifndef SCH_IOVEC_DEFINED
+#define SCH_IOVEC_DEFINED
 struct iovec {
     void   *iov_base;
     uint64  iov_len;
 };
+#endif
 
 // Linux's IOV_MAX. readv/writev used to cap iovcnt at 16 -- which is legal,
 // since POSIX only requires 16 -- and returned EINVAL above it. But programs

include/sbuf.h

@@ -0,0 +1,46 @@
+#pragma once
+
+#include "types.h"
+
+// A bounded string builder, because there is no snprintf in this kernel.
+//
+// These lived inside kernel/dev/procfs.c, where they were written, and were
+// static to it. The debugger's introspection registry needs the same thing --
+// a subsystem rendering its own state into a caller's buffer, with no
+// allocation and no way to run off the end -- and the choice was to write a
+// second set or to move this one. See docs/plan/debugger.md, D2.
+//
+// Nothing here can overflow: every writer checks cap, and a full buffer
+// silently drops the rest. That is the right trade for something whose callers
+// are a /proc read and a crash-time dump; a builder that can fail is a builder
+// every caller has to check, and none of them would.
+
+struct sbuf {
+  char *p;
+  int   len;
+  int   cap;
+};
+
+void sb_putc(struct sbuf *sb, char c);
+void sb_puts(struct sbuf *sb, const char *s);
+
+// A string in a fixed-width column, space-padded. Over-long values run past
+// their column rather than being truncated: a misaligned row is easier to read
+// than a mangled name.
+void sb_pad(struct sbuf *sb, const char *s, int width);
+
+// Four lowercase hex digits, zero-padded. PCI and USB identifiers are always
+// written this way, and a lookup table keyed on "8086:100e" does not match
+// "8086:100E" or "8086:10e".
+void sb_puthex4(struct sbuf *sb, uint32 v);
+
+void sb_putu(struct sbuf *sb, uint64 v);
+
+// Zero-padded hex of a given width, for addresses.
+void sb_puthex(struct sbuf *sb, uint64 v, int digits);
+
+// A decimal number in a right-aligned column, so tables of sizes line up.
+void sb_putu_pad(struct sbuf *sb, uint64 v, int width);
+
+// "<label><value> <unit>\n" -- the shape almost every /proc line takes.
+void sb_kv(struct sbuf *sb, const char *label, uint64 v, const char *unit);

include/socket.h

@@ -97,10 +97,25 @@
 // kernel will enforce.
 #define SCM_MAXFD       8
 
+// struct iovec is declared in two headers on purpose, and guarded so that
+// including both is not an error.
+//
+// posix.h has it because readv/writev need it; this file has it because a
+// userspace program including <socket.h> for sendmsg must get a complete
+// struct msghdr without also having to know about a kernel header. Both
+// definitions are identical and both are Linux's layout.
+//
+// The guard is not cosmetic. C23 permits redeclaring a struct with identical
+// members and GCC 15 defaults to C23, so the duplicate was invisible on the
+// gcc path -- while clang defaults to gnu17 and rejected it, which broke the
+// one toolchain shell.nix exists to provide and which the UEFI loader needs.
+#ifndef SCH_IOVEC_DEFINED
+#define SCH_IOVEC_DEFINED
 struct iovec {
   void  *iov_base;
   uint64 iov_len;
 };
+#endif
 
 struct msghdr {
   void         *msg_name;         // struct sockaddr *, or 0