Device Drivers

Modular driver framework, Magma GPU driver, and guide to writing Helix drivers.

Documentation

Driver Architecture

Helix uses a modular driver architecture where drivers are implemented as kernel modules that can be loaded, unloaded, and hot-reloaded at runtime.

Driver Model

Driver Model — Layer Stack5N · 4E
▶Kernel Subsystemsfilesystem, network,…1Driver Interface LayerStandardized device …2Driver Module Frameworkhelix-modules2HAL Hardware Accesshelix-hal2■HardwarePhysical devices1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Driver Traits

Each driver category implements a specific trait:

drivers/src/traits.rs
rust
pub trait BlockDevice: Send + Sync {
fn read_block(&self, lba: u64, buf: &mut [u8]) -> Result<()>;
fn write_block(&self, lba: u64, buf: &[u8]) -> Result<()>;
fn flush(&self) -> Result<()>;
fn block_size(&self) -> u32;
fn total_blocks(&self) -> u64;
7
}
8
pub trait NetworkDevice: Send + Sync {
fn send(&self, packet: &[u8]) -> Result<()>;
fn recv(&self, buf: &mut [u8]) -> Result<usize>;
fn mac_address(&self) -> [u8; 6];
fn link_speed(&self) -> u64;
fn is_link_up(&self) -> bool;
15
}
16
pub trait GpuDevice: Send + Sync {
fn init(&mut self) -> Result<()>;
fn submit_commands(&self, cmds: &CommandBuffer) -> Result<()>;
fn allocate_memory(&mut self, size: usize, flags: MemFlags) -> Result<GpuAlloc>;
fn free_memory(&mut self, alloc: GpuAlloc) -> Result<()>;
22
}
Index

Magma GPU Driver

The Magma GPU driver (drivers/gpu/magma/) is currently the only hardware driver in Helix. It's a massive undertaking with 52+ sub-crates targeting NVIDIA-compatible GPU hardware.

Architecture

Magma GPU Driver — Architecture8N · 7E
▶magma/GPU driver stack7magma-core/Core GPU abstraction…1magma-hal/Hardware abstraction1magma-mem/Memory management1magma-cmd/Command processing1magma-rpc/Firmware interface1magma-gl/OpenGL 4.61magma-vulkan/Vulkan 1.31
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

PCI Device Discovery

drivers/gpu/magma/crates/magma-hal/src/pci.rs
rust
pub fn enumerate_gpus() -> Vec<PciDeviceInfo> {
2
// Scan PCI bus for VGA-compatible devices
3
// Class code: 0x03 (Display controller)
4
// Subclass: 0x00 (VGA), 0x02 (3D)
5
}
6
pub struct PciDevice {
8
pub bus: u8,
9
pub device: u8,
10
pub function: u8,
11
pub vendor_id: u16, // 0x10DE = NVIDIA
12
pub device_id: u16, // GPU model identifier
13
pub class_code: u8,
14
pub subclass: u8,
15
pub bars: [Option<Bar>; 6],
16
pub irq_line: u8,
17
}
Index

BAR Mapping

BARSizePurpose
BAR016-32 MBGPU registers (MMIO)
BAR1128 MB - 32 GBMappable VRAM (ReBAR)
BAR2VariableI/O ports (legacy)
BAR332 MBNV_PFAULT, NV_PRAMIN

GSP Firmware RPC

For modern NVIDIA GPUs, Magma communicates with the GPU Security Processor (GSP) via RPC:

drivers/gpu/magma/crates/magma-hal/src/gsp.rs
rust
pub struct RpcChannel {
2
// Send an RPC message to GSP
3
// pub fn send(&self, msg: RpcMessage) -> Result<()>;
4
// pub fn recv(&self) -> Result<RpcMessage>;
5
}
6
3 refs
pub struct RpcMessage {
8
pub function: u32,
9
pub params: Vec<u32>,
10
pub payload: Option<Vec<u8>>,
11
}
Index

GSP handles: power management, thermal monitoring, security policies, and hardware initialization sequences that are too complex or proprietary for the open-source driver.

Planned Drivers

The following drivers are planned for future development:

Storage

DriverTargetPriority
AHCISATA controllersHigh
NVMeNVMe SSDsHigh
VirtIO-blkQEMU virtual block devicesMedium
USB Mass StorageUSB drivesLow

Network

DriverTargetPriority
VirtIO-netQEMU virtual networkHigh
E1000Intel Gigabit EthernetMedium
RTL8139Realtek (QEMU default)Medium
XHCIUSB 3.0 host controllerLow

Input

DriverTargetPriority
PS/2Keyboard and mouseHigh
USB HIDUSB keyboards, mice, gamepadsMedium
VirtIO-inputQEMU virtual inputMedium

Other

DriverTargetPriority
Serial16550 UARTDone (in HAL)
RTCCMOS Real-Time ClockMedium
ACPIPower managementMedium
PCIePCI Express bus enumerationHigh

Writing a Driver

To implement a new driver in Helix:

1. Create a Module

drivers/example/src/lib.rs
rust
1
use helix_modules::v2::*;
2
2 refs
pub struct MyDriver {
4
// Hardware state
5
}
6
2 refs
impl ModuleTrait for MyDriver {
fn info(&self) -> ModuleInfo {
9
ModuleInfo::new("my_driver")
10
.version(0, 1, 0)
11
.author("Your Name")
12
.description("Driver for XYZ hardware")
13
.flags(ModuleFlags::DRIVER)
14
}
15
fn init(&mut self, ctx: &Context) -> Result<(), ModuleError> {
17
// Discover hardware via PCI scan
18
// Map BARs
19
// Initialize hardware
20
Ok(())
21
}
22
fn start(&mut self) -> Result<(), ModuleError> {
24
// Register interrupt handler
25
// Enable hardware
26
Ok(())
27
}
28
2 refs
fn stop(&mut self) -> Result<(), ModuleError> {
30
// Disable interrupts
31
// Power down hardware
32
Ok(())
33
}
34
fn handle_event(&mut self, event: &Event) -> EventResponse {
36
match event {
37
Event::Tick { .. } => { /* periodic housekeeping */ }
38
Event::Shutdown => { let _ = self.stop(); }
39
_ => {}
40
}
41
EventResponse::Handled
42
}
43
}
Index

2. Implement the Device Trait

drivers/example/src/lib.rs
rust
impl BlockDevice for MyDriver {
fn read_block(&self, lba: u64, buf: &mut [u8]) -> Result<()> {
3
// MMIO read from hardware
4
}
5
fn write_block(&self, lba: u64, buf: &[u8]) -> Result<()> {
7
// MMIO write to hardware
8
}
9
fn flush(&self) -> Result<()> { Ok(()) }
fn block_size(&self) -> u32 { 512 }
fn total_blocks(&self) -> u64 { self.capacity / 512 }
13
}
Index

3. Register with the Module System

drivers/example/Cargo.toml
rust
1
// In Cargo.toml
2
[dependencies]
3
helix-modules = { path = "../../modules" }
4
helix-hal = { path = "../../hal" }
5
6
// The module_v2! macro handles registration automatically

4. Hardware Access Pattern

drivers/example/src/lib.rs
rust
1
// Safe MMIO access via HAL
2
let bar0 = hal.map_bar(pci_device, 0)?;
3
let status = bar0.read32(REGISTER_STATUS);
4
bar0.write32(REGISTER_COMMAND, CMD_ENABLE);
5
6
// Interrupt handling
7
hal.register_irq(pci_device.irq_line, |frame| {
8
let status = bar0.read32(REGISTER_IRQ_STATUS);
9
bar0.write32(REGISTER_IRQ_ACK, status);
10
InterruptAction::Handled
11
})?;