Goal: account for the work before Rust
A hosted Rust executable receives substantial help before its application code runs. An operating system loads the image, establishes an execution environment, and eventually transfers control through runtime startup. Our small hypervisor has no operating system underneath it. Start your investigation before the first Rust function: identify who supplies the initial program counter, where the first stack comes from, and which memory already contains initialized bytes. The goal is to justify the first log line rather than treating a successful function call as an unexplained starting condition.
The experiment uses one CPU and one EL1 guest on QEMU’s Arm virt platform. It is a deliberately small bare-metal program, not a Linux-capable general hypervisor. The website replays a measured run together with its source and configuration. Editing that source requires rebuilding and running the downloadable project locally. Keep these activities distinct: moving a replay slider examines existing evidence; running the project creates new evidence. That distinction becomes especially useful when comparing two builds that print similar messages.
Separate the ELF entry from the load location
A linker script assigns addresses to the combined code and data that originated in object files. Its entry symbol identifies where execution begins; a section’s placement identifies where bytes and storage belong. These are related but different decisions. Loading an ELF image through its loadable segments also differs from placing a raw binary at a fixed address. Inspect the command and image distributed with this project as a pair. Do not borrow an address from a tutorial that uses a different loading convention and assume it describes this build.
Source order alone does not prove final placement. Section collection, garbage collection, explicit retention of startup code, alignment, and linker-defined boundary symbols all affect the result. Inspect the built image’s entry address and loadable ranges, then confirm that the entry falls inside executable memory. Treat the binary checksum as part of the experiment: identical text in two console logs does not establish that the same executable ran. This discipline lets a later linker change be investigated without confusing it with a change in CPU exception behavior.
Keep the stack separate from static storage
The startup code installs the first stack. Reserve an actual interval, preserve the alignment required by the AArch64 calling convention, and check that its range does not overlap code, BSS, translation tables, or guest storage. A downward-growing stack occupies addresses below its top. Checking only that the top looks unused misses the most important collision. Budget for exception frames as well as ordinary function calls, because an exception can arrive while a Rust function already has local values on that stack.
The EL2 stack and the EL1 guest stack have different owners. Reusing the same memory may appear to work until guest activity overwrites a frame that the exception handler needs to restore. Make an ownership table for every reserved interval. Separate temporary call frames from persistent CPU context, and distinguish guest-accessible memory from storage reserved by the hypervisor. A future multi-CPU version would need per-CPU stacks too; the single-CPU experiment does not silently establish that more complicated allocation policy.
| Region | Distributed purpose | Boundary to check |
|---|---|---|
| .text / .rodata / .data | Code and initialized data in one host-and-guest ELF | Entry 0x40080000 and loadable ranges |
| .bss / STAGE2 | Zero-initialized storage and a 4 KiB-aligned table | __bss_start through __bss_end |
| EL2 stack | 32 KiB reserved, including exception frames | __host_stack_top and downward-used interval |
| EL1 stack | A separate 16 KiB reservation | __guest_stack_top and non-overlap with host storage |
Understand BSS and the no_std boundary
Initialized data and zero-initialized storage make different demands on the loader and startup code. Inspect how this project’s loading path and startup sequence establish each range before a Rust static is read. A type-correct program still depends on the machine state matching its assumptions. Linker-defined BSS boundaries provide a useful check: their difference should match the intended reserved region, and initialization should cover that interval without touching adjacent guest or stack storage. An off-by-one error here can masquerade as a later exception bug.
Using no_std removes reliance on the hosted standard library; it does not supply an entry point, panic policy, allocator, or UART driver. A small fixed-memory experiment can avoid introducing a heap and keep its initialization obligations visible. Define how panic and unexpected boot conditions are reported. A wait loop is a reasonable terminal action for this teaching image, but the surrounding test must recognize the absence of a success marker. An image that merely remains alive is not necessarily an image that initialized successfully.
Run a placement check on the host
The following standalone Rust program demonstrates an interval check; its illustrative addresses do not replace the project’s linker constants. Half-open intervals allow one region to end exactly where another begins. Checked addition matters before comparison: an oversized length that wraps around could otherwise make an invalid region look small and harmless. Keep the host-side rule simple enough to inspect, then feed it the boundaries extracted from a real build when extending the project’s verification tooling.
The normal case has adjacent non-overlapping ranges. Boundary cases include an aligned stack top and an empty interval; failure cases include overlap and arithmetic overflow. Passing this check does not prove correct EL2 entry or valid translation descriptors. It proves a narrower property that should be established before machine execution. Failing early is valuable: a placement error found on the host need not become a mysterious exception after boot. Build a testing ladder whose claims grow only when additional evidence has actually been collected.
// Independent host-side placement check; no machine execution.
fn end(base: u64, size: u64) -> Option<u64> { base.checked_add(size) }
fn disjoint(a: (u64,u64), b: (u64,u64)) -> bool {
a.1 <= b.0 || b.1 <= a.0
}
fn main() {
assert_eq!(end(0x4000, 0x1000), Some(0x5000));
assert!(disjoint((0x4000,0x5000), (0x5000,0x6000)));
assert!(!disjoint((0x4000,0x5001), (0x5000,0x6000)));
assert_eq!(end(u64::MAX, 1), None);
assert_eq!(0x6000u64 % 16, 0);
}Trace a recording back to its artifact
Before interpreting a boot recording, inspect the QEMU version, versioned machine name, CPU model, memory size, CPU count, and complete invocation. The unversioned virt name can evolve across QEMU releases. Reuse the versioned machine and arguments attached to the distributed recording, and record deliberate changes as experimental inputs. A slower host may take longer to produce a line without changing the architectural event sequence. Avoid mistaking wall-clock variation for a different guest execution path.
Connect the source commit or file hashes to the binary hash and captured UART output. This chain makes a statement such as “changing this instruction changed boot” reviewable. Highlighted source lines in the website refer to the recorded source version; the same line number in a different revision may identify unrelated code. For a local reproduction, retain source, build command, image, and console output together. Compare explicit milestones and values rather than declaring success merely because both runs eventually displayed a familiar word.
Test normal, boundary, and failure paths
For the normal path, build the unchanged distributed project and verify its entry-level and EL2-initialization milestones. For a boundary experiment, add a small static allocation immediately next to a reserved region and inspect whether the intended gap survives linking. Do not choose a production stack capacity by guesswork. Account for exception frames and ordinary call depth, and investigate the first corrupted object if a larger stack makes a failure disappear. Accidental success is a clue, not an explanation.
Create failure experiments in a separate working copy. Break one alignment or non-overlap invariant and verify that the build or placement check detects it. A targeted violation teaches more than arbitrary changes that only produce a blank console. Reading completion, website question scores, and self-reported local implementation completion are separate records. When reporting a local milestone as complete, retain what you built and what you observed. The website cannot infer the correctness of an unsubmitted local image from the fact that an article was opened.
Exercise: explain the path into EL2 initialization
Build a range table from the distributed linker script and startup source: entry, executable code, BSS, EL2 stack, and EL1 stack. List the conditions that must hold immediately before the first Rust function and connect each condition to the instruction or linker rule that establishes it. Mark which claims came from static artifact inspection and which were observed in QEMU. The exercise is not complete when addresses have merely been copied; identify the source decision responsible for each value.
For an extension, add a small data region and predict the changes to boundary symbols, image hash, and console milestones before rebuilding. Investigate any disagreement at the compiler, linker, loader, or execution stage where it first appears. The next lesson places EL2 exception handling on top of these foundations. Successful boot and successful exception return are separate milestones: neither should be inferred from the other. Keep the same evidence chain so later failures can be traced back to a known starting configuration.