Goal: establish an exception-entry contract
Reaching EL2 at boot does not establish a path back from a guest. The vector location, exception stack, general-register frame, and Rust calling convention must agree before a handler can safely return a result. This lesson builds that entry path on top of the memory layout from the boot lesson. Establish it before entering the guest: an exception cannot wait for the program to finish installing its handler. The useful milestone is a justified transfer of control, not simply a register write that happened to execute.
The scope is EL2 initialization and synchronous exceptions arriving from a lower AArch64 exception level. Interrupt delivery, scheduling, and multiple vCPU contexts remain separate topics. Unsupported vector entries should follow an identifiable failure path rather than pretending to complete the expected operation. In the recorded source, follow the initialization function, vector entry, and Rust synchronous handler as one chain. At each boundary ask which registers are live, which stack is in use, and what must still be restored before return.
Read control registers by responsibility
VBAR_EL2 selects the vector-table base. HCR_EL2 controls important aspects of lower-level execution and virtualization. ELR_EL2 and SPSR_EL2 describe a return address and saved processor state. Their shared suffix does not make them interchangeable. In the distributed configuration, the guest executes AArch64 and stage 2 is enabled. Explain those choices as named fields and responsibilities rather than memorizing one large hexadecimal value. This makes a wrong configuration distinguishable from a wrong vector address.
A second responsibility is avoiding accidental dependence on reset values. Read the project’s initialization sequence for the lower-level state and instruction facilities used by the guest. Synchronization instructions are not arbitrary delays; they participate in establishing when changes to control or translation state can be relied upon. Before moving the same constants into another environment, check the CPU and machine assumptions. The experiment’s narrow configuration permits a small explanation, but it does not turn that configuration into a portable initialization sequence for every Arm platform.
| Register | Distributed setting | Responsibility |
|---|---|---|
| VBAR_EL2 | Address of vectors | EL2 vector base |
| HCR_EL2 | 0x80000001 | AArch64 EL1 execution and stage 2 |
| VTCR_EL2 | 0x80023559 | Stage-2 table format and input range |
| VTTBR_EL2 | Address of STAGE2 | Stage-2 table base |
Use the vector offset to identify the origin
An AArch64 vector table contains instructions, with entry selection depending on exception type and the state from which the exception arrived. The central entry here is a synchronous exception from a lower level executing AArch64, at base plus 0x400. It is different from a synchronous exception taken at the current level while using SP_ELx, at plus 0x200. Reaching some handler therefore does not by itself establish that the guest caused the event. Preserve the origin information while investigating a failure.
The table base must satisfy its 2 KiB alignment requirement, and entries have a fixed spacing. A long entry sequence must not spill into the next slot. A short branch into shared save code makes the layout easier to review than duplicating a full handler in every slot. Inspect the assembly alignment directives and labels, then verify the same relationships after linking. The important property belongs to the generated addresses, not just to the visual indentation of the assembly source.
Preserve guest values before calling Rust
General-purpose registers at exception entry belong to the interrupted guest. A register that an ordinary function call may clobber is not automatically disposable here: the guest did not voluntarily call the Rust handler. The assembly entry must preserve the required guest state before calling Rust, and its frame layout must match the Rust representation. Later MMIO emulation obtains the stored byte from that saved context, so a frame-layout error can produce plausible but incorrect device output.
Calling a logging function before preserving registers risks changing the very values being diagnosed. Keep the phases explicit: save, capture exception state, handle, restore. Treat ELR_EL2 and SPSR_EL2 as evidence needed before return or another exception can change the interpretation. Even when an unsupported exception ends in a stop loop, retaining the first fault’s values helps distinguish the initiating problem from a secondary fault encountered while printing or accessing a malformed frame. Diagnostics should not erase their own evidence.
Check entry classification independently
This standalone host program checks the two synchronous-entry classifications used in the lesson; it does not install a vector table. It classifies 0x400 as lower-level AArch64 and 0x200 as current-level SP_ELx, leaving other offsets unsupported. Apply the same discipline in the machine handler: establish the supported category before interpreting more specific fields. Turning every unknown value into a successful default can hide the first error and send debugging toward an unrelated stage.
The normal case is the lower-level synchronous entry. The boundary case is the distinct current-level synchronous entry. The failure case verifies that an IRQ offset is not silently treated as synchronous. Instruction placement and alignment still require artifact inspection and QEMU execution. A small host test fixes one explanatory rule; it is not evidence that the real machine used that rule. Write the scope of each check next to its result so the host test and the measured recording support complementary claims.
// Host-side classification of the synchronous entries used here.
#[derive(Debug, PartialEq)]
enum Origin { CurrentSpElx, LowerAarch64 }
fn sync_origin(offset: u64) -> Option<Origin> {
match offset {
0x200 => Some(Origin::CurrentSpElx),
0x400 => Some(Origin::LowerAarch64),
_ => None,
}
}
fn main() {
assert_eq!(sync_origin(0x400), Some(Origin::LowerAarch64));
assert_eq!(sync_origin(0x200), Some(Origin::CurrentSpElx));
assert_eq!(sync_origin(0x480), None);
}Follow the recorded synchronous exception
In the distributed normal run, EL2 initialization precedes EL1 entry, and the guest’s byte store causes a stage-2 translation fault. The lower-AArch64 synchronous entry preserves general registers and transfers control to Rust’s handle_sync. UART output is the consequence of accepting and emulating that store, not the reason the vector was entered. Match the ordering of captured log lines to the ordering of source calls. This is more informative than treating the entire exception path as one instantaneous box.
The recorded ESR_EL2 value is 0x93090045, whose exception class is 0x24: a Data Abort from a lower exception level. Establish that broad classification before interpreting its remaining fields. Later lessons inspect access size and address. At this stage keep three claims separate: execution reached the intended synchronous entry, the saved guest values were available to the handler, and the restoration path permitted return. Each claim has a different failure mode and should be tied to a distinct part of the source or trace.
Test the preservation contract
For the normal path, connect the guest store’s source register to the saved-frame field, then verify the guest-resumed milestone after handling. A useful boundary experiment adds diagnostic output without changing the preserved guest values. If logging alone changes behavior, investigate register preservation, stack capacity, and calling-convention assumptions. Return to the save-first, print-later rule rather than assuming the extra output merely altered timing. The exception boundary must be correct even when ordinary functions use their permitted scratch registers.
For a failure experiment, deliberately enter an unsupported path in a separate copy and verify that the normal completion marker is absent. Sending every unexpected case into one silent loop discards useful classification information. Combine identifiable failure diagnostics with strict success conditions in the surrounding test. The website’s replay demonstrates the published measured example; it does not grade a locally edited vector table. Keep a local transcript for your change and state exactly which preservation property or failure response the experiment tested.
Exercise: trace the saved frame in both directions
Walk from initialization through VBAR_EL2 setup, the lower-AArch64 synchronous entry, handle_sync, restoration, and ERET using the distributed function names and labels. Choose one general register and explain where its pre-exception value is saved, how Rust locates it, and which instruction restores it. Printing the expected UART character once does not prove that every other guest register survived. The exercise requires following the complete round trip for a concrete value, including the assembly-to-Rust representation boundary.
As an extension, design the diagnostic snapshot needed at exception entry and justify its capture order. Distinguish information that can safely wait until after another function call from values that must first be preserved. The next lesson uses ELR_EL2 and SPSR_EL2 for initial guest entry. The same registers also appear on exception return, so always identify which point in execution a value describes. A precise timeline prevents an initial configuration value from being mistaken for the state captured by a later fault.