Goal: explain the prerequisites for injection
Wave four goes beyond entering EL1: it delivers an actual GICv3 virtual interrupt to the guest. This lesson covers the setup required before injection. Read gic_setup, bootstrap, and inject in examples/rust-hypervisor-wave4, then compare the recorded GIC_READY and ENTER events. The experiment uses QEMU's GIC and the guest exception path, rather than merely printing a fictional interrupt number.
The scope is one trusted EL1 guest and one vCPU sharing lesson RAM with EL2. It does not implement Linux, virtio, multiple VMs, or isolation from a hostile guest. Fixing that scope makes it possible to focus on the registers establishing delivery without inferring a general-purpose hypervisor from the word virtualization.
Fix the QEMU machine conditions
The recording uses QEMU 8.2.2, virt-8.2, cortex-a57, TCG, one CPU, and 128 MiB RAM. The machine options explicitly enable virtualization, disable secure mode, and select GIC version three. A run with omitted or changed machine options is a different experiment. Preserve the full command together with the ELF hash instead of treating the Rust source alone as a complete reproduction recipe.
Browser playback reads captured UART and register observations. Editing source and running a new machine is a separate action. The distributed qemu-recording.json records commands, source context, ELF hashes, and output. For each displayed event, identify the source and configuration it observed. Selecting a recorded case in the interface is not evidence of a newly executed QEMU process.
Separate physical, virtual, and CPU-side conditions
gic_setup prepares the physical PPI27 notification from virtual-timer expiry and the virtual CPU interface. ICH_HCR_EL2 is set to one. ICH_VMCR_EL2 establishes virtual interface settings including split EOI behavior, while the guest writes two to ICC_CTLR_EL1. Classify settings by delivery, priority, and completion responsibilities rather than memorizing an unexplained hexadecimal constant.
bootstrap records HCR_EL2 as 0x80000019. In this lesson that configuration accompanies the AArch64 guest, stage-two setup, and physical IRQ routing to EL2. A pending virtual interrupt and the guest CPU's acceptance of IRQ are separate conditions. Inspect guest DAIF masking and priority settings as well. Successful injection does not by itself guarantee immediate entry into the guest handler.
Measured trace: setup into Pending
In the measured irqNormal run, GIC_READY records ICH_VTR_EL2 and ICH_VMCR_EL2 readback, and ENTER records HCR_EL2. INJECT then records INTID forty and LR0 equal to 0x5080000000000028. Its top two state bits encode Pending. Read the interrupt identifier separately from the state; the entire register is not simply an interrupt number.
Do not require the VMCR readback string to equal the expression written by setup. The recording observes 0xff4c020a and preserves that observation. The table's LR value comes from the captured run and can be compared with host-side encoding tests. Matching that arithmetic does not prove interface enablement or actual exception delivery, which require the machine evidence.
| Observation | Measured value or interpretation | Meaning |
|---|---|---|
| GIC_READY | ICH_VMCR_EL2 = 0xff4c020a | Readback after setup |
| ENTER | HCR_EL2 = 0x80000019 | Conditions before guest execution |
| INJECT | INTID = 40 | Identifier to inject |
| LR0 | 0x5080000000000028 | State bits encode Pending |
Do not overwrite an occupied list register
The implementation uses LR0 for a small experiment rather than dynamically scheduling every available list register. virtual_irq_lr checks that the identifier is at most 1019 and the current state bits are Invalid. Writing over Pending or Active state would lose an unfinished delivery. Availability is determined from the state field, not by requiring every bit of the register to be zero.
The normal case injects forty into a free LR0. Boundary encoding tests cover zero and 1019; special identifiers starting at 1020 are rejected. Passing admission does not configure every device associated with an identifier. Failure cases supply an occupied LR0 or a reserved identifier and verify rejection before hardware mutation. Read this as preservation of an existing request, not merely an error message.
Runnable Rust: encoding and admission contracts
This standalone host program extracts the admission rule from the distributed lib.rs. It compiles as ordinary Rust without accessing AArch64 system registers. It combines priority, Group one, Pending state, and identifier bits, then asserts boundaries and occupied-state rejection. Passing these assertions is not evidence that a hardware GIC register was accessed.
The final assertion accepts an LR value whose state is Invalid while other fields remain nonzero. Completion does not require every register bit to become zero. Reading the relevant masked field is a general register-programming technique. Combining pure host checks with QEMU measurements separates arithmetic mistakes from machine-configuration mistakes and gives each claim an appropriate form of evidence.
#[derive(Debug, PartialEq)]
enum Reject { ReservedId, Busy }
fn prepare(id: u64, lr: u64) -> Result<u64, Reject> {
if id > 1019 { return Err(Reject::ReservedId); }
if (lr >> 62) & 3 != 0 { return Err(Reject::Busy); }
Ok((1 << 62) | (1 << 60) | (0x80 << 48) | id)
}
fn main() {
assert_eq!(prepare(40, 0), Ok(0x5080_0000_0000_0028));
assert!(prepare(0, 0).is_ok());
assert!(prepare(1019, 0).is_ok());
assert_eq!(prepare(1020, 0), Err(Reject::ReservedId));
assert_eq!(prepare(40, 1 << 62), Err(Reject::Busy));
assert_eq!(prepare(40, 2 << 62), Err(Reject::Busy));
assert!(prepare(40, 0x1080_0000_0000_0028).is_ok());
println!("normal=0x{:016x} boundaries=ok", prepare(40, 0).unwrap());
}Do not diagnose setup from the final log alone
If a guest ACK never appears, possible causes include no pending LR, a disabled virtual interface, guest IRQ masking, or the wrong exception vector. Inspect INJECT and LR state first, then CPU and priority acceptance conditions, and finally the handler entry. Missing DONE does not immediately establish that entering EL1 failed.
The recorded masked case provides a control for Pending state held before acceptance. Compare LR and delivery count before and after the guest unmasks IRQ. This differs from disabling the physical timer interrupt. This lesson establishes admission and setup; the next IRQ lesson follows acknowledge, EOI, and deactivation. Separating entrance from completion makes an undelivered request distinguishable from an unfinished one.
Exercise: test identifier and state independently
Build a matrix using identifiers forty, 1019, and 1020 against Invalid, Pending, and Active states. Predict admission before running the host program and distinguish identifier rejection from occupancy rejection. Decode the identifier and state fields in the measured irqNormal LR and connect them to the encoding calculation instead of memorizing a long hexadecimal value.
Submit the complete QEMU command, referenced ELF hash, setup readback, injected LR, and presence or absence of guest ACK. Compare masked and normal recordings and explain why Pending can be accepted immediately or retained. If you only replay a recording, say so rather than claiming execution of edited source. Explaining the evidence boundary is part of understanding the setup.