Crate axdevice_base

Expand description

Basic traits and structures for emulated devices in ArceOS hypervisor.

This crate provides the foundational abstractions for implementing virtual devices in the AxVisor hypervisor. It is designed for no_std environments and supports multiple architectures.

§Overview

The crate contains the following key components:

Device: The unified V3 device trait used by the runtime hot path.
DeviceAccess: The access-scoped capability context passed to devices.
Resource: Static device resource declarations used for registration validation and bus dispatch.
IrqSink and IrqLine: Architecture-neutral interrupt delivery contracts used by device factories.

§Usage

New emulated devices should implement Device directly and receive all sensitive runtime abilities through DeviceAccess.

use axdevice_base::{
    AccessWidth, BusAccess, BusKind, BusResponse, Device, DeviceAccess,
    DeviceError, Resource,
};

struct MyDevice {
    base_addr: usize,
    size: usize,
    resources: [Resource; 1],
}

impl Device for MyDevice {
    fn name(&self) -> &str {
        "my-device"
    }

    fn resources(&self) -> &[Resource] {
        &self.resources
    }

    fn access(
        &self,
        access: &BusAccess,
        context: &mut dyn DeviceAccess,
    ) -> Result<BusResponse, DeviceError> {
        match (access.kind, access.is_read) {
            (BusKind::Mmio, true) => Ok(BusResponse::Read { value: 0 }),
            (BusKind::Mmio, false) => Ok(BusResponse::Write),
            _ => Err(DeviceError::OutOfRange { addr: access.addr }),
        }
    }
}

§Feature Flags

This crate currently has no optional feature flags. All functionality is available by default.

Structs§

BusAccess: An access issued by a vCPU to a device on a bus.
DeviceId: Opaque identifier assigned to a device when it is registered into a [DeviceRuntime].
DmaGrant: Permission token for access-scoped guest-memory DMA.
GuestPhysAddr: Guest physical address.
IrqLine: A shareable interrupt line connected to an IrqSink.
IrqLineId: Identifier of an interrupt line within a virtual machine.
NoopDeviceAccess: A no-permission access context for tests and adapter-only callers.
Port: The port number of an x86 I/O operation.
PortRange: A inclusive range of port numbers.
StopGrant: Permission token for requesting VM stop/suspend style actions.
SysRegAddr: A system register address.
SysRegAddrRange: A inclusive range of system register addresses.
TimerGrant: Permission token for virtual timer scheduling.
WakeGrant: Permission token for waking a vCPU from a device.

Enums§

AccessWidth: The width of a guest bus access.
Arch: Target instruction-set architecture.
BusKind: The kind of bus a device is connected to.
BusResponse: The result of a bus access dispatched to a device.
DeviceError: Errors that can occur during device access handling.
InterruptTriggerMode: Interrupt trigger mode.
InvalidResourceReason: The reason a resource was rejected as structurally invalid during validation.
IrqError: Errors reported while routing or signaling a virtual interrupt line.
RegistryError: Errors that can be returned when registering a device.
Resource: A resource that a device declares it needs during registration.

Traits§

BusRouter: Bus dispatch interface — the runtime hot-path half of a [DeviceRuntime].
Device: The unified device trait.
DeviceAccess: Context scoped to one device bus access.
DeviceAddr: An address-like type that can be used to access devices.
DeviceAddrRange: A range of device addresses. It may be contiguous or not.
DeviceRegistry: Device registration interface — the build-time / management-path half of a [DeviceRuntime].
IrqSink: Receives state changes and pulses from interrupt lines.

Type Aliases§

DeviceResult: Result type returned by device access operations.
GuestPhysAddrRange: Guest physical address range.
IrqResult: Result type returned by virtual interrupt routing operations.