Architecture and Design

Relevant source files

• axdriver_base/src/lib.rs
• axdriver_block/src/lib.rs
• axdriver_net/src/lib.rs
• axdriver_virtio/src/lib.rs

Purpose and Scope

This document describes the architectural foundations and design principles that unify the axdriver_crates framework. It covers the trait hierarchy, modular organization, error handling patterns, and compilation strategies that enable building device drivers for ArceOS across different hardware platforms and virtualized environments.

For detailed information about specific device types, see Foundation Layer (axdriver_base), Network Drivers, Block Storage Drivers, Display Drivers, and VirtIO Integration. For build system details, see Development and Build Configuration.

Core Architectural Principles

The axdriver_crates framework follows several key design principles that promote modularity, type safety, and cross-platform compatibility:

Trait-Based Driver Interface

All device drivers implement a common trait hierarchy starting with BaseDriverOps. This provides a uniform interface for device management while allowing device-specific functionality through specialized traits.

Zero-Cost Abstractions

The framework leverages Rust's type system and compilation features to provide high-level abstractions without runtime overhead. Device-specific functionality is conditionally compiled based on cargo features.

Hardware Abstraction Layering

The framework separates device logic from hardware-specific operations through abstraction layers, enabling the same driver interface to work with both native hardware and virtualized devices.

Trait Hierarchy and Inheritance Model

The framework establishes a clear inheritance hierarchy where all drivers share common operations while extending with device-specific capabilities.

Base Driver Operations

flowchart TD
BaseDriverOps["BaseDriverOps• device_name()• device_type()"]
DeviceType["DeviceType enum• Block• Char• Net• Display"]
DevResult["DevResult<T>Result<T, DevError>"]
DevError["DevError enum• AlreadyExists• Again• BadState• InvalidParam• Io• NoMemory• ResourceBusy• Unsupported"]
NetDriverOps["NetDriverOps• mac_address()• can_transmit/receive()• rx/tx_queue_size()• transmit/receive()• alloc_tx_buffer()"]
BlockDriverOps["BlockDriverOps• num_blocks()• block_size()• read_block/write_block()• flush()"]
DisplayDriverOps["DisplayDriverOps• info/framebuffer• flush display"]

BaseDriverOps --> BlockDriverOps
BaseDriverOps --> DevResult
BaseDriverOps --> DeviceType
BaseDriverOps --> DisplayDriverOps
BaseDriverOps --> NetDriverOps
DevResult --> DevError

Diagram: Core Trait Hierarchy and Type System

Sources: axdriver_base/src/lib.rs(L18 - L62)  axdriver_net/src/lib.rs(L24 - L68)  axdriver_block/src/lib.rs(L15 - L38) 

Device-Specific Extensions

Each device type extends the base operations with specialized functionality:

Sources: axdriver_net/src/lib.rs(L24 - L68)  axdriver_block/src/lib.rs(L15 - L38) 

Device Type Abstraction System

The framework uses a centralized device type system that enables uniform device discovery and management across different hardware platforms.

flowchart TD
subgraph subGraph2["Device Registration"]
    DriverManager["Device driver registration"]
    TypeMatching["Device type matching"]
    DriverBinding["Driver binding"]
end
subgraph subGraph1["VirtIO Device Discovery"]
    VirtIOProbe["probe_mmio_device()"]
    VirtIOPCIProbe["probe_pci_device()"]
    VirtIOTypeConv["as_dev_type()"]
end
subgraph subGraph0["Native Device Discovery"]
    PCIProbe["PCI device probing"]
    MMIOProbe["MMIO device discovery"]
    HardwareEnum["Hardware enumeration"]
end
DeviceType["DeviceType enum"]

DeviceType --> TypeMatching
DriverBinding --> DriverManager
MMIOProbe --> DeviceType
PCIProbe --> DeviceType
TypeMatching --> DriverBinding
VirtIOPCIProbe --> VirtIOTypeConv
VirtIOProbe --> VirtIOTypeConv
VirtIOTypeConv --> DeviceType

Diagram: Device Type Abstraction and Discovery Flow

The DeviceType enum serves as the central abstraction that maps hardware devices to appropriate driver implementations. The VirtIO integration demonstrates this pattern through type conversion functions that translate VirtIO-specific device types to the common DeviceType enumeration.

Sources: axdriver_base/src/lib.rs(L18 - L29)  axdriver_virtio/src/lib.rs(L71 - L79)  axdriver_virtio/src/lib.rs(L38 - L69) 

Error Handling Design

The framework implements a unified error handling strategy through the DevResult<T> type and standardized error codes in DevError.

Error Code Mapping

The framework provides consistent error semantics across different hardware backends through error code translation:

flowchart TD
subgraph subGraph2["Driver Operations"]
    NetOps["NetDriverOps methods"]
    BlockOps["BlockDriverOps methods"]
    BaseOps["BaseDriverOps methods"]
end
subgraph subGraph1["Error Types"]
    QueueFull["QueueFull → BadState"]
    NotReady["NotReady → Again"]
    InvalidParam["InvalidParam → InvalidParam"]
    DmaError["DmaError → NoMemory"]
    IoError["IoError → Io"]
    Unsupported["Unsupported → Unsupported"]
end
subgraph subGraph0["VirtIO Error Translation"]
    VirtIOError["virtio_drivers::Error"]
    ErrorMapping["as_dev_err() function"]
    DevError["DevError enum"]
end

BaseOps --> DevError
BlockOps --> DevError
ErrorMapping --> DevError
ErrorMapping --> DmaError
ErrorMapping --> InvalidParam
ErrorMapping --> IoError
ErrorMapping --> NotReady
ErrorMapping --> QueueFull
ErrorMapping --> Unsupported
NetOps --> DevError
VirtIOError --> ErrorMapping

Diagram: Unified Error Handling Architecture

This design enables consistent error handling across different driver implementations while preserving semantic meaning of hardware-specific error conditions.

Sources: axdriver_base/src/lib.rs(L31 - L53)  axdriver_virtio/src/lib.rs(L82 - L97) 

Modular Workspace Organization

The framework employs a modular workspace structure that promotes code reuse and selective compilation.

Workspace Dependency Graph

flowchart TD
subgraph subGraph3["External Dependencies"]
    virtio_drivers["virtio-drivers crate"]
    hardware_crates["Hardware-specific cratesfxmac_rsixgbe-driver"]
end
subgraph subGraph2["Hardware Integration"]
    axdriver_pci["axdriver_pciPCI bus operations"]
    axdriver_virtio["axdriver_virtioVirtIO device wrappersTransport abstraction"]
end
subgraph subGraph1["Device Abstractions"]
    axdriver_net["axdriver_netNetDriverOpsNetBuf systemEthernetAddress"]
    axdriver_block["axdriver_blockBlockDriverOpsBlock I/O"]
    axdriver_display["axdriver_displayDisplayDriverOpsGraphics"]
end
subgraph Foundation["Foundation"]
    axdriver_base["axdriver_baseBaseDriverOpsDeviceTypeDevError"]
end

axdriver_base --> axdriver_block
axdriver_base --> axdriver_display
axdriver_base --> axdriver_net
axdriver_base --> axdriver_pci
axdriver_base --> axdriver_virtio
axdriver_net --> hardware_crates
axdriver_pci --> axdriver_block
axdriver_pci --> axdriver_net
axdriver_virtio --> virtio_drivers

Diagram: Workspace Module Dependencies

This organization allows applications to selectively include only the device drivers needed for their target platform, minimizing binary size and compilation time.

Sources: axdriver_base/src/lib.rs(L1 - L15)  axdriver_net/src/lib.rs(L6 - L11)  axdriver_block/src/lib.rs(L6 - L10)  axdriver_virtio/src/lib.rs(L16 - L28) 

Feature-Based Compilation Strategy

The framework uses cargo features to enable conditional compilation of device drivers and their dependencies.

Feature Organization Pattern

This pattern enables several deployment scenarios:

• Minimal embedded: Only essential drivers compiled in
• Full server: All available drivers for maximum hardware compatibility
• Virtualized: Only VirtIO drivers for VM environments
• Development: All drivers for testing and validation

Sources: axdriver_net/src/lib.rs(L6 - L11)  axdriver_block/src/lib.rs(L6 - L10)  axdriver_virtio/src/lib.rs(L16 - L21) 

Hardware Abstraction Patterns

The framework implements two primary patterns for hardware abstraction:

Direct Hardware Integration

For native hardware drivers, the framework integrates with hardware-specific crates that provide low-level device access. This pattern is used by drivers like FXmac and Intel ixgbe network controllers.

Virtualization Layer Integration

For virtualized environments, the framework provides adapter implementations that wrap external VirtIO drivers to implement the common trait interfaces. This enables the same driver API to work across both physical and virtual hardware.

The VirtIO integration demonstrates sophisticated error translation and type conversion to maintain API compatibility while leveraging mature external driver implementations.

Sources: axdriver_virtio/src/lib.rs(L38 - L97)  axdriver_net/src/lib.rs(L6 - L11)