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:

BaseDeviceOps: The core trait that all emulated devices must implement.
EmuDeviceType: Enumeration representing the type of emulator devices (re-exported from axvmconfig crate).
EmulatedDeviceConfig: Configuration structure for device initialization.
Trait aliases for specific device types:
- BaseMmioDeviceOps: For MMIO (Memory-Mapped I/O) devices.
- BaseSysRegDeviceOps: For system register devices.
- BasePortDeviceOps: For port I/O devices.

§Usage

To implement a custom emulated device, you need to implement the BaseDeviceOps trait with the appropriate address range type:

use axdevice_base::{BaseDeviceOps, EmuDeviceType};
use axaddrspace::{GuestPhysAddrRange, device::AccessWidth};
use ax_errno::AxResult;

struct MyDevice {
    base_addr: usize,
    size: usize,
}

impl BaseDeviceOps<GuestPhysAddrRange> for MyDevice {
    fn emu_type(&self) -> EmuDeviceType {
        EmuDeviceType::Dummy
    }

    fn address_range(&self) -> GuestPhysAddrRange {
        (self.base_addr..self.base_addr + self.size).try_into().unwrap()
    }

    fn handle_read(&self, addr: GuestPhysAddr, width: AccessWidth) -> AxResult<usize> {
        // Handle read operation
        Ok(0)
    }

    fn handle_write(&self, addr: GuestPhysAddr, width: AccessWidth, val: usize) -> AxResult {
        // Handle write operation
        Ok(())
    }
}

§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 [AxVmDevices].
EmulatedDeviceConfig: Represents the configuration of an emulated device for a virtual machine.
GuestPhysAddr: Guest physical address.
IrqLine: A shareable interrupt line connected to an IrqSink.
IrqLineId: Identifier of an interrupt line within a virtual machine.
MmioDeviceAdapter: Wraps an old-style BaseDeviceOps<GuestPhysAddrRange> device so that it implements the new Device trait.
Port: The port number of an x86 I/O operation.
PortDeviceAdapter: Wraps an old-style BaseDeviceOps<PortRange> device so that it implements the new Device trait.
PortRange: A inclusive range of port numbers.
SysRegAddr: A system register address.
SysRegAddrRange: A inclusive range of system register addresses.
SysRegDeviceAdapter: Wraps an old-style BaseDeviceOps<SysRegAddrRange> device so that it implements the new Device trait.

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.
EmuDeviceType: The type of emulated device.
InterruptTriggerMode: Interrupt trigger mode.
InvalidResourceReason: The reason a resource was rejected as structurally invalid during validation.
RegistryError: Errors that can be returned when registering a device.
Resource: A resource that a device declares it needs during registration.

Traits§

BaseDeviceOps: The core trait that all emulated devices must implement.
BusRouter: Bus dispatch interface — the runtime hot-path half of a [AxVmDevices].
Device: The unified device trait.
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 [AxVmDevices].
IrqSink: Receives state changes and pulses from interrupt lines.

Functions§

map_device_of_typeDeprecated: Attempts to downcast a device to a specific type and apply a function to it.

Type Aliases§

AxResult: A specialized Result type with AxError as the error type.
GuestPhysAddrRange: Guest physical address range.

Trait Aliases§

BaseMmioDeviceOps: Trait alias for MMIO (Memory-Mapped I/O) device operations.
BasePortDeviceOps: Trait alias for port I/O device operations.
BaseSysRegDeviceOps: Trait alias for system register device operations.