docs: establishment planes — the design and the two-seam plan

The namespace holds protocols, never instances; what multiplies is provider
processes, and their establishment routes through the device manager, which
owns the topology. communication.md gets the model; the plan converts the
usb-transfer and block seams in one flag-day, closes the restart-zombie hole
the scoping found, and pins the three-controller mouse bug as a QEMU case.
This commit is contained in:
Daniel Samson
2026-08-09 11:26:53 +01:00
parent 5930c9653c
commit 0d5a7394ef
2 changed files with 156 additions and 1 deletions
+34 -1
View File
@@ -55,7 +55,40 @@ source/destination addressing internally at L0 — the way IP runs under TCP —
and none of it surfaces into the packet header. Protocols stay ignorant of
distance.
## The transport (L0): a buffer and a doorbell
## Establishment: two planes, one namespace
`target` routes objects *within* a provider. It cannot route *between* provider
processes, because "who am I talking to" was decided at establishment — so when a
protocol's objects live in several processes, something must resolve establishment
to the right one. A real machine forced the question: three xHCI controllers,
three `usb-xhci-bus` processes, one `usb-transfer` name, and whichever instance
bound first owned every class driver's discovery — a mouse on the second
controller was unreachable (`could not open device 50`). The registry's exclusive
bind was built for parties that are genuinely singular; per-device driver
processes are deliberately *not* singular — one process per device found is what
makes a single driver recompilable and restartable while the machine runs.
So establishment has two planes, and the namespace stays instance-free on both:
- **Applications establish by name.** `/protocol/input`, `/protocol/display`,
`/protocol/ufs` — served by *services*, the layer that aggregates
(driver-model.md: services face applications). These are genuinely singular,
the registry's exclusive bind is correct for them, and multiplicity behind
them is `target`'s job. Ten mice still merge into one `/protocol/input`.
- **Drivers establish by topology.** A driver instance *creates its channel* —
its own endpoint — and hands it up in the `hello` it already sends, as a
capability. The device manager is the establishment router for the device
tree because it already owns the routing fact: it knows which instance
reported which child. A consumer's `hello` for device N returns a capability
to N's provider. The name `usb-transfer` names the *contract*; no process
binds it.
Establishment is always a synchronous call, and always consumer-initiated: the
kernel carries one capability in each direction of a call (request and reply),
and deliberately none on a push — a provider cannot foist a channel on anyone.
Re-establishment after a provider restart is therefore also consumer-initiated:
the consumer's channel dies with the provider, and a fresh `hello` fetches the
successor's.
Strip any transport to its skeleton and the same two parts remain: