xenia-rs/HANDOFF-intro-video-done.md

Handoff — Intro video SOLVED (iterate-4A/apu-xma-stage1, tag intro-video-done)

The original frontier — why dat/movie/ADV.wmv never played vs Xenia Canary — is solved. The intro renders authentically: white SQUARE ENIX logo + cyan glow + red diamonds on a near-black background, correct color / geometry / luminance, playing reliably. This doc is the handoff for that state and the newly-opened emulator-speed frontier.

Method (unchanged): first-divergence vs canary · fix causes not symptoms · NO masking · measure the oracle, never infer. Full setup for this branch is in HANDOFF-iterate-4A-milestone2.md (FFmpeg dev libs, DuckDB tooling, etc.) — read that first on a fresh machine.

---

0. What to push / copy for handoff

Git (the only repo): xenia-rs/. Branch iterate-4A/apu-xma-stage1, 6 commits ahead of origin.

cd xenia-rs
git push origin iterate-4A/apu-xma-stage1      # the 6 commits below
git push origin intro-video-done               # the annotated milestone tag (-> 5573ac1)

Not in git (machine-local — copy manually for a full-context handoff):

• ../CLAUDE.md — project working instructions (project root is NOT a git repo).
• ~/.claude/projects/-home-fabi-RE---Project-Sylpheed/memory/ — the auto-memory (MEMORY.md index + topic files). This is where the detailed step-by-step history lives.
• Large local artifacts (NOT pushed): the real ISO (sylpheed.iso symlink target), sylpheed.db (DuckDB static-analysis DB, ~1h35m to regenerate — see CLAUDE.md), canary build.

---

1. Commits on this branch (ahead of origin)

Commit	What
645feb8	ROOT #1 decode-timeout clock (IPM 10k→1M), #1b feeder starvation (incumbent-pick), #2 k_8 texture decoder
4344152	re-baseline boot golden 50M→200M after the clock fix
3559c8f	ROOT #3 host render path — multi-texture YUV, tfetch dest-swizzle, PS const-bank +256
deb9292	RectangleList quad completion (fix diagonal seam)
5573ac1	MULSC/ADDSC/SUBSC scalar-const operand addressing (fix squared-luma) — tag intro-video-done
2c883e9	diagnostics snapshot: XENIA_PROFILE profiler + probe/tooling (this handoff)

Working tree is clean — all diagnostics/tooling are now committed in 2c883e9.

---

2. Build & run (see CLAUDE.md for the authoritative version)

cd xenia-rs
export CARGO_BUILD_JOBS=4 && cargo build --release          # ~8s incremental
# Headless oracle run (threaded GPU, single-thread CPU lockstep):
RUST_LOG=warn ./target/release/xenia-rs exec sylpheed.iso -n 3000000000
# Watch the movie (windowed): add --ui ; the first on-screen frame is at ~81s WALL
# (mostly boot). Give it >=150s. Boot is DETERMINISTIC; only wall speed varies.

Movie oracles: sylph-run.sh [runs] [n] [timeout] (default 180s). Static analysis: zq.py over sylpheed.db (DECIMAL bounds, never 0x). Both are committed at repo root now.

---

3. Root-cause summary (the fixes)

• #1 clock deadline — movie handler sub_821B4968 has a 2000 ms decode-ready timeout; INSTRUCTIONS_PER_MS 10k ran ~320× too fast so a legit 720p decode looked timed-out → abort. Fixed to 1_000_000 (state.rs; XENIA_INSTR_PER_MS overrides).
• #1b feeder starvation — co-located feeder tid24 lost the equal-priority rotation; pick_runnable now has an incumbent-preference tiebreak (scheduler.rs; XENIA_INCUMBENT_PICK).
• #2 k_8 decoder — the movie uploads YUV planes as linear k_8; added decode_k8.
• #3 host render path — multi-texture (8 YUV slots), tfetch 12-bit dest-swizzle, PS constant bank +256 (Xenos splits VS 0..255 / PS 256..511), RectangleList quad synthesis (v3=v0+v2−v1), and MULSC operand addressing (src3, not src_a/src_b). Details: memory topic file STEPs 88→97.

---

4. Open frontier — emulator SPEED (profiled, not yet worked)

Playback is slow (~14–19 fps). First quantified profile (XENIA_PROFILE=1, headless):

• Effective ~35 MIPS overall (3 B guest instr / 86 s clean).
• Interpreter body ~40% @ ~95–102 MIPS; kernel HLE ~4%; block-cache lookup ~5–6%; texture decode 0.3% (cache works — not a bottleneck); present ~0%; no default IPS throttle.
• The rest is per-block dispatch + scheduler plumbing — ~13 instr/block over ~229 M blocks, each paying fixed prologue/epilogue/lookup/borrow costs. Overhead-bound, not interpreter-body bound. (Note: default run is single-thread lockstep run_superblock, confirming the "serialized single-core" architecture; the console's 6 HW threads are time-sliced onto one host thread. --parallel exists but is not validated for the movie.)

Ranked levers:

1. Coarsen the execution unit — longer superblock chains (raise superblock_budget). Cheap, reversible, targets the dominant overhead. ⚠️ chaining is also the scheduling lever (can starve the movie subsystem — validate against the oracles). Start here.
2. JIT / block-recompiler — collapses both the interpreter body and per-block dispatch; the real ceiling (~5–10×), but a multi-week subsystem.
3. True multi-core (guest threads on separate host threads) — huge for a 6-thread workload but riskiest: would invalidate the IPM=1M + incumbent-pick timing fixes that made the video work.

Caveat for the next session: precise remainder attribution needs a sampling profiler (perf_event_paranoid=4 blocks perf without sudo here; gdb ptrace_scope=1 blocks non-descendant attach). The XENIA_PROFILE coarse timers are the current best tool and are now gated zero-cost when off.

---

5. XENIA_PROFILE quick reference

XENIA_PROFILE=1 <run> → periodic snapshots (every 500 M guest instr, or every 500 presents) + a clean-exit report on stderr. Buckets: interp step_block, kernel HLE call_export, block decode/cache lookup_or_build, texture decode, host draw, present, and the unaccounted remainder. Zero-cost when unset (cached is_on() gate). Source: crates/xenia-gpu/src/prof.rs.