docs: audit all 'what's next' sections against the code; fix stale comments

Verified every deferred item in the nine docs with a what's-next section and
marked what has since landed (reaper, per-process CR3, higher-half kernel,
kernel heap, contiguous frame alloc, RSDP capture, cap-passing, driver restart
with backoff, PS/2 keyboard) while keeping the genuinely open items. Also
corrects interrupts.md's claim that the keyboard skipped the IO-APIC, and
updates scheduler.zig/heap.zig comments that predated the reaper and the big
kernel lock.
This commit is contained in:
Daniel Samson
2026-07-22 02:23:51 +01:00
parent a081f69def
commit 52df2ba6f6
11 changed files with 98 additions and 77 deletions
+15 -15
View File
@@ -358,21 +358,21 @@ is **port I/O** (`io_read`/`io_write`, the claim-gated syscalls that make a PS/2
driver possible). What's left is IOMMU *enforcement* (per-device domains — it waits on
the first DMA driver to protect and test against) and these smaller items:
- **Releasing a claim.** There is no `dev_release`, and `devices_broker` never drops a claim on
exit — only IRQ bindings are released. A dead driver's device stays owned forever,
which blocks restart.
- **Unregistering children.** `device_register` only appends. A USB device that is
unplugged cannot be removed, and a bus driver in a loop can exhaust the 64-entry
table.
- **Restart.** A supervisor that *spawns* drivers now exists — the device-manager starts
them with `system_spawn` — but a supervisor that *restarts* them does not. A driver that
dies should release its claim, have its device quiesced, and be respawned; today nothing
notices the death. Some pieces (`releaseIrqs`, `device_grant` teardown, the claim table)
exist, and `dev_release` (below) is the missing mechanism; the restart policy is the
resilience track ([resilience.md](resilience.md)).
- **Interrupt priority / threaded IRQ latency.** `notifyFromIsr` enqueues the woken
driver but doesn't preempt (`wakeLocked` deliberately leaves that to the caller), so
a woken driver waits for the next scheduling point.
- **Releasing a claim** — half done. The kernel now drops *all* of a dead driver's
claims on every path out of a process (`releaseAllOwnedBy`, called from process
teardown), which unblocked restart. A voluntary `dev_release` for a live driver
still doesn't exist.
- **Unregistering children** — half done. Hot-remove works at the manager layer:
the xHCI bus reports `child_removed` on unplug and the device manager prunes its
tree. The kernel's own device table is still append-only, so a bus driver in a
loop can still exhaust the 64-entry table.
- **Restart** — done. The device manager notices a driver's death, reads its exit
reason, prunes the children it reported, and respawns it with exponential
backoff — with a crash-loop cap that marks a repeat offender `failed` instead
of respawning forever ([device-manager.md](device-manager.md)).
- **Interrupt priority / threaded IRQ latency** — still open. `notifyFromIsr`
enqueues the woken driver but doesn't preempt (`wakeLocked` deliberately leaves
that to the caller), so a woken driver waits for the next scheduling point.
## The driver contract (M17–M18)