axvirtio-net 0.1.0

VirtIO network device implementation with MMIO transport for hypervisors
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

# axvirtio-net

A `no_std` VirtIO 1.x MMIO **network device model** for the
[ArceOS-Hypervisor](https://github.com/arceos-hypervisor/) ecosystem. It runs
on the host side of a hypervisor and emulates a virtio-net device that a guest
driver talks to over MMIO; it is **not** a guest-side virtio-net frontend
driver.

It is built on top of [`axvirtio-common`](../axvirtio-common), which owns the
split virtqueue and MMIO transport protocol logic.

## Architecture

```text
VMM / network runtime (TAP, virtual switch, IRQ injection, task scheduling)
  |  push RX frame via receive_frame()   /   consume DeviceEvent to inject IRQ
  v
axvirtio-net  (this crate)
  |  virtio_net_hdr wire format, RX/TX semantics, config space, backend calls
  v
axvirtio-common  (split virtqueue, MMIO transport, guest memory access)
  |  GuestMemoryAccessor
  v
guest address space
```

The portable device model owns only protocol state. TAP/virtual-switch
lifetime and virtual interrupt injection belong to the VMM glue layer, which is
intentionally out of scope.

## First-version scope

- VirtIO 1.x MMIO transport, device ID `1` (network).
- Split virtqueue with a single RX/TX queue pair (RX = queue 0, TX = queue 1).
- Advertised features: `VIRTIO_F_VERSION_1`, `VIRTIO_NET_F_MAC`,
  `VIRTIO_NET_F_STATUS`.
- Base 10-byte `virtio_net_hdr` (no mergeable buffers). RX writes a zero
  header; TX rejects any checksum/GSO offload request.
- 6-byte MAC and link status exposed in config space (byte/word/dword reads).
- Guest TX is drained on queue-1 notification; host RX is driven explicitly by
  the VMM calling `receive_frame`.

Out of scope (do **not** appear in the device feature bits): control queue,
multiqueue (`VIRTIO_NET_F_MQ`), mergeable buffers (`VIRTIO_NET_F_MRG_RXBUF`),
indirect descriptors, `VIRTIO_F_RING_EVENT_IDX`, checksum/GSO/TSO offload, RSS.

## Public API surface

```rust
use axvirtio_net::{
    VirtioMmioNetDevice, VirtioNetConfig, NetworkBackend, NetworkBackendError, DeviceEvent,
    RxOutcome,
};

// Implement the host transmit boundary.
struct MyBackend;
impl NetworkBackend for MyBackend {
    fn transmit(&self, frame: &[u8]) -> Result<(), NetworkBackendError> { /* ... */ Ok(()) }
}

let device = VirtioMmioNetDevice::new(
    mmio_base, mmio_len, MyBackend, VirtioNetConfig::default(), guest_memory,
)?;

// Guest MMIO trap handler:
match device.mmio_write(addr, width, value)? {
    DeviceEvent::InterruptPending => { /* VMM injects a virtual IRQ */ }
    DeviceEvent::Reset => { /* device fully reset */ }
    DeviceEvent::None => {}
}
let v = device.mmio_read(addr, width)?;

// Host -> guest RX (VMM calls this when a frame arrives):
match device.receive_frame(frame)? {
    RxOutcome::Delivered { frame_len } => { /* written into a guest buffer */ }
    RxOutcome::NoGuestBuffer => { /* VMM may cache/retry/drop */ }
}
```

## Concurrency contract

- The device uses short internal critical sections (per-field spin locks, one
  per-queue lock).
- The TX path calls `NetworkBackend::transmit` while holding the queue lock, so
  **backends must not re-enter the device** from within `transmit` (e.g. call
  `receive_frame`), or it will self-deadlock.
- RX (`receive_frame`) validates the whole chain capacity **before** consuming
  the available head, so a too-small buffer or bad chain leaves the ring
  untouched.

## License

Licensed under Apache-2.0 (compatible with this repository).