axdevice_base 0.2.0

Basic traits and structures for emulated devices in ArceOS hypervisor.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# axdevice_base

[![CI](https://github.com/arceos-hypervisor/axdevice_base/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/arceos-hypervisor/axdevice_base/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/axdevice_base)](https://crates.io/crates/axdevice_base)
[![Docs.rs](https://docs.rs/axdevice_base/badge.svg)](https://docs.rs/axdevice_base)

Basic device abstraction library for [AxVisor](https://github.com/arceos-hypervisor/axvisor) virtual device subsystem, designed for `no_std` environments.

## Overview

`axdevice_base` provides core traits, structures, and type definitions for virtual device development, including:

- `BaseDeviceOps` trait: Common interface that all virtual devices must implement.
- `EmulatedDeviceConfig`: Device initialization and configuration structure.
- Device type enumeration `EmuDeviceType` (re-exported from `axvmconfig` crate).
- Trait aliases for various device types:
  - `BaseMmioDeviceOps`: For MMIO (Memory-Mapped I/O) devices.
  - `BaseSysRegDeviceOps`: For system register devices (ARM).
  - `BasePortDeviceOps`: For port I/O devices (x86).
- `map_device_of_type`: Helper function for runtime device type checking and casting.

## Features

- **`no_std` compatible**: Designed for bare-metal and hypervisor environments.
- **Multi-architecture support**: x86_64, AArch64, RISC-V64.
- **Type-safe addressing**: Different address range types for different device access methods.
- **Serialization support**: Device configuration can be serialized/deserialized via `serde`.

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
axdevice_base = "0.1"
```

### Implementing a Custom Device

```rust,ignore
use axdevice_base::{BaseDeviceOps, EmuDeviceType};
use axaddrspace::{GuestPhysAddr, GuestPhysAddrRange, device::AccessWidth};
use axerrno::AxResult;

struct MyUartDevice {
    base_addr: usize,
    // ... device state
}

impl BaseDeviceOps<GuestPhysAddrRange> for MyUartDevice {
    fn emu_type(&self) -> EmuDeviceType {
        EmuDeviceType::Dummy  // Use appropriate device type
    }

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

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

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

### Device Configuration

```rust
use axdevice_base::EmulatedDeviceConfig;

let config = EmulatedDeviceConfig {
    name: "uart0".into(),
    base_ipa: 0x0900_0000,
    length: 0x1000,
    irq_id: 33,
    emu_type: 1,
    cfg_list: vec![115200],  // device-specific config (e.g., baud rate)
};
```

### Type Checking with `map_device_of_type`

```rust,ignore
use axdevice_base::{BaseMmioDeviceOps, map_device_of_type};
use alloc::sync::Arc;

fn process_device(device: &Arc<dyn BaseMmioDeviceOps>) {
    // Try to access device-specific methods if it's a UartDevice
    if let Some(baud_rate) = map_device_of_type(device, |uart: &MyUartDevice| {
        uart.get_baud_rate()
    }) {
        println!("UART baud rate: {}", baud_rate);
    }
}
```

## Supported Platforms

| Architecture | MMIO Devices | Port I/O Devices | System Register Devices |
|--------------|--------------|------------------|-------------------------|
| x86_64       | ✓            | ✓                | -                       |
| AArch64      | ✓            | -                | ✓                       |
| RISC-V64     | ✓            | -                | -                       |

## Documentation

For detailed API documentation, visit [docs.rs/axdevice_base](https://docs.rs/axdevice_base).

## Contributing

Issues and PRs are welcome! Please follow the [ArceOS-hypervisor project guidelines](https://github.com/arceos-hypervisor/axvisor).

## License

Axdevice_base is licensed under the Apache License, Version 2.0. See the [LICENSE](./LICENSE) file for details.