godspeed/driver/

mod.rs

// SPDX-License-Identifier: Apache-2.0
//! `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.

pub mod arena;
// A device reached through its bus's host, not registers of its own: a USB device's transfers (2026-10-23).
#[cfg(not(test))]
pub mod bus;
pub mod delay;
pub mod device;
pub mod input;
pub mod irq;
pub mod power;
pub mod registers;
pub mod wait;

// The two grants a driver names and relies on (step 3, 2026-10-19): its device's registers and its DMA
// arena, taken at the top of a driver, so they are here rather than a module down.
#[cfg(not(test))]
pub use arena::{arena, Arena, Layout, Part};
#[cfg(not(test))]
pub use registers::{registers, Registers};