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.
VirtualInterruptController, WiredIrqInput, and IrqLine: architecture-neutral interrupt connections 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.
ControllerInputId: Identifies one hardware input on an interrupt controller.
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.
HostIrqId: Identifies one physical interrupt in the host interrupt namespace.
InterruptControllerId: Identifies an interrupt controller within one virtual machine.
InterruptSourceId: Identifies one device connection to a controller input.
IrqLine: A shareable device connection to one wired controller input.
IrqLineId: Identifier of an interrupt line within a virtual machine.
ItsId: Identifies one ITS instance within a virtual machine.
LpiId: Identifies one LPI in a virtual interrupt controller.
MsiDeviceId: Identifies an MSI-producing device in a message interrupt domain.
MsiEndpoint: A device-owned connection to a message interrupt controller.
MsiEventId: Identifies an event generated by an MSI-producing device.
MsiMessage: One message delivered to an MSI-capable interrupt controller.
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.
WiredIrqInput: A controller-owned wired interrupt input.

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.
InterruptEndpoint: Pinpoints the interrupt endpoint involved in an operation.
InterruptSharing: Declares whether multiple independently owned sources may use one wired controller input.
InterruptTriggerMode: Interrupt trigger mode.
InvalidResourceReason: The reason a resource was rejected as structurally invalid during validation.
IrqError: Errors reported while connecting or signaling interrupt endpoints.
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].
MessageInterruptController: Supplies planner-authorized MSI endpoints to virtual devices.
MessageInterruptSink: Receives message-signaled interrupts for one controller.
VirtualInterruptController: Supplies controller-owned wired inputs to virtual devices.
WiredIrqSink: Receives the aggregate electrical state of one controller input.

Type Aliases§

DeviceResult: Result type returned by device access operations.
GuestPhysAddrRange: Guest physical address range.
InterruptTrigger: Trigger semantics of one wired interrupt input.
IrqResult: Result type returned by virtual interrupt connection operations.