Repository navigation
Debugging Tools and Commands
Mainkill1 edited this page Sep 21, 2026
·
10 revisions
Use this page to choose a debugging tool. Each linked page explains where to obtain the tool, how to verify the installation, how xemu uses it, how to interpret its output, and what evidence to retain.
Use Debugging Lag and Hot Paths for the investigation process and Graphics Transition Debugging Tools for scene, resource, snapshot, and renderer-transition failures.
| Name | OS | Description / use cases |
|---|---|---|
| [[Git | Debugging-Tool-Git]] | Windows, Linux, macOS |
| [[SHA-256 and artifact identity | Debugging-Tool-SHA-256]] | Windows, Linux, macOS |
| [[Release symbols with objcopy and strip | Debugging-Tool-Release-Symbols]] | Windows cross-build, Linux, macOS |
| [[Windows Performance Recorder (WPR) | Debugging-Tool-WPR]] | Windows |
| [[Windows Performance Analyzer (WPA) | Debugging-Tool-WPA]] | Windows |
| [[WPAExporter | Debugging-Tool-WPAExporter]] | Windows |
| [[xperf | Debugging-Tool-Xperf]] | Windows |
| [[addr2line | Debugging-Tool-Addr2line]] | Windows, Linux, macOS |
| [[objdump | Debugging-Tool-Objdump]] | Windows, Linux, macOS |
| [[Defined-text symbol maps | Debugging-Tool-Defined-Text-Symbol-Maps]] | Windows, Linux, macOS |
| [[ripgrep (rg) | Debugging-Tool-Ripgrep]] | Windows, Linux, macOS |
| [[PowerShell automation | Debugging-Tool-PowerShell]] | Windows, Linux, macOS |
| [[RenderDoc | Debugging-Tool-RenderDoc]] | Windows, Linux, Android |
| [[Vulkan validation layers | Debugging-Tool-Vulkan-Validation-Layers]] | Windows, Linux, macOS, Android |
| [[xemu cause counters | Debugging-Tool-Xemu-Cause-Counters]] | Host-independent analysis |
| [[WPA attribution helpers | Debugging-Tool-WPA-Attribution]] | Windows capture; cross-platform analysis |
| [[Correctness hash comparison | Debugging-Tool-Correctness-Hashes]] | Windows, Linux, macOS |
| Question | Start with | Continue with |
|---|---|---|
| Which xemu thread owns a lag interval? | [[WPR | Debugging-Tool-WPR]] |
| Is the thread running, waiting, or ready? | [[WPA | Debugging-Tool-WPA]] |
| Which source line owns a sampled address? | [[addr2line | Debugging-Tool-Addr2line]] |
| Which draw or resource first corrupts a frame? | [[RenderDoc | Debugging-Tool-RenderDoc]] |
| Why does a framework helper repeat? | [[xemu cause counters | Debugging-Tool-Xemu-Cause-Counters]] |
| Did candidate output remain equivalent? | [[Correctness hashes | Debugging-Tool-Correctness-Hashes]] |
| Does evidence belong to the reviewed build? | [[Git | Debugging-Tool-Git]] and [[SHA-256 |
flowchart LR
A[Exact Release executable and symbols] --> B[Bounded capture]
B --> C[Inspect the correct process, thread, API, and time range]
C --> D[Resolve addresses and resources]
D --> E[Inspect exact source and state ownership]
E --> F[Add one bounded diagnostic if causality is still missing]
F --> G[Build an uninstrumented candidate]
G --> H[Correctness and performance validation]
- Record commit, tree, working-tree state, executable hash, symbol hash, tool versions, configuration, renderer, GPU, and driver.
- Start capture before the controlled action, then report only the explicit measurement interval.
- Verify that the capture contains the intended workload. A file existing does not prove correct admission.
- Use the least invasive tool that answers the unresolved question.
- Remove diagnostic timing from acceptance evidence. Validate the final change in an optimized, uninstrumented build.
- A source commit does not identify a binary. Record executable and symbol hashes.
- A profiler identifies where time or samples appeared; it does not prove root cause or removable cost.
- Temporal GPU/CPU overlap does not prove a dependency.
- A source match does not prove that code executed.
- A hash PASS proves only the hashed contract.
UNVERIFIEDis not PASS. - Display-write cadence is a guest-progress proxy, not rendered or monitor-present FPS.
- Keep diagnostic logging, validation, and tracing disabled during ordinary performance acceptance unless that run is explicitly measuring their cost.
- Preserve failed admission, dropped events, incomplete exports, abnormal termination, and unfavorable results instead of relabeling them as passes.
DSP tooling guide and navigation updated November 2, 2026 for experimental PR #384, source 8f51d237. Capture/replay usage and limits.
The earlier wiki-wide review was published November 1, 2026. Emulator source: b7140848. Reviewed wiki content: 1d2b671. Current status · Release availability · Publication process.
- Home
- Current status
- Stable versus main
- Implemented mechanisms
- Controls and defaults
- Measured results and limits
- Complete change register
- System
- CPU and vCPU
- Memory and DMA
- Graphics / NV2A
- APU and audio
- Timing and timers
- Platform and I/O
- Hardware observations
- Fidelity boundaries
- Methodology
- PGR2 routes
- Debugging lag / hot paths
- Tools and commands
- DSP capture, replay and fuzzing
- HLE readiness and public XISO proof
- Concurrent DSP shadow and OpenAL proof
- DSP HLE operation inventory
- DSP HLE fix examples and testing
- Development
- Upstream shortlist
- Wiki maintenance
- Research / retired work
- Optimization catalog
- Hot-path shortcuts
- Researched experiments
- Unproven proposal directory
- PR lessons
- September26 snapshot
Repository · PRs · Issues