Module driver 

Device-neutral mechanisms for drivers (docs/driver-library.md). Not gated on the host test build: its pure arithmetic is unit-tested there, and the SDK-dependent half gates itself. gs::driver - the device-neutral mechanisms a driver is built from.

What belongs here, and what never does

A driver describes a device. This module holds what is left when the device is taken away: the mechanisms every driver needs and no driver should have to reinvent. The question that decides membership is the one docs/driver-library.md opens with - does this part describe the device, or a reusable Godspeed mechanism? A register sequence, a command set, a firmware’s quirks and a chip’s recovery dance describe the device and stay in its driver. How long to wait for a register, how to say the wait gave up, how long to hold still when no register can say, and how to wait for an interrupt without losing a request, describe neither - so they are here (wait, delay, irq). So are the two grants a driver names: its register window (registers) and its DMA arena, laid out by name (arena). And so are the calls a driver made to the SDK for what its grants carry with them: the input it hands the console (input), its device’s power (power), and what the kernel knows about the device that the driver cannot read for itself (device) - each the SDK’s own call, so that a driver is written on this module and nothing beside it (step 5). And a device that has no registers of its own, because it is on a bus whose host owns them - a USB device - is reached through that host (bus), as a bus and never as a class: it moves transfers and knows nothing of what the device is.

There are no device CLASSES here, and there will not be. No driver::wifi, driver::audio or driver::usb: a class API is a guess about what every device of that kind will need, made before most of them exist. A family of devices that genuinely shares a protocol gets a domain library of its own outside the standard library (sdk/wifi is the first), built on this module.

How a mechanism gets in

By being REPEATED, not by being imagined. Each module here was found written out by hand in more than one driver, differently each time, and then moved here and the drivers converted to it. irq was built from xhci, ehci and dwc2, tested by the two audio drivers, and since 2026-10-22 is the wait of all five. (input, power and device are the exception, recorded in step 5: each is one SDK call a driver must name, wrapped, not a mechanism found written out.) A second, independent kind of driver using it naturally is the test of whether it is general; one that has to be bent to fit it means the abstraction is shaped like the driver it came from.

Unsafe

None, as everywhere in this crate (#![deny(unsafe_code)]). A driver that seems to need unsafe is asking a question - which safe mechanism is missing from here? - and the answer belongs in this module or the SDK’s audited layer (CLAUDE.md 18.1), never in the driver.

What it does not change

The kernel. Nothing here is a new kernel responsibility or a new syscall; these are the mechanisms the kernel already offers, put in the one shape a driver should reach for.

Re-exports

pub use arena::arena;

pub use arena::Arena;

pub use arena::Layout;

pub use arena::Part;

pub use registers::registers;

pub use registers::Registers;

Modules

arena

A driver’s ARENA: the memory its device reads and writes, granted at spawn, and laid out by name.

bus

bus - a device a driver reaches through the host of the bus it is on, not through registers of its own.

delay

Holding still for a set time, waiting for nothing.

device

What the kernel knows about a driver’s DEVICE that the driver cannot read for itself.

input

A driver’s INPUT: handing what the user typed to the console, and saying input is up.

irq

Waiting for a device’s INTERRUPT - and for requests, on the same endpoint, without losing one.

power

A driver’s POWER: cutting and restoring the power of the device it was granted.

registers

A driver’s REGISTERS: the window onto its device that the kernel granted at spawn.

wait

Waiting for hardware, bounded by the CLOCK.