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 axvm-types 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::{AccessWidth, BaseDeviceOps, EmuDeviceType};
use axvm_types::{GuestPhysAddr, GuestPhysAddrRange};
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§

EmulatedDeviceConfig: Represents the configuration of an emulated device for a virtual machine.
GuestPhysAddr: Guest physical address.
Port: The port number of an I/O operation.
PortRange: A inclusive range of port numbers.
SysRegAddr: A system register address.
SysRegAddrRange: A inclusive range of system register addresses.

Enums§

AccessWidth: The width of an access.
EmuDeviceType: The type of emulated device.

Traits§

BaseDeviceOps: The core trait that all emulated devices must implement.
DeviceAddr: An address-like type that can be used to access devices.
DeviceAddrRange: A range of device addresses. It may be contiguous or not.

Functions§

map_device_of_type: 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.