Repository navigation
Description
Implement the infrastructure for userspace device drivers. Depends on IOMMU support (must be complete before Phase 6).
See the full design in plans/device-driver-model.md.
Summary
Driver binaries are self-describing via named ELF sections (.panda_devices.pci, .panda_devices.usb, etc.). The service manager scans driver binaries from the initrd and root filesystem, subscribes to device events on their behalf, and spawns them lazily when matching devices appear. Drivers subscribe to device events, receive a one-time-use token when a device is added, claim the device using that token, then access hardware via DEVICE_MAP_MMIO, DMA_ALLOC, and DEVICE_SUBSCRIBE_IRQ. Hot-plug is the default case — boot-time enumeration and runtime hot-plug use the same code path.
Phases
- Phase 1 —
panda-abidevice types:BusType, per-bus*DeviceIdstructs,DeviceEvent, newOP_andEVENT_constants - Phase 2 —
crates/panda-elf: addread_section(bytes, name) -> Option<&[u8]> - Phase 3 —
libpandamacros (pci_device_table![]etc.), syscall wrappers, andMmioRegionsafe MMIO abstraction - Phase 4 — Kernel subscription registry:
SubscriptionRegistry,DeviceRegistry, subscription replay,post_added/post_removed; wire intopci::init() - Phase 5 — Service manager driver registry:
initrd:kernel scheme (backed by in-memory ustar archive) + two-phase driver scanning (initrd first, root fs after mount) - Phase 6 — Device ownership syscalls:
DEVICE_CLAIM,DEVICE_MAP_MMIO,DMA_ALLOC,DMA_FREE,DEVICE_SUBSCRIBE_IRQ; handle-close cleanup path (requires IOMMU) - Phase 7 — Virtio keyboard userspace driver: atomic cutover, kernel driver deleted, userspace driver in
userspace/drivers/virtio-keyboard/ - Phase 8 — Documentation:
docs/DEVICE_DRIVERS.md
Key design decisions
- ELF section naming convention:
.panda_devices.{bus}with fixed-size#[repr(C)]structs — readable without executing the binary, extensible to new bus types with no changes to existing code. - Device tokens:
EVENT_DEVICE_ADDEDdelivers an opaque one-time-useHandlealongside device info.DEVICE_CLAIMtakes this token, not a raw address. Non-forgeable and compatible with a future capability-based authorisation system. - Hot-plug by default: drivers subscribe and wait; the kernel replays
EVENT_DEVICE_ADDEDfor already-present devices to new subscribers, eliminating start-order races. - Wildcard subscriptions: the service manager calls
OP_DEVICE_SUBSCRIBE(bus_type, all-wildcard)once per known bus type at startup. initrd:scheme: kernel scheme backed by the in-memory ustar archive; no disk extraction needed before the block driver is available.- Two-phase driver scanning: initrd drivers first (includes virtio-blk), then root filesystem drivers after mount.
MmioRegion: safe wrapper around mapped BAR pointer enforcing bounds and volatile access, making it impossible to form a Rust reference to device memory.- Atomic cutover: kernel virtio keyboard driver is deleted in the same commit that adds the userspace driver; no coexistence period.
Activity
michaelmelanson commentedon May 15, 2026
Reconciled from #44:
service:/keyboard) after initialisation, and interrupt delivery uses the existing mailbox event system.EVENT_IRQfor interrupt delivery; this plan usesEVENT_DEVICE_IRQto avoid ambiguity with other IRQ sources.