encounter/dawn-cmake
1
0
Fork 0
mirror of https://github.com/encounter/dawn-cmake.git synced 2025-05-13 19:01:24 +00:00
Code Issues Packages Projects Releases Wiki Activity
dawn-cmake/docs/dawn/debugging.md
Austin Eng 5107db5637 Add DAWN_DEBUG_BREAK_ON_ERROR environment var and debugging docs 
DAWN_DEBUG_BREAK_ON_ERROR executes dawn::BreakPoint inside
ErrorData::Create so that an application can inspect their callstack
immediately when an error is generated.

Bug: dawn:1789
Change-Id: I3f31b9713414d31b69ed469474e0f3c0f714540a
Reviewed-on: https://dawn-review.googlesource.com/c/dawn/+/133562
Reviewed-by: Loko Kung <lokokung@google.com>
Commit-Queue: Austin Eng <enga@chromium.org>
Reviewed-by: Brandon Jones <bajones@chromium.org>
Kokoro: Kokoro <noreply+kokoro@google.com>
2023-05-18 23:29:25 +00:00

2.3 KiB
Raw Blame History

Debugging Dawn

Toggles

There are various debug-related Toggles that can help diagnose issues. Useful debug toggles:

  • dump_shaders: Log input WGSL shaders and translated backend shaders (MSL/ HLSL/DXBC/DXIL / SPIR-V).
  • disable_symbol_renaming: As much as possible, disable renaming of symbols (variables, function names, etc.). This can make dumped shaders more readable.
  • emit_hlsl_debug_symbols: Sets the D3DCOMPILE_SKIP_OPTIMIZATION and D3DCOMPILE_DEBUG compilation flags when compiling HLSL code.
  • use_user_defined_labels_in_backend: Forward object labels to the backend so that they can be seen in native debugging tools like RenderDoc, PIX, or Mac Instruments.

Toggles may be enabled/disabled in different ways.

  • In code:

    Use extension struct DawnTogglesDescriptor chained on DeviceDescriptor.

    For example:

    const char* const enabledToggles[] = {"dump_shaders", "disable_symbol_renaming"};

wgpu::DawnTogglesDescriptor deviceTogglesDesc;
deviceTogglesDesc.enabledToggles = enabledToggles;
deviceTogglesDesc.enabledTogglesCount = 2;

wgpu::DeviceDescriptor deviceDescriptor;
deviceDescriptor.nextInChain = &deviceTogglesDesc;

  • Command-line for Chrome

    Run Chrome with command line flags--enable-dawn-features and/or --disable-dawn-features to force enable/disable toggles. Toggles should be comma-delimited.

    For example: --enable-dawn-features=dump_shaders,disable_symbol_renaming

  • Command-line for dawn_end2end_tests/dawn_unittests

    Run Dawn test binaries with command line flags--enable-toggles and/or --disable-toggles to force enable/disable toggles. Toggles should be comma-delimited.

    For example: dawn_end2end_tests --enable-toggles=dump_shaders,disable_symbol_renaming

Environment Variables

  • DAWN_DEBUG_BREAK_ON_ERROR

    Errors in WebGPU are reported asynchronously which may make debugging difficult because at the time an error is reported, you can't easily create a breakpoint to inspect the callstack in your application.

    Setting DAWN_DEBUG_BREAK_ON_ERROR to a non-empty, non-zero value will execute a debug breakpoint instruction (dawn::Breakpoint()) as soon as any type of error is generated.