Goal: receive guest register accesses at EL2
Wave five connects a guest I/O request to a small device implemented at EL2. The entry is a virtio-mmio register window at IPA 0x0a000000. An EL1 load or store reaches emulate_mmio through a stage-two exception and changes Device state. Follow the distinction between an ordinary RAM write and a write interpreted as a device operation from the guest instruction that initiates each one.
The distributed project is examples/rust-hypervisor-wave5. Device::read and Device::write in lib.rs define register behavior, while initialize_device in main.rs shows the guest driver sequence. This separates machine exception handling from state transitions that ordinary Rust tests can inspect. The web interface replays captured QEMU runs; editing the source and producing a new machine run happens in the downloaded project.
Scope: one read-only block device
This implementation reports modern MMIO Version 2 and DeviceID 2, advertising RO and VERSION_1. It provides queue zero with exactly eight entries. The restricted contract makes each admission condition visible. The virtio name does not establish compatibility with arbitrary drivers or a bootable Linux system.
EL2 and one trusted EL1 guest share lesson RAM. Address and descriptor checks are present, but this is not an isolation boundary against a hostile guest. Packed queues, indirect descriptors, arbitrary scatter-gather, EVENT_IDX, and notification suppression are outside the subset. Keep the general transport design separate from the precise operations accepted by this implementation.
Read registers by responsibility
Registers have separate identification, feature, queue, notification, and status responsibilities. DeviceFeaturesSel selects a 32-bit feature page. Page zero contains RO at bit five; page one contains bit zero, representing overall bit thirty-two for VERSION_1. Reading one page does not establish that the whole required feature set is present.
Queue addresses use low and high 32-bit register pairs. Once QueueReady is set, this implementation rejects address changes, preserving the relationship between validated memory and subsequently accessed memory. The table gives offsets from the MMIO window, not addresses of ring storage in guest RAM.
| Role | Offset | Lesson behavior |
|---|---|---|
| Identity | 0x000 / 0x004 / 0x008 | Magic / Version 2 / DeviceID 2 |
| Features | 0x010,0x014 / 0x020,0x024 | Offered / accepted feature pages |
| Queue | 0x030 / 0x038 / 0x044 | Select / size eight / Ready |
| Addresses | 0x080,0x084 / 0x090,0x094 / 0x0a0,0x0a4 | Descriptors / available / used |
| Notifications | 0x050 / 0x060 / 0x064 | QueueNotify / InterruptStatus / InterruptACK |
| Status and capacity | 0x070 / 0x100,0x104 | Accumulated status / four sectors |
Initialization: explain the gate behind each status
After reset, initialize_device writes status one and three, accepts both offered feature pages, and proceeds to eleven. Eleven combines ACKNOWLEDGE, DRIVER, and FEATURES_OK. Device::write checks that the accepted feature pair matches this lesson contract. Inspect readback rather than treating an attempted FEATURES_OK write as evidence of successful negotiation. A useful debugging table has three columns: the value the guest attempted to write, the state the device accepted, and the state subsequently read back. These can differ when a precondition fails. For example, accepted feature words alone do not make the queue ready, and valid queue addresses alone do not complete feature negotiation. Retaining these boundaries keeps a later rejected notification from hiding its earlier cause.
The guest then configures queue zero, its size, and three addresses before setting QueueReady. Layout::validate checks bounds, alignment, and overlap. Status fifteen adds DRIVER_OK; only Ready together with status fifteen admits QueueNotify. Explain why notification comes last from the conditions needed to read shared memory, rather than memorizing a list of hexadecimal writes.
MMIO exceptions: emulate one instruction
emulate_mmio derives the IPA, source or destination register, and access direction from exception information. The subset accepts aligned 32-bit accesses within the window. Reads return Device::read results through the saved register frame; writes pass the guest value to Device::write. Only an admitted QueueNotify invokes notify, so an arbitrary register write is not itself an I/O request.
After emulating the instruction, ELR_EL2 advances by four bytes. Returning to the unchanged address would repeat the same faulting access. Guessing the meaning of an unsupported access width would instead continue with incorrect state. Locate the branches separating rejected accesses from successful emulation and return. Also distinguish the faulting instruction address from the requested device address. ELR_EL2 tells the handler where guest execution resumes; the reconstructed IPA identifies which device register the instruction accessed. Adding four to the device address would select another register, while adding four to ELR skips the emulated instruction. Writing both addresses in a trace makes this otherwise plausible mix-up easy to detect.
Runnable Rust: isolate initialization gates
This standalone host program extracts negotiation and queue-readiness gates from Device::write. Compile it with rustc as one file. It checks valid and rejected transitions without accessing MMIO or system registers. Actual exception handling remains a separate claim requiring the QEMU recording.
The rejected cases jump from zero to fifteen, attempt FEATURES_OK without accepted features, and attempt DRIVER_OK without Ready. For each rejection, state the missing precondition. The reset assertion also checks that accepted features and readiness are cleared. Turning the meaning of a status value into explicit preconditions is the purpose of this small test.
#[derive(Debug, PartialEq)]
enum Reject { Order, Features, Queue }
struct Device { status: u32, features: [u32; 2], ready: bool }
impl Device {
fn set_status(&mut self, next: u32) -> Result<(), Reject> {
if next == 0 { self.status=0; self.features=[0;2]; self.ready=false; return Ok(()); }
match (self.status, next) {
(0,1) | (1,3) => {},
(3,11) if self.features == [1<<5,1] => {},
(3,11) => return Err(Reject::Features),
(11,15) if self.ready => {},
(11,15) => return Err(Reject::Queue),
_ => return Err(Reject::Order),
}
self.status=next; Ok(())
}
}
fn main() {
let mut d=Device {status:0,features:[0;2],ready:false};
assert_eq!(d.set_status(15),Err(Reject::Order));
d.set_status(1).unwrap(); d.set_status(3).unwrap();
assert_eq!(d.set_status(11),Err(Reject::Features));
d.features=[1<<5,1]; d.set_status(11).unwrap();
assert_eq!(d.set_status(15),Err(Reject::Queue));
d.ready=true; d.set_status(15).unwrap();
d.set_status(0).unwrap();
assert_eq!((d.status,d.features,d.ready),(0,[0,0],false));
println!("negotiation=ok queue-gate=ok reset=ok");
}Read evidence at the right layer
Follow MMIO_READ and MMIO_WRITE through identification, feature-page selection, Ready, and DRIVER_OK. Only then look for QueueNotify, QUEUE_TAKE, and CHAIN_VALID. Reading the magic value establishes identification, not successful descriptor consumption. A final DONE message conceals which earlier boundaries were crossed.
Preserve the selected case command, source identity, ELF hash, and raw UART together. The device in this experiment is the Rust EL2 implementation, rather than QEMU built-in virtio-blk. QEMU supplies the CPU, exception environment, and GIC. State which layer is implemented in the lesson and which layer comes from the execution platform.
Exercise: distinguish order errors from value errors
Try DRIVER_OK before Ready and omit acceptance of the high feature page. Predict the rejecting Device::write call and its reason before testing. Compare each result with the normal recording and identify the first divergent state. A rejected final notification does not by itself establish a broken notification register.
For an extension, attempt to change the descriptor address after Ready. Explain the frozen-layout contract and contrast it with resetting and configuring again. Submit a transition table, failure location, and reproduction command. Distinguish new machine runs from playback and explain the narrower evidence supplied by the host transition test.