Skip to content

Userspace device driver model #89

Open

Description

@michaelmelanson

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-abi device types: BusType, per-bus *DeviceId structs, DeviceEvent, new OP_ and EVENT_ constants
  • Phase 2 — crates/panda-elf: add read_section(bytes, name) -> Option<&[u8]>
  • Phase 3 — libpanda macros (pci_device_table![] etc.), syscall wrappers, and MmioRegion safe MMIO abstraction
  • Phase 4 — Kernel subscription registry: SubscriptionRegistry, DeviceRegistry, subscription replay, post_added/post_removed; wire into pci::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_ADDED delivers an opaque one-time-use Handle alongside device info. DEVICE_CLAIM takes 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_ADDED for 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

  1. added
    driversDevice drivers (virtio, block, GPU, keyboard)
    enhancementNew feature or request
    kernelKernel-space changes
    userspaceUserspace libraries and programs
    on May 15, 2026
  2. michaelmelanson commented on May 15, 2026

    @michaelmelanson
    OwnerAuthor

    Reconciled from #44:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    driversDevice drivers (virtio, block, GPU, keyboard)enhancementNew feature or requestkernelKernel-space changesuserspaceUserspace libraries and programs

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions