Goal: distinguish a guest entry from a branch
A normal branch to a guest function address does not change execution into the EL1 environment. The distributed project prepares a return address and return state at EL2, then uses ERET to enter EL1h. Your goal is to explain the starting address, exception level, stack selection, and interrupt masks as one execution contract. An entry point is not just a number: the surrounding machine state determines how the first instruction and its memory accesses will behave.
The EL2 vectors and saved-register frame must already be ready. After guest entry, HVC transfers control back to EL2 and the handler returns to the guest’s subsequent instruction. Later, a stage-2 Data Abort is emulated and execution resumes. HVC and Data Abort are different exception classes, even though both can be described informally as guest exits. Keep their saved return-address semantics and the handler’s responsibilities separate. A correct return rule for one category can be wrong for the other.
Establish three values for initial entry
ELR_EL2 receives the guest_main address. SP_EL1 receives the top of the guest stack. SPSR_EL2 describes the PSTATE to restore. In this project, SPSR_EL2 is 0x3c5: its mode selects EL1h and its DAIF fields mask asynchronous exceptions. This supports a small, synchronous experiment; it is not a completed interrupt configuration for a full guest operating system. Interpret the initial state before deciding which fields a future interrupt-enabled extension would need to change.
EL1h selects EL1 with SP_EL1. Entering EL1t or EL0 requires a different contract, not simply a different function name. The entry address must also reside in executable guest-reachable RAM, and the stack must be reachable through the active memory regime. Individually plausible register values can still form an invalid combination. For example, an unreachable SP_EL1 can fault in the first function prologue. Check the register setup against the translation configuration instead of reviewing those two parts of the program in isolation.
| State | Initial-entry setting | Meaning |
|---|---|---|
| ELR_EL2 | Address of guest_main | First instruction after ERET |
| SP_EL1 | __guest_stack_top | Top of the guest stack |
| SPSR_EL2 mode | Low mode 0x5 within 0x3c5 | EL1h using SP_EL1 |
| SPSR_EL2 DAIF | 0x3c0 | Asynchronous exceptions masked in this experiment |
| Measured GuestCurrentEL | 0x4 | The CurrentEL encoding confirms EL1 |
Include HCR and stage 2 in the entry contract
The distributed HCR_EL2 value is 0x80000001, selecting lower-level AArch64 execution and stage-2 translation. Stage 2 still matters when this guest leaves its stage-1 MMU disabled. Do not infer that disabling EL1 stage 1 grants direct access to every host physical address. Guest code and stack accesses must remain reachable through the stage-2 mapping. The entry contract therefore includes the translation tables and control settings already installed at EL2.
The UART IPA is deliberately absent from that mapping, while the RAM containing the guest remains accessible. This allows guest instructions to run normally but brings a UART store into EL2 for emulation. The contrast gives stage 2 a concrete role: distinguishing reachable memory from an address whose operation the hypervisor intends to handle. The teaching project uses a coarse RAM block to keep the example inspectable. It is not a finished memory-isolation policy for several mutually untrusted guests, and the one-guest success trace should not be used to claim that broader property.
Separate initial entry from exception return
For first entry, EL2 deliberately constructs ELR_EL2 and SPSR_EL2. After an exception, the processor supplies return information according to the exception category. The handler must decide whether to retry the interrupted operation, continue after an emulated operation, or stop because the event is unsupported. “Add four to the PC on every exception” is not a valid general rule. Classify the event and decide what the handler actually completed before changing the saved return address.
This project uses HVC as an observation mechanism for guest entry, resumption, and completion. Its saved return address already identifies the instruction following the call, so the HVC path does not add another four bytes. A UART-store Data Abort instead points at the faulting operation; after successful emulation the handler advances ELR by four so the store is not repeated. Read the two paths side by side. Their different rules show why exception return is a policy decision supported by architecture-specific semantics, not a generic jump back.
Check return state and PC updates on the host
The standalone Rust program below separates the mode and mask fields of the project’s initial 0x3c5 state, then checks a PC update after a known AArch64 operation has been emulated. The function name states that precondition. This makes accidental reuse on the HVC path easier to notice during review. The arithmetic result being four bytes later is only part of the argument; the handler also needs evidence that it completed the operation represented by the faulting instruction.
The normal cases verify EL1h selection and DAIF masks. A boundary case exercises an address near the integer limit, and the failure case rejects overflow. This host code does not execute ERET. It fixes the interpretation of selected bits and the arithmetic policy. Evidence of real EL1 execution comes separately from the project’s QEMU run and its lower-level HVC exception. Keeping these claims separate avoids presenting a host assertion about a number as proof of a processor transition.
// Host-side checks of this project's initial EL1h state and PC policy.
fn after_emulated_a64_store(pc: u64) -> Option<u64> { pc.checked_add(4) }
fn main() {
let initial_spsr = 0x3c5u64;
assert_eq!(initial_spsr & 0xf, 0x5); // EL1h
assert_eq!(initial_spsr & 0x3c0, 0x3c0); // DAIF masked
assert_eq!(after_emulated_a64_store(0x1000), Some(0x1004));
assert_eq!(after_emulated_a64_store(u64::MAX - 3), None);
let hvc_return_pc = 0x2004u64;
assert_eq!(hvc_return_pc, 0x2004); // HVC path keeps its saved ELR.
}Pair the recorded entry with resumption
The recording prints ENTER with the guest entry address and SPSR_EL2, followed by GUEST_ENTERED from the guest’s HVC path. The first line proves preparation reached its logging point; the second supplies evidence that the guest instruction stream actually ran. Check both instead of equating an announced intention to enter with successful execution. Concrete ELR addresses depend on the recorded build and placement, so interpret them alongside the attached source and image identity.
After the UART-store exception is accepted, RESUME prints the updated ELR, and GUEST_RESUMED arrives through a subsequent guest HVC. This pairing distinguishes displaying a proposed return address from actually reaching the guest’s next observation point. The short successful path still does not test an interrupt-enabled operating system or return after arbitrary instructions. State the claim attached to each milestone. A small but well-supported claim is more useful for debugging than an expansive success label with unclear boundaries.
Separate entry failures from emulation failures
The normal path checks ENTER, GUEST_ENTERED, the UART trap, RESUME, and GUEST_RESUMED in order. A milestone that stops after guest entry allows the entry and HVC-return contract to be inspected before adding MMIO emulation. This is a diagnostic decomposition, not a way to call an incomplete feature complete. Locate the earliest contract that stopped holding. A failure before entry demands different evidence from a failure after the guest has already reached its observation call.
An unsupported-width UART store provides a useful failure path: guest entry succeeds but emulation is rejected. GUEST_ENTERED is present while GUEST_RESUMED is absent. The handler must not advance the rejected operation merely to produce a success-looking trace. When changing the local project, specify milestones that must be absent as well as those that must appear. A test that searches only for an early success string can miss a later rejected access or an incorrect return path.
Exercise: compare two exception-return policies
Read enter_guest and handle_sync, then make a table for initial entry, HVC, and the MMIO Data Abort. For each row identify who supplies ELR_EL2, whether the handler changes it, and which instruction should execute next. Connect the three policies to concrete log lines: a deliberately configured initial address, the next-instruction address supplied for HVC, and the handler-advanced address after emulation of the aborted store. Explain the ownership of the value rather than simply copying its hexadecimal representation.
For an extension, predict two separate mistakes before testing them in independent working copies: adding four on the HVC path, and failing to add four after successful MMIO emulation. Observe which milestones disappear and whether the same fault repeats. These changed runs are new experiments, not the published recording. The next lesson inspects the MMIO acceptance checks in detail. It establishes when the handler has actually earned the right to advance the PC, and when rejection must leave that operation uncompleted.