michaelmelanson / michaelmelanson/panda-os
Userspace device driver model
- Dominant language
- Rust
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
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`](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.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with plans/device-driver-model.md and verify the IOMMU prerequisite before choosing a phase. Use the checklist to trace work across crates/panda-elf, the kernel registries and syscalls, the service manager, userspace/drivers/virtio-keyboard/, and docs/DEVICE_DRIVERS.md. Done means all eight phases are implemented, including the atomic keyboard-driver cutover.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- embedded-iot, operating-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100