Watch

Nexoniarz d3c37f82b6 docs: the tree moved and the documentation did not

The site and several documents still described the system as it was before
virtual terminals, the new schinit, the hybrid work and descriptor passing.

docs/architecture/init.md described the wrong program. It documented a single
schinit that parses manifests and supervises jobs, which has not been true since
PID 1 was split: PID 1 forks a supervisor, spawns jobs on its behalf and reaps;
the job table lives in /proc/schinit; a heartbeat runs both ways; and
proc_reincarnate() re-execs PID 1 in place rather than panicking. Rewritten
around what exists, keeping the reasoning that is still load-bearing -- the five
failures of the sibling-init scheme, the escalation ladder, and the three bugs in
the reincarnation path that each had to happen before they were obvious.

docs/plan/init.md is deleted, which is the tree's own rule for finished work and
had not been applied. Fourteen source comments referenced it by part number, so
they are repointed at the architecture doc by section name rather than left
dangling -- a deleted document nobody notices is worse than a stale one.

docs/architecture/devices.md gained the section it has been missing since
/dev/pci existed: what a driver needs from a kernel, why mmap is checked against
the caller's claims, why DMA is a call and not a mapping, and why the write back
after an interrupt is not optional. Also that a released device does not come
back by itself, which is true and was nowhere.

docs/architecture/networking.md gained a descriptor-passing section, and
docs/architecture/README.md's stack diagram gained the two layers and the third
seam it was missing. "Two seams hold the whole thing together" has not been true
since /dev/pci.

docs/plan/README.md said the hybrid work was deliberately last, on the argument
that an interface with no consumer is wrong in ways nobody can see. The argument
was right; the conclusion was not, and the document now says why it changed --
the alternative to a driver compatibility layer is writing a driver for every
device that exists, and the original objection is answered rather than ignored
because SchOS's own drivers are the consumers.

The site: a Hybrid section with the eviction transcript, cards for virtual
terminals, schinit and drivers outside the kernel, and the numbers remeasured
rather than estimated -- 46,961 lines, 207 syscalls. The boot log in app.js is
from a boot taken today, and the lines are trimmed to what the console can show
without clipping, each still a verbatim prefix of real output.

Two small rendering fixes found by looking at the pages rather than assuming:
.console pre's min-height is now scoped to the hero, so a static transcript sizes
to its content instead of reserving eight lines it does not have; and the docs
reader's contents panel strips inline marks from headings, so a heading written
`proc_reincarnate()` no longer carries its backticks into the sidebar.

Every intra-doc link checked; none broken.

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

2026-09-13 20:05:06 +02:00

8.7 KiB

Raw Blame History

Roadmap — everything else still open

The three current decisions have their own documents; see README.md. This file holds what is left: work that is scoped, agreed and unstarted, with nothing in it that is finished.

Finished work is not here. It moved to ../architecture/ and was rewritten as a description of what it produced — see the rule. What used to be phases 1 through 4 of this file, several hundred lines of ticked boxes, is now usb, networking.md, graphics.md and devices.md over there.

1. Storage and the boot path

Make a USB disk mountable and bootable. The xHCI stack, the bulk-only transport, the SCSI layer and the block device all work — a superblock reads back through bread(). What is missing is that the root device is compiled in rather than selectable, so nothing can be told to mount it.

This is also the first piece of the installer, and it is the single change that would most enlarge what SchOS can boot from.

2. Graphics

A /dev/dri-style device with mode setting, so resolution stops being whatever the loader asked for. This was to be done with hybrid.md's GPU eviction, and that eviction has now happened — cmd/vgpud drives virtio-gpu from userspace. The modeset API is the next thing it makes affordable, and is milestone H3 over there rather than here.
Double buffering and vblank. display_ops specifies both and no driver implements either. Schcom needs both to not tear.
Port the console onto the text layer and delete the cell grid. The layer exists, the rasteriser exists, and the console still indexes font_data[256][16].
Load a font from disk and point the console at it.
CFF/Type 2 charstrings, so OTF fonts work. A separate font_ops provider and a bytecode interpreter, not an extension of the glyf path.
Text layout — advance widths, kerning — as a library in lib/, so the terminal and the file manager are not each solving it.

The console keeps its fixed grid until the first item above; proportional text belongs to the GUI.

3. Networking

Two things the stack owed on the day it landed, both still owed:

accept() does not report the peer's address, and there is no getsockname/getpeername. Nothing has needed them yet; a server that wants to log who connected will.
No routing table. With two interfaces up, the first is the default route and the second is reachable only by an address on its own subnet. That is a rule rather than an accident, and it is not routing.

Two that were on this list are now done and described in ../architecture/networking.md: setsockopt honours six options and refuses the rest, and sendmsg/recvmsg carry SCM_RIGHTS. A third is closer than it was — toybox's ping needed recvmsg and IP_RECVTTL, and only the second is still missing.

4. The interactive crash screen

PSOGM renders and stops. The idea is a small OS inside the crash, and the framing decides the design:

At panic time the kernel is the only thing running, which is exactly why it can offer what a live system cannot: walk the stack, read another process's memory, dump page tables, inspect the process table — with no scheduler and no locking to respect, because nothing else can race you.

What makes it a system rather than a print statement is that it keeps the base machine's drivers. Concretely, the ones that work with interrupts off: the framebuffer (gfx_draw_pixel is a plain memory write), the PS/2 keyboard (pollable via ports 0x60/0x64), and the serial port. Those three are a complete console.

Everything else — IDE, USB, the timer, anything that sleeps or takes a sleeplock — is off limits, because the lock it needs may be precisely the one held by the CPU that just died.

So the shape is a polled event loop over preallocated state: no kalloc, no sleep/wakeup, no acquire on anything a live path might hold, one static command buffer, and that driver set. That restriction is not a limitation to work around later; it is the invariant that makes the mode trustworthy when everything else is not. Anything wanting more should be answered by rebooting into a recovery environment.

A useful precedent to read but not copy: DDB, the BSD in-kernel debugger, is exactly this, and its hard-won rule is the same one — a debugger that can deadlock is worse than no debugger.

5. The installer and `.sip`

Scoped in projects/schinst/README.md, which holds the detail. In short:

.sip format specification, written down before any code
tools/mksip — capture a directory tree into a package
The apply path
An installation environment that boots from the ISO, partitions, applies the .sip, and installs the loader

.sip is modelled on WIM, and the thing worth copying from WIM is that it is file-based, not block-based: one file holds a whole filesystem, applies to a partition of any size, and several images can share their common files.

Most of this already exists. tools/mkschfs.c and tools/mkfs.c both do content dedup with an (st_dev, st_ino) fast path, and SchFS's B-tree is content addressed. mksip should share that code rather than reimplement it — that is the reason the dedup was factored the way it was.

Open questions, all wanting a decision before code:

Compression. Something with a small decompressor is worth more than something with a good ratio, because the decompressor runs in the installation environment.
Multiple images per .sip — WIM's real trick, install/recovery/boot sharing one blob store. Worth the complexity now, or not?
Can the kernel mount a .sip read-only directly? It is close to a filesystem already, and if it can, the installation environment's root can simply be the .sip.

The GUI for this is a Wayland client; see wayland.md.

6. SchFS beyond SchOS

In the order they should happen.

~~An on-disk format version~~, and an upgrade path. The version policy is done — see ../architecture/schfs.md. What remains is the upgrade step, and it cannot be written until there are two formats to convert between; the first bump is when that becomes real work rather than speculation.

The format is now pinned, which is what the other two items were waiting on.

A Linux implementation, FUSE first. Three reasons in order of weight: it can be tested with fsx and xfstests, which are far harsher than anything written alongside the code; it carries no licence entanglement, since libfuse is LGPL and used across a process boundary; and it can reuse the read/write logic already in tools/mkschfs and tools/schfs_fsck rather than being written twice and having the two disagree.

A kernel module is a different project, comes only after FUSE passes xfstests, and carries the licence problem ../licensing.md describes.

The missing features, listed honestly before adding any: no journal replay across an unclean shutdown beyond what copy-on-write gives for free, no snapshots, no sparse-file support, and no online fsck. Snapshots are the one where the existing design already pays for most of the cost — the B-tree is copy-on-write, which is most of the machinery; nothing takes or names a snapshot.

7. The kernel's own gaps

Not phases, and each one improves everything above it:

A slab or pool allocator. kalloc hands out one page at a time, and every subsystem written since has invented its own fixed-size table to work around that. This is the single change that would most improve the rest of the kernel.
A page cache, which is what a general writable MAP_SHARED needs. foundations.md delivers a memfd instead, which is narrower and sufficient for the GUI.
Symlinks in procfs, so /proc/<pid>/exe can be one and ps -o comm stops printing [init]. Belongs with the rest of the VFS work rather than on its own.
The ls -lR hang — not reproducible, and kept here because the absence of a result is a result. Instrumented and hunted at length; see Gate 0 of 1.0.md. Two real defects were found on the way and fixed, neither proven to be the cause.
No garbage collector for descriptors in flight. An AF_UNIX socket passed over itself and never received leaks the pair. Bounded at thirty-two sockets, and nothing in the tree does it — but a third-party program could.

Kept out of scope on purpose

Anything that needs pushing or publishing. This work stays local.
TrueType hinting.
XWayland.

8.7 KiB Raw Blame History