SchOS/docs/architecture/devices.md

# The device model

How hardware gets found, claimed and used, and what the rest of the kernel sees
of it.

Writing a driver is [../guides/adding-a-driver.md](../guides/adding-a-driver.md).
Moving drivers out of the kernel entirely is [../plan/hybrid.md](../plan/hybrid.md).

---

## One list of everything attached

There is one list of everything attached, whatever bus found it:
`include/device.h` and `kernel/dev/device.c`, readable at `/proc/devices`.

```
name      bus       class     driver    device
kbd0      platform  input     ps2kbd    PS/2 keyboard
mouse0    platform  input     ps2mouse  PS/2 mouse
uart0     platform  other     uart8250  16550 serial port
ide0      platform  storage   ide       ATA disk controller
vga0      pci       display   vga       display controller
```

Before this there were two registries in `kernel/drivers/registry.c` — an array
of PCI drivers and an array of USB drivers — with nothing that knew about both.
That is sufficient for *binding* and useless for the three things wanted next.

**Enumeration.** "What is in this machine, and what claimed it" had no answer
covering a USB disk and a PCI display at once. A device manager is exactly that
question.

**Classes.** A compositor should ask for *the display* and not care whether that
is the VBE framebuffer or virtio-gpu. Without a class every consumer hardcodes a
driver, and adding the second driver means editing the consumers — which is how
a framebuffer address ended up hardcoded in three places here once already.

**A boundary for drivers that are not compiled in.** They have to attach
somewhere that is not an array fixed at link time.

Two vocabularies are kept deliberately separate: a device's **bus** is
provenance (`platform`, `pci`, `usb`), its **class** is capability
(`display`, `input`, `storage`, `net`, `bus`). A USB disk and a SATA disk are
both `storage` despite sharing no numbering at all. Where a driver claims a
device, the driver's opinion wins over the descriptor's: `struct usb_driver` has
a `devclass` field separate from the USB interface class, because the descriptor
says what the device *claims* to be and the driver knows what it *made* of it.

It is a flat list with a bus tag, **not** a device tree. Nothing yet needs to
walk a hierarchy, and a tree nobody traverses is just a harder list. Hot-unplug
would need more; the `in_use` flag is the hook.

Platform devices are registered in one place
(`platform_register_devices()` in `registry.c`) rather than inside each driver's
init, for the same reason the driver arrays are written out by hand: a list you
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()` |
| use its ports, if it has an I/O BAR | nothing — `CLAIM` grants them |

Four 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.

The check is against the *pages* a BAR lies in rather than the BAR itself,
because a page is the only granularity an MMU has. A BAR smaller than a page
therefore hands the process the whole page it sits in — forced by the hardware
rather than chosen. Comparing against the BAR's own size instead meant a
sub-page BAR could not be mapped at all, which nothing noticed until an
rtl8139 with 256 bytes of registers turned up; see
[ldls.md](ldls.md), "The bug a foreign driver found in its
first minute".

**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.

Everything in that arena has to be **contiguous**, which is the whole reason it
exists — so the number that matters is not how much is free but how large the
biggest piece is. `dma_alloc()` is therefore best fit rather than first fit: a
64 KB ring taken from the middle of a 16 MB arena leaves two 8 MB extents, and
a framebuffer wanting 9 MB then cannot be had on an arena three quarters empty.
Best fit puts each request in the tightest extent that holds it and leaves the
large ones whole for the requests with no alternative.

**One request is capped at 32 MB**, and the cap is not there to ration memory —
the arena does that, and says so properly. It is there so a wild `size` from a
process cannot ask for the whole arena by accident. It was 4 MB, which is one
framebuffer at 1280x800, chosen when that was the only thing anyone asked for.

That is worth recording because it produced a failure that pointed somewhere
else entirely. virtio-gpu's display size is the size of the *host's window*, so
a user who drags it out to 1920x1080 asks for 8100 KB in one piece — refused by
the cap, on an arena with 61 MB free:

```
vgpud: wanted 7365 KB of DMA memory for a 1920x982 framebuffer
...
65536 KB total, 61847 KB free in 2 extent(s)
```

Every number in the diagnostic was about the arena, and the arena was fine.

A failed allocation reports both numbers for the same reason, because they
point at different fixes — a fragmented arena is cured by whoever holds the
block in the middle letting go, a full one by `DMA_ARENA_BYTES`:

```
dma_alloc: no room for 9216000 bytes -- 12591104 free,
           largest contiguous piece 8495104 (`schdbg dma` for the map)
```

**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).

**Ports come with the claim, and only that device's.** There is no ioctl for
this because there is no decision left to make: a process holding a device with
an I/O BAR gets exactly the ports in that BAR, through the TSS I/O permission
bitmap, and loses them when it releases or exits. Granting it is not optional —
a driver's `outl` is an instruction compiled into it, not a call anything can
intercept — and granting it *coarsely* is not acceptable, because `IOPL=3` is
one flag that hands over the interrupt controller and the disk along with the
NIC. See [../../include/ioperm.h](../../include/ioperm.h).

### 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.

Two things a release has to do beyond quiescing the hardware, both found by
handing over a NIC the kernel was actively using:

- **Mask the line.** The kernel's handler is gone and the incoming driver is
  about to enable the device, so for a while nothing will acknowledge the
  cause. Left unmasked that is an interrupt storm — 450,000 a second, measured.
- **Give up the class device too.** A NIC's `release` calls `net_detach()`, the
  missing half of `net_attach_late()`. An interface left in the stack keeps its
  address and the route to its subnet, so the stack goes on choosing it and
  every frame reaches a `transmit` that now correctly refuses. Nothing reports
  an error. See [ldls.md](ldls.md).

It also **changes the display mode**, on a control socket, with `schmode` as the
client — and that is worth a sentence here because it is the thing the device
model makes possible rather than the thing it does. A modeset is five commands
to the device. In the kernel those five commands are also a reason to be
nervous, because a wrong one takes the machine; in a process the worst case is
that `schinit` starts another one. See
[../plan/hybrid.md](../plan/hybrid.md), "A modeset, from a process".

### Taking it back

A driver that dies is the case this whole arrangement exists for, so release is a
symmetric operation rather than a courtesy. Three things happen that are not
obvious from "the process exited":

**Bus mastering is cleared before the DMA is freed.** A device whose driver has
just died is still writing into memory the kernel is about to hand to somebody
else. The kernel cannot quiesce a device it does not understand — that is a
different register on every chip — but it can clear `PCI_CMD_BUS_MASTER`, which
stops the writes whatever the device is, and it is the only halt available to a
kernel that knows nothing but the header. So `PCIIOC_CLAIM` sets the bit and
release clears it, in that order relative to freeing the memory. `pcitest` prints
the bit in a `bm` column, with a separate mark for "could not read it", because a
failed read rendered as "off" is worse than no column at all.

**DMA memory a driver mapped is not `freevm()`'s to release.** `freevm()` frees
every mapped page below `PHYSTOP` and the DMA arena is the top 16 MB of exactly
that range, so a DMA block left for it went onto the page allocator's free list
while `pciuser_release_all()` handed the same pages back to the arena — two
allocators, one set of pages. `PCIIOC_DMA` records a VMA with `no_free` set, the
same way shared memory does, and `proc_release_shared()` unmaps the range before
the page tables are torn down. The same rule covers every future case: **anything
mapped into a process that the process does not own the pages of needs a VMA, or
exit will free it twice.**

**A device that is the only display will not be released.** `vgpu_release()` asks
`vga_fb_restore()` whether there is a framebuffer to put the console back on, and
declines if the answer is no. The rule that the kernel keeps a minimal driver for
everything on the path to a shell is only worth writing down if something
enforces it.

Coming back is a job, not a kernel feature. `etc/schinit/vgpud.job` carries
`KeepAlive = yes`, so killing the driver is the entire test: `schinitd` starts
another one, it claims the device, and the pid of whichever process drew the
frame is legible in the frame itself. See
[../plan/hybrid.md](../plan/hybrid.md), "The driver came back".

### 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
will be. The user may install one on their own machine, through a device
manager or equivalent, and SchOS will load it.

The licensing reasoning matters and is worth stating exactly, because it is
easy to get wrong in both directions:

- **Distribution is what triggers the GPL.** SchOS is GPL-2.0-or-later, so
  shipping a GPL-2.0-only driver in an image is now *possible* — see
  [../licensing.md](../licensing.md) §6 — but LDLS still does not, by policy. A
  user obtaining a driver themselves and loading it on their own machine is
  their act, not ours, and is not a distribution by us.
- **Implementing a loader is not copying.** Writing support for a module format
  and a driver ABI from published documentation produces our own work. It is a
  clean-room implementation, and it stays one only if it is written from
  documentation rather than transcribed from Linux source. Reading Linux to
  understand *hardware* is fine; translating its code is not, whatever the
  identifiers say.

So the rule for this subsystem is the same as everywhere else in the tree: the
loader is ours and GPL-2.0-or-later, what it loads is the user's business, and
no third-party module enters an image we build. `RAMDISK_EXCLUDE` and `NOTPORTS` are the
existing mechanisms for keeping that true mechanically rather than by intention.

---

## Interrupts

A PCI driver connects its interrupt with one call, `pci_irq_attach()`, and
does not choose how. In order of preference:

1. **MSI**: the device writes a vector to the local APIC. No pin, no routing,
   nothing to share.
2. **MSI-X**, but only if the driver passes `PCI_IRQF_MSIX`. Some parts change
   how they report interrupt causes in that mode; the 82574 needs its IVAR
   programmed, which `e1000` does not do, so it does not ask.
3. **INTx**, on the line named by the device's `INTERRUPT_LINE` register.

MSI comes first because INTx on real hardware is **the wrong pin**.
`INTERRUPT_LINE` holds the number the firmware gave the 8259. In APIC mode the
device is wired to an IOAPIC input that only ACPI's `_PRT` describes, and
reading `_PRT` takes an AML interpreter, which SchOS does not have. Under QEMU
the two numbers happen to agree, which is why this went unnoticed until the
drivers were read with a real board in mind.

INTx is therefore backed by the poller in `kernel/dev/irq.c`:

- A level-triggered line that has had a handler for two seconds and has never
  fired gets its handlers called every tick, from a kernel thread with
  interrupts off.
- A line that **storms** (an idle ISA input configured active-low reads as
  asserted forever) is masked and polled instead of being reported and left
  running.

Every handler already has to cope with being called when its device is idle,
because lines are shared, so a spurious call costs only a register read.
`/proc/interrupts` marks such a line `[polled]`, and an MSI line `msi`.

The vector layout:

| Lines | What they are |
|---|---|
| 0–23 | IOAPIC pins |
| 24–29 | MSI vectors, allocated by `irq_alloc_msi()` |
| 30 | LAPIC error (it was 19, which is a PCI pin on Intel chipsets) |
| 31 | spurious |

Nothing goes as high as vector 64, which is `T_SYSCALL`.

Tested under QEMU q35 with the root filesystem on a USB stick, in three
configurations:

- xHCI and e1000e on MSI.
- MSI disabled and the INTx line deliberately misrouted. xHCI took no
  interrupts at all, the poller carried every transfer, and the root still
  mounted.
- The old INTx path, unchanged on i440fx.

---

## `/dev/random` and `/dev/urandom`

Seeded once at boot, from `RDRAND` where the CPU has it and from the cycle
counter mixed with the wall clock where it does not. A verbose boot says which:

```
random: seeded from RDRAND
```

That is worth a section only because of what it replaced. It was a linear
congruential generator seeded with a **constant**, so every boot produced the
same bytes in the same order — not weak, *the same*. A program asking for a
key, a nonce, a temporary filename or a hash seed got one it shared with every
other SchOS machine that had ever run.

**It is still not a CSPRNG and does not pretend to be.** It is an LCG, re-stirred
from the cycle counter on each byte so two readers do not continue one
sequence. What changed is the property that made it dangerous rather than
merely poor.

## What it does not do

- **It is a flat list, not a device tree.** There is no parent/child nesting,
  only a bus tag. Nothing yet needs to walk a hierarchy, and a tree nobody
  traverses is just a harder list.
- **No hot-plug.** Devices are registered at boot and never removed; the
  `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.
- **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.
- **The kernel does not rebind its own driver.** `PCIIOC_RELEASE`, or the process
  exiting, leaves the interrupt line masked and the in-kernel driver unbound —
  the console stays wherever the release put it. A *supervisor* can start a
  replacement driver, and `schinitd` does; the kernel itself watches for
  nothing.
- **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.