nexoniarz/SchOS
nexoniarz/SchOS
Watch
1
0
Fork
You've already forked SchOS
 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

docs: the tree moved and the documentation did not

Browse source 
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
This commit is contained in:
Nexoniarz 2026-09-13 20:05:06 +02:00
commit d3c37f82b6
21 changed files with 548 additions and 336 deletions
Download patch file Download diff file Expand all files Collapse all files

28
docs/architecture/README.md
View file

@ -29,7 +29,9 @@ each with its own screen, line discipline and foreground process group. See
```
┌─────────────────────────────────────────────────┐
│ toybox mksh musl first-party cmd/ │ userland
│ toybox mksh zsh musl first-party cmd/ │ userland
├─────────────────────────────────────────────────┤
│ vgpud — a driver that is an ordinary process │
├─────────────────────────────────────────────────┤
│ schinit — PID 1, job manifests, supervision │
├─────────────────────────────────────────────────┤
@ -37,11 +39,13 @@ each with its own screen, line discipline and foreground process group. See
╞═════════════════════════════════════════════════╡
│ VFS │ sockets │ signals │ mmap │ poll │ procfs │
├──────┴─────────┴─────────┴──────┴──────┴────────┤
│ SchFS │ lwIP │ text/gfx │ buffer cache │
├─────────┴────────┴────────────┴─────────────────┤
│ device model — class vtables, bus binding │
│ SchFS │ lwIP │ vt/gfx │ buffer cache │
├─────────┴────────┴──────────┴───────────────────┤
│ device model — class vtables, bus binding │ ← the driver seam
├─────────────────────────────────────────────────┤
│ drivers: xHCI e1000 virtio-gpu VBE IDE PS/2│
│ /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
└─────────────────────────────────────────────────┘
@ -49,10 +53,13 @@ each with its own screen, line discipline and foreground process group. See
UEFI loader (boot/uefi)
```
The two seams that matter are the syscall table and the device model. Above the
first, software is ordinary and portable — musl and toybox are unmodified.
Below the second, a driver never names its consumer and a consumer never names a
driver.
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).
---
@ -83,8 +90,9 @@ Read in this order if you are new:
| [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` and the job manifests. |
| [init.md](init.md) | `schinit`, PID 1 as a role, and the job manifests. |
---

80
docs/architecture/devices.md
View file

@ -57,6 +57,75 @@ can read beats a list assembled by side effects.
---
## Drivers that are not in the kernel
`/dev/pci` (major 9) hands a PCI device to a process. It is deliberately about
*PCI devices* and not about any driver model, and its first users are SchOS's
own drivers, evicted one at a time — which is the ordering that keeps it a
general mechanism rather than a hole shaped like something foreign.
What a driver needs from a kernel, and all it needs:
| | |
|---|---|
| find its device, and read what the bus says | `PCIIOC_INFO`, `PCIIOC_CFG` |
| be given it, exclusively | `PCIIOC_CLAIM` |
| reach its registers | `mmap`, where the offset is a BAR's physical address |
| memory it can hand to the device | `PCIIOC_DMA` |
| be told when the device wants attention | `PCIIOC_IRQ`, then `read()` |
Three of those are worth expanding on, because each encodes a decision:
**`mmap` is checked against the caller's claims.** An offset that is not inside
a BAR of a device this process holds is refused. That is the whole difference
between this and `/dev/mem` with extra steps.
**DMA is a call, not a mapping.** The process is told the *physical* address,
which is precisely what it cannot work out for itself, and the memory comes from
an arena reserved at boot before the general allocator gets anything.
**Interrupts arrive by `read()`**, the way Linux's uio does it and for the same
reason: a descriptor composes with `poll`, and a driver that stops reading falls
behind rather than losing events. The kernel masks the line when the interrupt
arrives and leaves it masked until the driver `write()`s back. **That write is
not optional.** A PCI interrupt is level-triggered — it stays asserted until the
cause is cleared *at the device*, which is a different register on every chip and
therefore something only the driver can do. Signal EOI on a line that is still
asserted and it re-fires immediately, for ever. That is not hypothetical: it
happened here at 72,000 interrupts a second, and what it looked like from
userspace was a clock running seven times slow. See §13 of
[../history/kernel.md](../history/kernel.md).
### Handing a device over
`struct pci_driver` has a `release` hook. A driver that does not define one keeps
its device — always safe, and for anything on the path to a shell also correct.
A driver that does define one has to give back everything, not just the device:
the first eviction found this the hard way, because releasing the GPU while
keeping its 4 MB framebuffer meant the incoming driver was told there was no DMA
memory left.
`cmd/vgpud` is the virtio-gpu driver as an ordinary process. It does the whole
virtio 1.0 bring-up from outside — reset, feature negotiation, a virtqueue in DMA
memory, `SET_SCANOUT`, transfer and flush — and while it owns the GPU the kernel
console falls back to the VBE framebuffer.
**No syscall on that path knows it is talking about a GPU.** The kernel hands
over a PCI device; the process decides what it is.
### What this is not
**It is not a security boundary.** There is no IOMMU, so a process holding a DMA
buffer can point the device at any physical address. This isolates a driver
against its own *bugs* and not against its own *intent* — a crashed driver that
restarts instead of taking the machine down is the entire benefit, and it is
worth having on those terms. [../plan/hybrid.md](../plan/hybrid.md) says so at
length.
**One device per process.** A driver drives one thing; if you need two, run two.
---
## Linux drivers
**Decided 2026-08-08.** Linux drivers are not shipped with SchOS and never
@ -96,9 +165,14 @@ existing mechanisms for keeping that true mechanically rather than by intention.
`in_use` flag is the hook a hot-unplug path would need, and nothing sets it
for that purpose.
- **`NDEVICE` is 32**, compile-time, like every other table in the kernel.
- **Drivers are fixed at link time.** There is no module loader, and nothing can
be installed after the build — the class vtable is the attachment point a
loader would use, and it is the only part that exists.
- **In-kernel drivers are fixed at link time.** There is no module loader, and
nothing can be added to the kernel after the build. A driver *outside* the
kernel is an ordinary program and can be started whenever — but it reaches its
device through `/dev/pci` and publishes nothing to the class vtables, so the
console cannot be handed to one yet.
- **A released device does not come back by itself.** `PCIIOC_RELEASE`, or the
process exiting, leaves the interrupt line masked and the in-kernel driver
unbound. Something has to start a replacement; nothing watches for one.
- **Only two class vtables are defined**: `display_ops` and `netdev_ops`.
Storage and input devices appear in the list with `ops = 0` and are reached
through their own subsystems instead.

237
docs/architecture/init.md
View file

@ -1,7 +1,166 @@
# `schinit` — PID 1
# `schinit` — PID 1 as a role
Shaped after launchd rather than sysvinit. The reason is not the configuration
format.
Shaped after launchd rather than sysvinit, and it breaks one Unix rule on
purpose.
---
## The rule that was changed
Unix's rule is *PID 1 is special and must never die*. Every init since 1975 has
honoured it by being careful.
> **SchOS's rule instead: PID 1 is a role. The kernel guarantees the role is
> filled. The role's state lives outside whichever process currently holds it.**
"Must never die" is not a mechanism — it is a hope, and the thing it hopes about
is the one program on the machine with no supervisor. What replaced it is four
pieces: a split by role, state in `/proc`, a heartbeat, and a kernel that
re-execs PID 1 in place instead of panicking.
### The arrangement it is not
The obvious design — init 1 starts init 2; if init 1 dies, init 2 revives it —
was tried on paper and rejected. The failures are worth keeping, because they are
the traps any redundant-supervisor scheme falls into:
- **It defends against an attack that already fails.** Userspace cannot kill
PID 1 here: `init_ignores()` drops `SIGKILL` to `initproc`.
- **Init 2 is the same binary.** If init 1 died of its own bug, init 2 reaches
the same line and dies the same way — *faster*, having just watched the input
that caused it.
- **The chain has no bound.** Init 2 makes init 3 by symmetry. With a cap, the
cap is the real design and the chain is decoration.
- **Two supervisors is split brain.** Both hold the job table, both see a pid
exit, both restart it. Now the console shell exists twice, both reading
`/dev/console`. That is worse than no redundancy: it corrupts the state it was
added to protect.
- **It only detects death.** The common way an init breaks is *hanging*, and
`wait()` never returns for a process that is merely stuck. The scheme is armed
against the rare failure and blind to the likely one.
---
## The split
| | |
|---|---|
| **`schinit`** (PID 1) | Reaps children, holds the job table in memory, supervises exactly one child. No manifest parsing, no filesystem walking after boot, no allocation. About 520 lines. Its entire job is to be too boring to fail. |
| **`schinitd`** (PID 2) | Manifests, respawn policy, backoff, socket sections, and the eventual `schinitctl`. This is where the bugs will be, and it is restartable. |
The detail that makes this work, and that two copies of one program cannot have:
> **Jobs are forked by PID 1, not by `schinitd`.** `schinitd` decides and asks;
> PID 1 acts. Every job on the machine is a child of PID 1 at all times, so
> `schinitd` crashing orphans nothing, reparents nothing and restarts nothing. It
> comes back, reads the state, and finds the world exactly as it left it.
So there are still two processes with one watching the other — but their roles
are *different*, which is what stops the second being a second copy of the first
one's bug.
### The protocol
`include/schinit.h`. **Every message is exactly one struct**, and PID 1 reads
`sizeof(struct)` or nothing: no length prefix to get wrong, no partial-message
state machine, and no allocation in the process that must not fail. The socket is
a `socketpair` inherited as fd 3.
| To PID 1 | | To the supervisor | |
|---|---|---|---|
| `HELLO` | version handshake | `WELCOME` | PID 1's version, echoed |
| `SPAWN` | start this job | `SPAWNED` | the pid, or negative |
| `PONG` | answer to a ping | `EXITED` | a child was reaped |
| | | `PING` | answer within the deadline |
---
## State outside the process
`/proc/schinit` is the serialised job table: a generation, the supervisor's pid,
then one line per running job — cookie, pid, start tick, label.
It is **written by PID 1**, because PID 1 is the process that cannot lose it, and
written whenever the table changes rather than generated on read — a procfs
generator runs in the kernel, and the kernel has no business walking this
program's memory.
procfs rather than a file on disk for four reasons: it survives a read-only root,
it survives a full disk, it costs no I/O, and it is already the pattern this
kernel uses for exactly this kind of question.
A resurrected supervisor reads it back and adopts what is already running instead
of starting it again. The side benefit is that the job table is no longer
invisible: `cat /proc/schinit` is the observation.
---
## The heartbeat
PID 1 pings the supervisor every 2 seconds and expects an answer within 10. This
is the failure the sibling-init scheme cannot see: a supervisor that is *stuck*
rather than dead never causes a `wait()` to return.
Silence from `schinitd` means PID 1 replaces it — **without waiting for the
corpse**, because `kill()` on a wedged process never completes and PID 1 waiting
for it would be the hang it was trying to detect.
Silence from PID 1 is what the kernel change exists for.
---
## `proc_reincarnate()`
`exit()` on `initproc` used to `panic("init exiting")`. Now the kernel tears down
the address space, keeps the `struct proc`, keeps **pid 1**, and re-execs
`/bin/schinit` in place with a generation counter passed in.
No init 2, no init 3, and no reparenting problem — **because pid 1 never stops
being pid 1**. Every orphan the kernel already reparented to `initproc` is still
correctly parented, `initproc` is still the pointer it always was, the children
survive, and the state is in `/proc/schinit`.
Three details in that path are not obvious and each was a bug first:
- **`exec()` returns 0 on success.** It does not fail to return, so the code
after it is the *success* path, not an error path to panic in.
- **`killed` has to be cleared first**, or the new image exits before its first
instruction — five generations in microseconds.
- **`exec` preserves descriptors**, so the new PID 1 inherits the old
supervisor's socket and never sees the hangup that tells it the supervisor is
gone. It has to be closed deliberately.
### The escalation ladder
| Generation | What happens |
|---|---|
| 1 | Normal boot. |
| 2–3 | Re-exec in place. Log it, keep the jobs, carry on. |
| 4 | Re-exec, but ignore `/etc/schinit` entirely and start only a console shell. **A manifest that kills init must not kill it forever.** |
| 5 | Stop. `panic()`. |
The last row is the honest one. A machine that cannot hold PID 1 up five times is
not a machine that should keep trying, and PSOGM renders a stop code, a call
chain and a QR code of the whole report — a far better end than a silent loop.
### Both paths are tested by doing them, not by reasoning
Two `sysrq` keys exist for this:
| | |
|---|---|
| `sysrq i` | Kills PID 1. Signals cannot — `init_ignores()` drops them — so this sets `killed` directly, which is the kernel deciding rather than userspace asking. |
| `sysrq w` | Wedges `schinitd` on purpose, so the heartbeat timeout is exercised. There is no way back from it; reboot afterwards. |
```
init: pid 1 exited with status 9 -- reincarnating, generation 2
schinit: reclaimed 2 running job(s) from /proc/schinit
schinit: SchOS process 1, generation 2 (reincarnated)
schinitd: adopting os.schos.console-shell
schinitd: adopting os.schos.tty2-shell
```
The shell being typed into keeps its pid across the death and rebirth of PID 1.
---
@ -14,16 +173,15 @@ That inverts the dependency graph. A job stops needing to declare what must be
running before it, because the thing it depends on answers on first use — and
runlevels stop being a concept at all.
SchOS has the two pieces that makes possible: `AF_UNIX` sockets and a real
`/proc`. **This milestone is the supervisor; demand launching is the next one.**
Socket sections are parsed and remembered but not yet held.
SchOS has the two pieces that make it possible: `AF_UNIX` sockets and a real
`/proc`. Socket sections are parsed and remembered but not yet held, so this is
still the reason for the shape rather than a feature of it.
## Constraints on the program itself
## Constraints on the programs themselves
`cmd/schinit/main.c` links against `lib/`, which is raw syscall stubs. **There is
no libc here** — no `malloc`, no `printf`, no `strlen`. Everything is static
storage and hand-rolled, which is also why the limits are constants rather than
growable:
Both link against `lib/`, which is raw syscall stubs. **There is no libc here** —
no `malloc`, no `printf`, no `strlen`. Everything is static storage and
hand-rolled, which is also why the limits are constants rather than growable:
| | |
|---|---|
@ -57,9 +215,9 @@ entirely.
## Job manifests
Every `*.job` file in `/etc/schinit` is loaded at boot, found with `getdents64`
rather than a hardcoded list — so dropping a file in the directory is all it
takes to add a job.
Held by `schinitd`, not by PID 1. Every `*.job` file in `/etc/schinit` is loaded
at boot, found with `getdents64` rather than a hardcoded list — so dropping a
file in the directory is all it takes to add a job.
Sectioned `key = value`, `#` starts a comment, keys are case-insensitive
(a manifest may say `KeepAlive`, `keepalive` or `KEEPALIVE`; keys are for humans
@ -89,14 +247,14 @@ the rest of the system through a shared controlling terminal.
That is exactly what makes `ControllingTerminal` necessary, and the interaction
is the least obvious thing in the program:
> A fresh session has no controlling terminal, and the console only delivers
> input to the foreground process group it is tracking. Without
> A fresh session has no controlling terminal, and a terminal only delivers input
> to the foreground process group it is tracking. Without
> `ControllingTerminal = yes`, the shell comes up, echoes every keystroke through
> the line discipline, and executes none of them — which looks like a hung shell
> and is really a terminal that is not listening to it.
It is **off by default**. A daemon has no business seizing the console, and
launchd's model is that the console is something a job asks for.
It is **off by default**. A daemon has no business seizing a terminal, and
launchd's model is that the terminal is something a job asks for.
`exec.c` enables the Linux ABI automatically for musl binaries, so a job must
not call `enable_linux_abi()` itself — it would renumber the syscalls the child
@ -104,36 +262,24 @@ still has to make.
## Supervision
One loop around `wait()`.
PID 1 loops on `wait()` and reports every reaped pid to the supervisor.
**It reaps whatever exited, including processes reparented here when their own
parent died.** Those are not jobs, `job_by_pid` returns 0 for them, and that is
the whole handling they need.
parent died.** Those are not jobs, and that is the whole handling they need.
A `KeepAlive` job is restarted, subject to `ThrottleInterval` — a job that exits
immediately and forever would otherwise spin the machine. launchd defaults to
10 seconds; 1 is enough here, where the common case is a shell someone just
exited on purpose and expects back.
When `wait()` returns -1 there is nothing left to wait for, which should not
happen while any job is alive. It sleeps rather than spinning, so a mistake
there costs an idle machine and not a hot CPU.
A `KeepAlive` job is restarted by the supervisor asking PID 1 to spawn it again,
subject to `ThrottleInterval` — a job that exits immediately and forever would
otherwise spin the machine. launchd defaults to 10 seconds; 1 is enough here,
where the common case is a shell someone just exited on purpose and expects back.
## The fallback
With no manifests found, schinit says so and starts `/bin/sh` on the console
anyway.
With no manifests found, the supervisor says so and starts `/bin/sh` on the
console anyway.
> An unbootable-looking machine because a manifest was missing would be a poor
> trade for purity.
## PID 1 cannot be killed
Enforced in the kernel, not here. `init_ignores()` discards any signal whose
disposition is the default action when the target is PID 1, **including
`SIGKILL`** — see [kernel.md](kernel.md#signals) for why Ctrl-C is the input that
finds that window. A handler init did install is still delivered.
---
## What it does not do
@ -141,15 +287,18 @@ finds that window. A handler init did install is still delivered.
- **Socket activation is not implemented.** The manifest key is parsed and the
path remembered; nothing holds the socket, so demand launching — the entire
reason for copying launchd — does not happen yet.
- **No `schinitctl`.** Jobs cannot be started, stopped, reloaded or inspected at
runtime. The only interface is rebooting with a different manifest.
- **The job table is invisible.** Nothing reports what is loaded, what is
running, or how many times something has respawned.
- **No `schinitctl`.** Jobs cannot be started, stopped or reloaded at runtime.
They can now be *inspected*, through `/proc/schinit`, which is half of it.
- **No dependency ordering of any kind**, deliberately — demand launching is
meant to make it unnecessary, and until that exists there is nothing in its
place either.
- **No log capture.** `StandardOut` is a path, so a job's output goes wherever
the manifest says and nothing aggregates it.
- **A crash in schinit is fatal to the machine**, because `exit()` panics on
initproc. Fixing that is [../plan/init.md](../plan/init.md).
- **`/proc/schinit` records running jobs, not the whole table.** A job that is
loaded and stopped is not in it, so a resurrected supervisor learns what is
alive and re-reads the manifests for everything else.
- **A new compatibility surface exists between PID 1 and PID 2** that did not
before, and the tree's own [../plan/schapi.md](../plan/schapi.md) §3 spends a
section warning about exactly those. `SCHINIT_PROTO` is versioned in the
handshake, which is the least that can be done about it.
- **32 jobs, 16 arguments, 4 KB manifests**, all compile-time.