dolphin/docs/StarletOS_Handoff.md

# StarletOS integration handoff — 2026-10-03

This checkpoint publishes the existing emulator changes used by the companion
[StarletOS repository](https://git.yaya48.xyz/Yaya48/StarletOS). It is a recovered
source checkpoint, not a new claim that stock IOS or physical hardware is fully
supported. The Rust project's current phase is 10C, stock NCD probe H02B awaiting
SD staging and its physical result; consult its HANDOFF and phase reports.

## Published work

- The existing local commits c230971f07 (NAND conformance/diagnostic tools) and
  a8dbbab62d (SD CMD6/conformance report) precede this integration checkpoint.
- 16 modified files and 6 previously untracked files are now tracked here:
  ARM bootstrap ELF loader and tests, direct PPC/Starlet launch, read-only NAND
  and explicit disposable-copy support, diagnostics and regression runner,
  ARMv5TE LDRD/STRD handling, and the existing MSVC dependency-detection fix.
- `docs/StarletOS_Checkpoint.json` records SHA-256s of the 22 exact source files.
  The companion repository also pins the published Dolphin commit.
- Every runtime byte matches the source snapshot captured before publication.
  Only Git attributes, ignore rules and handoff metadata were added this turn.
- Inspection of 67 changed file versions in the two pending commits found no
  available private NAND key/content markers, device identifiers or credentials.
  The staged integration files were inspected separately before publication.
- No full rebuild, new emulator test or Wii test is claimed by this Git import.
  Historical qualification remains in the companion project's phase reports.

## Other computers

Clone this fork beside `starlet-ios-rust`, checkout the commit pinned in
`StarletOS/support/dolphin/manifest.json`, then follow the companion
`docs/DEVELOPMENT.md`. The previous private base bundle and source overlay are
no longer needed to retrieve these sources: their commits are on this server.
Use `docs/Wii_Starlet_Bootstrap.md` for the existing build and test runner.

NAND, keys, user profiles, traces and generated builds remain local/ignored.
The `.starlet_user3` profile is needed only for the full Menu scenarios; the
standalone Starlet bootstrap probe does not need a NAND or keys.
The old `.before-p10a-h07b` script is retained locally as an ignored backup.

## Future sessions

Read AGENTS.md. Record the starting commit, changed behavior, actual tests and
remaining work. Update this handoff and any changed file hashes, commit to this
fork, then update the pinned dependency in StarletOS. Never label a build, a
source comparison or a fake emulator device as a physical Wii observation.


## Linux qualification — 2026-10-03

Starting checkout: master `54f5a74bbf4e3be8418a3e98d006436c16a23e40`, clean;
fetch and fast-forward-only pull found no divergence. All recursive submodules
were initialized at their recorded commits. No runtime/source bytes changed;
this addition records the first build on the destination Linux PC.

- Debian 13 x86_64, GCC 14.2.0, CMake 3.31.6, Ninja 1.12.1. Release build in
  `.starlet_linux`: `StarletBootstrapProbe`, `dolphin-nogui`, `tests` succeeded.
  Qt, X11/EGL, desktop audio/input, LLVM disassembly and optional integrations
  were disabled; headless and tests enabled. The complete configuration is in
  the companion `docs/LINUX_QUALIFICATION.md`. This is not a GUI qualification.
- 95 selected tests of bootstrap ELF loading, ARM execution, SRAM, DMA,
  timer, register and IPC behavior passed. Google Test also reports two
  existing disabled tests; they were not enabled. The rest of Dolphin's
  unit suite was not run.
- Ten standalone bootstrap runs passed: idle, panic, fatal data, undefined
  instruction and Phase 02 self-test, each in interpreter and JIT. Rust used
  the companion's pinned nightly-2026-09-20. The Phase 02 trace still says
  IRQ delivery deferred and timer flag relatch untested; no hardware inference.
- SHA-256 of Linux `StarletBootstrapProbe`:
  `a536e5125c193d3ae23f3a5028e2f34df0359785d86191500c65ce7bcd9610f9`.
  Tests: `6acf5f26206e5afee2b3fbe3fd149b7c7c4dcd1f035d4dc12b89193df1d13a6f`.
  NoGUI: `bd0f9420428f07a1c8785c131f430cc0f9eed88a5723e2e56546291fa3b72544`.
- Logs are private/local in companion `target/linux-qualification-20261003/`;
  their hashes and commands are summarized in its public traceability report.
  All 22 pinned integration file hashes still match. The private Menu profile
  and NAND were not used or modified by these standalone tests. No full Menu
  replay or physical Wii test is established by this build.

Next: use the companion handoff. Stock-IOS H02B has now been copied to the
identified SD and verified after remount; the console result is pending.
Rebuilding its PPC binary under Linux remains unqualified (the exact devkitPro
packages could not be downloaded: HTTP 403). Preserve the archived probe.
This documentation commit changes the dependency pin, not the built code;
the executables above still report their build's original commit.


## Phase 11 IPC trace for the original IOS — 2026-10-06

Starting checkout: master `78738093ece433e9198213f91d43a3a0d60e3fa2`, clean;
fetch found no divergence. Companion: StarletOS Phase 11 proposal L2
(`docs/PHASE11_PROPOSAL.md`), approved by the user.

- `Source/Core/Core/HW/WII_IPC.cpp`: with the environment variable
  `DOLPHIN_IPC_TRACE=1` and the original IOS running on the emulated Starlet
  (`WiiIOSLLE`), every request Broadway posts (PPCCTRL X1) is logged as
  `IPCTRACE RQ <addr> C <command> FD <fd> A <five argument words>` (an OPEN
  adds ` P <path>`), and every reply Starlet posts (ARMCTRL Y1) as
  `IPCTRACE RP <addr> C <original command> RC <result>`. Notice level, `WII_IPC`
  log type. Metadata only: buffer contents are never read. Without the
  variable, or in HLE mode, nothing changes.
- The file is now an exact integration file (`.gitattributes -text`, hash in
  `docs/StarletOS_Checkpoint.json`, 23 files).
- Build: `.starlet_linux` `dolphin-emu-nogui` and `tests` rebuilt; the 95
  selected Starlet tests (filter in the companion `docs/LINUX_QUALIFICATION.md`)
  passed.
- Emulation smoke run (supporting evidence only, private log in the companion
  `target/phase11/l2/`): headless, Null video, the companion's Phase 10C NAND
  read-only behind a private profile's COW journal, original boot chain to the
  System Menu for 5 minutes: 74342 requests and 74337 replies traced (5
  asynchronous requests still pending at the stop).
- Limitation: this Linux build has no window platform (X11 disabled; the
  system lacks the `xi` development package), so no one can point and click in
  it yet. A separate X11 build directory is the next step once `libxi-dev` is
  installed; the qualified headless build stays unchanged.

Next: the companion's Phase 11 L2c (the user launches the Mii Channel from the
Menu in a window with the trace on); analysis stays in the companion.

## X11 window build and the reference launch — 2026-10-06

No source change. The user installed `libxi-dev` and `libxrandr-dev`; a
separate build directory `.starlet_linux_x11` (the qualified options with
`ENABLE_X11=ON`, tests off) built `dolphin-nogui` in 2 min 53 s
(SHA-256 `a7d372f47e7265a4ebe20c71bde6f8dd63f22416b422551b960f526a604ebda4`).
The qualified headless `.starlet_linux` build is unchanged. On KDE Plasma
Wayland the window runs through XWayland (`-p x11`, Vulkan); the emulated
Wii Remote reads the mouse through XInput2.

Companion session L2c (emulation, supporting only): original boot chain and
IOS80, the companion's Phase 10C NAND read-only (hash unchanged after), no
Ethernet NAT; the user launched the Mii Channel from the System Menu and it
started. The `IPCTRACE` log shows ES LAUNCH right after the WiiConnect24
shutdown request; analysis is in the companion's Phase 11 STATUS (finding 9).

Known limit for the next companion step: in bootstrap (Revolution) mode the
emulated Wii Remotes are not initialized (`m_initialized` stays false), so
nobody can point at a channel there. Changing that is proposed in the
companion (proposal M1), not done.

## Emulated Wii Remotes for a Revolution session — 2026-10-06

Companion proposal M1 (approved by the user): replay the reference launch
with Revolution instead of the original IOS, to see where Broadway stops.

- `REV_BOOTSTRAP_WIIMOTE=1` (bootstrap-ELF mode, after the NAND and keys
  attaches): `StarletMemory::EnableBootstrapWiimotes` selects the identities
  paired in the attached NAND's SYSCONF (`BT.DINF`, decrypted with the keys)
  and creates the emulated Wii Remotes exactly as the original-IOS mode does.
  `InstallEmulatedWiimotePairings(false)` never rewrites SYSCONF: without a
  paired identity the remotes keep their default addresses. Without the
  variable nothing changes (the remotes stay absent, as before).
- Checkpoint hashes updated for `Starlet.cpp`, `StarletMemory.cpp`,
  `StarletMemory.h`.
- Build: `.starlet_linux` (`dolphin-emu-nogui`, `tests`) and
  `.starlet_linux_x11`; the 95 selected Starlet tests passed.
- Without the variable, the companion's headless P11-H06 Menu regression
  (`tools/regression/phase11_menu.py --step H06 --outcome Phase9Running
  --timeout 600`) still passes on this build, NAND source and disposable
  copy identical.

Next: the companion's M1b (smoke test with the variable, no window) and M1c
(the user launches the Mii Channel under Revolution in the X11 window).

## Filesystem paths in the IPC trace — 2026-10-06

Companion proposal M1e (approved): under Revolution in the window the System
Menu's save before a launch got -106 on its second CREATE_DIR, and no trace
had the path. `IPCTRACE RQ` lines now end with ` F <path>` for IOCTLs whose
input is a 64-byte path (DELETE, GET_ATTR), a 76-byte attribute record (path
at +6: CREATE_DIR, CREATE_FILE, SET_ATTR) or two paths (` F a > b`, RENAME),
and for IOCTLVs whose first input vector is 64 bytes (READ_DIR, GET_USAGE);
` F -` when that field holds no valid path. Read from memory when X1 is
rung, like the OPEN path; nothing else of the buffers. Checked headless under
Revolution: `/shared2/test2`, `/title/00000001/00000002/data/cache.dat`, the
GET_USAGE directories. 95 Starlet tests passed.

## Write watch for Starlet memory — 2026-10-06

Companion proposal F1 (approved): find what changes Revolution's RAM layer
table between two filesystem requests (the companion's finding 11).

- `REV_WATCH=start:size[,start:size...]` (hexadecimal, physical): every
  Starlet CPU store (`StarletMemory::Write8/16/32`) and every device DMA
  write (`WriteDMABuffer`, `WriteDMA8`) touching a range is logged as
  `REVWATCH CPU addr/size value PC <instruction> LR <r14>` or
  `REVWATCH DMA addr/size PC <instruction>`. Off without the variable.
- The ARM JIT keeps fastmem; `ARMBus::GetWatchRanges` gives it the ranges,
  `EmitFastmemAddress` sends any access overlapping one to the existing bus
  slow path, and the ARM and Thumb slow paths store the instruction address
  first (only while watching). Speed under watch is the JIT's (companion
  smoke run: the Menu's main menu at 74 s, as without the watch).
- `ARMCore.h` (`GetInstructionAddress`, `GetWatchRanges`), `ARMJitX64.cpp`,
  `ARMJitX64.h` are now exact integration files (26 in the checkpoint).
- The 95 selected Starlet tests passed (`.starlet_linux`); `.starlet_linux_x11`
  rebuilt. Smoke run with the companion's Revolution P11-H06: 1519 watched
  writes on its layer table during start-up, attributed by instruction.

## Shadow comparison for the write watch — 2026-10-06

Companion proposal H1 (approved). The companion's diagnostic image showed
its kernel reading back, from its RAM layer table, an entry different from
the one it had just written, with no other Starlet store or device DMA seen.

- With `REV_WATCH`, `StarletMemory` keeps a shadow of each range, updated by
  the Starlet stores and device DMA it logs. A Starlet read whose bytes differ
  from the shadow logs `REVWATCH DIFF addr/size read … expected … PC … LR …`
  (another writer changed them: Broadway, its GPU, the DSP…); each IPC reply
  (ARMCTRL Y1) audits the ranges (`REVWATCH AUDIT addr+len now …`, at most 16
  runs per reply). The shadow then adopts the new bytes.
- Register-list transfers whose virtual range overlaps a watched range now
  take the JIT's architectural helper, and the interpreter logs
  `REVWATCH LDM|STM virtual->physical/size PC …` (its own translation).
- `ARMCore.cpp` keeps its CRLF bytes. 95 Starlet tests passed. Companion
  smoke run (P11-H06D, 150 s): no DIFF, no AUDIT, 9 LDM with identical
  virtual and physical addresses.

## ARMv5TE enhanced DSP instructions — 2026-10-06

Companion proposal I1 (approved). The companion's Revolution kernel computes
table addresses with `smlabb`; the ARM926EJ-S executes it, but
`ARMCore::ExecuteARM` had no case for the ARMv5TE enhanced DSP instructions,
so `smlabb` fell into data processing as `TST` (no destination written, flags
changed). The kernel then read the wrong RAM-layer entry and refused a
creation -106 ("system files corrupted" in the System Menu), in the fork only.

- `ARMCore::ExecuteEnhancedDSP`: SMLAxy, SMLAWy, SMULWy, SMLALxy, SMULxy,
  QADD, QSUB, QDADD, QDSUB, with the sticky Q flag (ARM Architecture
  Reference Manual semantics), decoded before the generic decoders.
- `CanEmitARMDataProcessing` excludes these encodings, so the JIT leaves them
  to the interpreter.
- Test `StarletARMCore.ARMv5TEEnhancedDSPInstructions`: eleven encodings from
  GNU as (`-march=armv5te`), interpreter and JIT, results, Q and NZCV
  untouched. 96 selected Starlet tests passed.
- The companion's images use, besides these (16 `smlabb`, 4 `smulbb`), only
  `blx`, `clz`, `ldrd`, `strd` among the ARMv5TE additions; those were
  already handled.

## Broadway hardware window after the WiiConnect24 shutdown — 2026-10-06

Companion proposal J1 (approved). With the DSP fix, the companion's System
Menu under Revolution reaches ES LAUNCH in the fork, while on the console it
stops right after the WiiConnect24 shutdown reply (IOCTL 0x28), with no IPC
until then. This lists what Broadway touches in that gap.

- `DOLPHIN_HW_WINDOW=1` (with `DOLPHIN_IPC_TRACE=1`): the IPC trace remembers
  an IOCTL 0x28 with 32-byte input and output; its reply opens a window, and
  `MMU::ReadFromHardware`/`WriteToHardware` log each Broadway MMIO access as
  `HWTRACE R|W address/size value PC` until Broadway's next IPC request (or
  20000 accesses). `IsOptimizableMMIOAccess` returns 0 while requested, so the
  JIT inlines no MMIO read. Nothing changes without the variables.
- `MMU.cpp` and `WII_IPC.h` are now exact integration files (28).
- 96 Starlet tests passed; both builds rebuilt.