Skip to content

Debugging Tools and Commands

Mainkill1 edited this page Sep 21, 2026 · 10 revisions

Debugging Tools and Commands

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.

Tool index

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

Choose by question

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

Standard investigation flow

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]
Loading
  1. Record commit, tree, working-tree state, executable hash, symbol hash, tool versions, configuration, renderer, GPU, and driver.
  2. Start capture before the controlled action, then report only the explicit measurement interval.
  3. Verify that the capture contains the intended workload. A file existing does not prove correct admission.
  4. Use the least invasive tool that answers the unresolved question.
  5. Remove diagnostic timing from acceptance evidence. Validate the final change in an optimized, uninstrumented build.

Evidence rules

  • 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. UNVERIFIED is 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.

Scenario guides

Clone this wiki locally