# 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`:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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
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.