Debugging

Debugging

Use a bounded, evidence-first loop. Reproduce the symptom, identify the earliest divergence, and fix the owning layer rather than adding a route-specific latch or forced success.

A practical loop

1. Reproduce deterministically with the smallest supported route.
2. Decide whether the first divergence is in guest input/state, translation, HLE/runtime, renderer, audio/media, or host integration.
3. Inspect the generated source only as an output of the current generator and input manifest.
4. Compare the production path with a source-owned synthetic or reference-interpreter case.
5. Validate output pointers, lengths, return values, and failure paths before looking at the final visual/audio symptom.
6. Add a focused regression that fails before the fix and passes after it.
7. Re-run the focused gate, then the aggregate and publication checks.

Useful diagnostics

The maintained debugging guide documents categories and profiles. Examples include:

$env:SR_DEBUG = "0x03"
$env:SR_DISPATCH_FATAL = "1"

Use the manager profiles where possible. Many legacy Boolean SR switches are presence-based: setting a literal 0 can still enable them, so remove the variable to disable it. Keep logging bounded; SR_DEBUG=0xFF is useful for a short diagnosis but can overwhelm a run.

Memory watches, guest-PC profiling, framebuffer snapshots, and HLE tracing each answer different questions. A crash report that names only a host address is not enough; map it back to guest state and the first failing operation.

Common problem families

• Dispatch miss or unknown NID: run the fatal/default diagnostic route, classify the missing operation, and implement or expose the real behavior. Do not return success just to advance.
• Black screen or stale frame: separate guest writes, display latch/VBLANK, GE command state, VRAM coherency, and presentation.
• Audio silence or drift: separate PSP API queues, logical stream position, ring-buffer wrapping, decoder output, scheduler timing, and host routing.
• Crash after a valid-looking pointer: validate the complete guest span and checked size arithmetic, not only the starting address.
• Generated code differs after a tool change: confirm the intended source revision and manifest, regenerate, and inspect the first changed block.

Keep private title traces, captures, saves, and local paths out of public reports. Use Verification and Testing to state exactly what the evidence establishes.