dolphin/docs/Wii_Starlet_Bootstrap.md

Starlet Rust bootstrap in this Dolphin fork

This fork can load the Phase 01 Revolution IOS ELF directly into Starlet SRAM. The loader uses the ELF's two PT_LOAD segments, zeroes their uninitialized tails, starts the ARM core at 0xffff0000 in big-endian supervisor mode, and publishes REV_TRACE lines in the IOS log. No boot0, keys, or NAND dump is needed for the standalone probe.

Fast development loop

Build the Rust ELF from starlet-ios-rust:

cargo build --release

Configure this Dolphin fork with ENABLE_TESTS=ON, then build StarletBootstrapProbe. Run the build commands from an x64 Native Tools Command Prompt (or after vcvars64.bat). For the local MSVC configuration:

cmake --build .starlet_msvc2 --target StarletBootstrapProbe
powershell -NoProfile -ExecutionPolicy Bypass -File .\Run-Wii-Starlet-Bootstrap.ps1

The script defaults to the sibling Rust repository's release ELF. It prints every trace line, the stopping PC, and the ARM instruction count; it exits nonzero for a missing marker, fault, or invalid ELF. -JIT exercises the fork's ARM JIT.

To check the panic path without replacing the ordinary release artifact:

cd ..\starlet-ios-rust
cargo build --release --features panic-smoke --target-dir target/panic-smoke
cd ..\dolphin
powershell -NoProfile -ExecutionPolicy Bypass -File .\Run-Wii-Starlet-Bootstrap.ps1 `
  -ELF '../starlet-ios-rust/target/panic-smoke/armebv5te-none-eabi/release/revolution-ios-bootstrap' `
  -ExpectedOutcome Panic

To exercise a Rust fatal check and a synchronous ARM exception, derive two diagnostic ELF copies from the release artifact:

cd ..\starlet-ios-rust
py -3 tools/make_smoke_elf.py target/armebv5te-none-eabi/release/revolution-ios-bootstrap target/phase01-smoke
cd ..\dolphin
powershell -NoProfile -ExecutionPolicy Bypass -File .\Run-Wii-Starlet-Bootstrap.ps1 `
  -ELF '../starlet-ios-rust/target/phase01-smoke/fatal-data.elf' -ExpectedOutcome Fatal
powershell -NoProfile -ExecutionPolicy Bypass -File .\Run-Wii-Starlet-Bootstrap.ps1 `
  -ELF '../starlet-ios-rust/target/phase01-smoke/undefined-entry.elf' -ExpectedOutcome Fault

Each command also accepts -JIT and -FullDolphin. The fatal image changes only the loaded .data probe, producing REV:FATAL:DATA. The exception image replaces the reset branch with an undefined instruction; the fault record reports code 1 and raw LR/SPSR. Both passed in the standalone probe and full Dolphin, with interpreter and JIT, on 2026-09-23. The source release ELF remains unchanged.

The probe uses the actual ARMCore and StarletMemory implementations. It initializes the high SRAM mapping, runs 4096-cycle slices, checks __fault_code, and decodes REV_TRACE. It does not start Broadway, graphics, USB, or a Wii title. The two ELF parser unit tests run with:

cmake --build .starlet_msvc2 --target tests
.starlet_msvc2\Binaries\Tests\tests.exe --gtest_filter=BootstrapELFTest.*

Full Dolphin run

Set Dolphin.General.WiiStarletBootstrapELF to the absolute ELF path and Dolphin.Core.WiiIOSLLE=True. This bypasses the boot0/keys/NAND dump initialization in StarletMemory and starts the loaded program at its ELF entry. To run through DolphinNoGUI using the existing .starlet_user3 Wii profile:

powershell -NoProfile -ExecutionPolicy Bypass -File .\Run-Wii-Starlet-Bootstrap.ps1 -FullDolphin

This mode launches the Wii System Menu title only to initialize the full emulator; the Starlet runtime is the supplied Rust ELF. It uses the Null video backend and headless platform, reads new IOS log lines, and stops its own process after the expected marker. A populated Wii user profile is required for this full frontend path. The standalone probe is the reproducible path for the Phase 01 CPU and SRAM contract.

The accepted ELF is ELF32, big-endian ARM ET_EXEC, entry 0xffff0000, with exactly one executable segment at 0xffff0000 (up to 64 KiB) and one writable segment at 0xfffe0000 (up to 16 KiB). It must expose REV_TRACE, __fault_code, __fault_lr, and __fault_spsr in the data segment's loaded memory span. Rejected images never write to SRAM.

The Rust code reaches REV:BOOT:IDLE in both interpreter and JIT; the panic-smoke image reaches REV:PANIC, and the diagnostic images reach fatal and fault states. All four outcomes pass through the full DolphinNoGUI path. An initial incremental MSVC build crashed before the first slice because HW.cpp still allocated the old Starlet class size; AddressSanitizer identified the overflow. A forced rebuild fixed it, and Starlet::Create now keeps allocation in the same translation unit as the class definition. The CMake configuration also corrects a French MSVC /showIncludes prefix that made Ninja record zero header dependencies. After rebuilding HW.cpp, Ninja records Starlet.h as a dependency.