1dd4ba0186
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
116 lines
6.5 KiB
Markdown
116 lines
6.5 KiB
Markdown
# The system, layer by layer
|
|
|
|
What SchOS is today. Everything in this directory is built and running; what is
|
|
merely intended lives in [../plan/](../plan/).
|
|
|
|
---
|
|
|
|
## The names, and what each one covers
|
|
|
|
`uname -s` reports `SchIFT`, the way every Unix reports its kernel rather than
|
|
its distribution.
|
|
|
|
| Layer | Name | What it is |
|
|
|---|---|---|
|
|
| System | **SchOS** | The distribution — kernel, userland, tooling |
|
|
| Kernel | **SchIFT** | Multi-core x86-64 kernel with a modular VFS |
|
|
| Filesystem | **SchFS** | Transactional, copy-on-write, the root filesystem |
|
|
| API | **SchAPI** | The native programming interface — *designed, not built* |
|
|
| Compositor | **Schcom** | Owns the display; v0 runs |
|
|
|
|
Six virtual terminals sit under all of it -- `/dev/tty1`..`tty6`, AltGr+F1..F6
|
|
or `chvt N` --
|
|
each with its own screen, line discipline and foreground process group. See
|
|
[terminals.md](terminals.md).
|
|
|
|
---
|
|
|
|
## The stack, bottom to top
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────┐
|
|
│ toybox mksh zsh musl first-party cmd/ │ userland
|
|
├─────────────────────────────────────────────────┤
|
|
│ vgpud — a driver that is an ordinary process │
|
|
├─────────────────────────────────────────────────┤
|
|
│ schinit — PID 1, job manifests, supervision │
|
|
├─────────────────────────────────────────────────┤
|
|
│ syscall table — Linux numbering, one .inc file │ ← the ABI seam
|
|
╞═════════════════════════════════════════════════╡
|
|
│ VFS │ sockets │ signals │ mmap │ poll │ procfs │
|
|
├──────┴─────────┴─────────┴──────┴──────┴────────┤
|
|
│ SchFS │ lwIP │ vt/gfx │ buffer cache │
|
|
├─────────┴────────┴──────────┴───────────────────┤
|
|
│ device model — class vtables, bus binding │ ← the driver seam
|
|
├─────────────────────────────────────────────────┤
|
|
│ /dev/pci — MMIO, DMA and IRQs to a process │ ← the eviction seam
|
|
├─────────────────────────────────────────────────┤
|
|
│ drivers: xHCI e1000 virtio-gpu VBE IDE PS/2│
|
|
├─────────────────────────────────────────────────┤
|
|
│ scheduler │ paging │ traps │ IRQ │ SMP │ DMA │ SchIFT core
|
|
└─────────────────────────────────────────────────┘
|
|
▲
|
|
UEFI loader (boot/uefi)
|
|
```
|
|
|
|
Three seams matter. Above the **syscall table**, software is ordinary and
|
|
portable — musl and toybox are unmodified. Below the **device model**, a driver
|
|
never names its consumer and a consumer never names a driver. And at
|
|
**`/dev/pci`**, a driver stops having to be in the kernel at all: a process is
|
|
handed a device's registers, DMA memory and interrupts, and the in-kernel driver
|
|
that held it releases it cleanly. `vgpud` is the virtio-gpu driver living out
|
|
there today. See [../plan/hybrid.md](../plan/hybrid.md).
|
|
|
|
---
|
|
|
|
## Where it came from
|
|
|
|
SchOS began as [xv6](https://github.com/mit-pdos/xv6-public) and is now mostly
|
|
something else. What survives from xv6 is the *shape* of the process table, the
|
|
sleep/wakeup discipline, and the buffer cache. What has been replaced: the
|
|
scheduler and trap path (rewritten for x86-64 and for more than one processor),
|
|
the memory manager, the entire filesystem, the syscall layer, and every driver.
|
|
|
|
That inheritance is worth knowing when reading the code, because the parts that
|
|
still look like xv6 follow xv6's conventions and the parts that do not, do not.
|
|
|
|
---
|
|
|
|
## The documents
|
|
|
|
Read in this order if you are new:
|
|
|
|
| | |
|
|
|---|---|
|
|
| [boot.md](boot.md) | Firmware to the first userspace process. The shortest path through the whole system. |
|
|
| [kernel.md](kernel.md) | Memory, processes, scheduling, traps, signals, SMP. |
|
|
| [syscalls.md](syscalls.md) | The one table everything is generated from, and how a musl binary runs unmodified. |
|
|
| [filesystem.md](filesystem.md) | The VFS, the buffer cache, mounts, procfs. |
|
|
| [schfs.md](schfs.md) | The copy-on-write root filesystem. |
|
|
| [devices.md](devices.md) | Buses, classes, binding, and the vtables consumers talk to. |
|
|
| [usb.md](usb.md) | xHCI, the USB core, and the three class drivers. |
|
|
| [graphics.md](graphics.md) | Framebuffer, text rendering, the console, and PSOGM. |
|
|
| [terminals.md](terminals.md) | The six virtual terminals, and the chord that switches them. |
|
|
| [networking.md](networking.md) | NIC drivers, lwIP, and both socket families. |
|
|
| [init.md](init.md) | `schinit`, PID 1 as a role, and the job manifests. |
|
|
| [debugging.md](debugging.md) | Symbols, a log that outlives the kernel, and asking the kernel a question. |
|
|
|
|
---
|
|
|
|
## Three rules that hold across all of it
|
|
|
|
**The kernel and the host tools compile the same SchFS source.** `mkschfs`
|
|
cannot disagree with the kernel about the on-disk format, because there is only
|
|
one implementation. Format bugs are found on the host, where a test takes a
|
|
second instead of a boot.
|
|
|
|
**Syscalls are declared in exactly one place.** `kernel/sys/table.inc`.
|
|
The constants, the dispatch table and the Linux translation map are all
|
|
generated from it, so a syscall cannot be half-registered.
|
|
|
|
**A list you can read beats a list assembled by side effects.** Drivers are
|
|
written out by hand in `kernel/drivers/registry.c` rather than collected by a
|
|
linker section, and platform devices are registered in one function rather than
|
|
inside each driver's init. The tradeoff is deliberate: self-registration is
|
|
nicer to write, and it means the list of what is in your kernel is not written
|
|
down anywhere you can read.
|