Goal: separate publication from consumption
A virtqueue transfers requests and completions through shared memory. Match guest prepare_request with EL2 notify and follow how a published request is taken once. The notification register does not contain the 512-byte payload. It is an entry signal; descriptors and buffers in RAM hold the request itself.
This project uses split rings: a descriptor table, available ring, and used ring occupy separate areas. The guest publishes a head index on the available side; EL2 publishes completion on the used side. Shared visibility does not erase write ownership. Compare QUEUE_TAKE with USED_PUBLISH and explain the validation and mutations between them.
Draw the fixed arena before following pointers
The lesson arena begins at 0x41000000 and spans 65536 bytes. Descriptor, available, used, header, data, and status areas are placed separately. Eight sixteen-byte descriptors form the table. Layout::validate checks that queue-management regions fit in the arena, meet alignment requirements, and do not overlap.
A payload address inside the arena can still be invalid: writing returned data over the used ring would corrupt completion bookkeeping. Layout::payload rejects overlap with management regions; validate_chain also checks payloads against each other. These are lesson addresses, not universal virtio placement requirements.
| Region | Arena offset | Responsibility |
|---|---|---|
| Descriptor table | +0x0000 | Eight sixteen-byte descriptors |
| Available ring | +0x1000 | Guest publishes request heads |
| Used ring | +0x2000 | EL2 publishes completed heads and lengths |
| Request header | +0x3000 | Sixteen bytes: type, reserved, sector |
| Data | +0x4000 | 512-byte destination |
| Status | +0x5000 | One-byte request result |
Validate links, direction, and length independently
A normal read has a sixteen-byte header, 512-byte data area, and one-byte status. Header NEXT links to data; data NEXT|WRITE links to status; status WRITE terminates the chain. WRITE describes device permission, not guest permission. A read operation needs a device-writable data buffer because the device returns bytes to the guest.
validate_chain checks head and next indices, chain shape, lengths, direction, and addresses. It rejects cycles, repeated entries, and indirect-descriptor flags. checked_region also rejects overflowing address-plus-length arithmetic. Table indices and payload addresses are different boundaries, so validating one does not establish the other.
Publication: prepare content before advancing idx
prepare_request writes the header, descriptors, and available slot, orders memory, then advances available.idx and writes QueueNotify. notify establishes ordering before reading idx and comparing it with consumed. Publishing idx first would permit the peer to observe an incomplete request.
This implementation admits one newly outstanding request at a time. pending accepts difference zero as empty and one as available; other differences are rejected. Eight stored entries do not imply that this driver supports submitting eight requests as a batch. Extending concurrency requires changes to both consumption and guest bookkeeping.
Two wrap boundaries: slots and sixteen-bit counters
The ring position is consumed % 8. queueBoundary performs nine sequential requests, moving through slots zero to seven and back to zero. The guest reclaims each completion before reusing the buffer. That recording demonstrates slot reuse, not a machine run through the 65535-to-zero counter boundary.
wrapping_sub computes sixteen-bit distance. With consumed equal to 65535 and avail equal to zero, the distance is one. Ordinary subtraction and magnitude comparisons can misread that boundary. Host tests cover the numeric wrap; nine-request QEMU execution covers actual ring-storage reuse. Keep those evidence claims separate.
Runnable Rust: consume once and wrap the position
This standalone program isolates pending and ring-position arithmetic. Across nine requests, assertions check one outstanding publication before consumption and none afterward. A final position of zero demonstrates array-slot wrap. The sixteen-bit counter boundary is checked by a separate assertion.
The program does not implement shared memory, barriers, or device notification. Its arithmetic result is not evidence of machine visibility. First establish the numeric contract, then check nine corresponding QUEUE_TAKE, USED_PUBLISH, and GUEST_RECLAIM events in QEMU. Together they help distinguish duplicate consumption from legitimate storage reuse.
#[derive(Debug, PartialEq)]
enum Reject { TooMany }
fn pending(avail: u16, consumed: u16) -> Result<bool, Reject> {
match avail.wrapping_sub(consumed) {
0 => Ok(false), 1 => Ok(true), _ => Err(Reject::TooMany)
}
}
fn slot(index: u16) -> usize { (index % 8) as usize }
fn main() {
assert_eq!(pending(12,12),Ok(false));
assert_eq!(pending(13,12),Ok(true));
assert_eq!(pending(14,12),Err(Reject::TooMany));
assert_eq!(pending(0,u16::MAX),Ok(true));
let mut consumed=0u16;
let mut positions=Vec::new();
for _ in 0..9 {
let avail=consumed.wrapping_add(1);
assert_eq!(pending(avail,consumed),Ok(true));
positions.push(slot(consumed));
consumed=consumed.wrapping_add(1);
assert_eq!(pending(avail,consumed),Ok(false));
}
assert_eq!(positions,vec![0,1,2,3,4,5,6,7,0]);
assert_eq!(consumed,9);
println!("slots={:?} u16-boundary=ok",positions);
}Can a malformed chain return a request status?
In queueFailure, a cyclic chain prevents EL2 from identifying a valid request including a safe status destination. EL2 adds DEVICE_NEEDS_RESET mask sixty-four (bit six), taking device status from fifteen to seventy-nine. It advances no used index and sends no used-buffer completion notification. Instead, InterruptStatus bit one (value two) announces a configuration change through IRQ forty; the guest reads device status seventy-nine. This is different from completing a valid read request with IOERR.
A valid chain with an out-of-capacity sector still provides a safe status destination, so IOERR can be returned with completion. Both failures can use an IRQ, but they differ in used-ring advancement and InterruptStatus: bit zero (value one) for an IOERR completion, bit one (value two) for reset-required configuration change. Look first for CHAIN_VALID after QUEUE_TAKE, then for BLOCK_REQUEST. Establish request structure before interpreting request meaning. The queueSpurious recording supplies a third outcome: an empty or duplicate notification with available.idx equal to consumed. The device records QUEUE_IDLE and ignores it without resetting, publishing used, injecting an IRQ, or changing queue state. Notification is therefore a reason to inspect shared state, not proof that a new request exists. This distinction permits a repeated doorbell after a previous request has already been consumed without inventing another transfer.
Exercise: violate one invariant at a time
Start from a valid three-descriptor request. Redirect data.next to the head, remove status WRITE, change data length to 511, or move data.addr onto the used ring. Predict the rejecting check for each isolated mutation. Combining faults makes only the first reported failure visible and weakens coverage of the remaining boundaries.
Make a nine-request table with separate slot and idx columns, marking publication, consumption, and reclaim. Test the 65535-to-zero numeric case separately. Submit rejection reasons, used-index changes, InterruptStatus bits, IRQ handling, and which checks were machine runs versus host tests. Matching totals is not enough; confirm that each publication is consumed once. Compare queueSpurious with queueFailure explicitly. The former has no newly available chain to validate; the latter presents a new but malformed chain. Keeping empty, admitted, and malformed cases separate prevents a harmless repeated notification from becoming a device failure. Record both counter values before interpreting a missing completion, rather than assuming every notification must increment a counter.