diff --git a/docs/dawn/debugging.md b/docs/dawn/debugging.md index 740d0b284c..4856256008 100644 --- a/docs/dawn/debugging.md +++ b/docs/dawn/debugging.md @@ -1,3 +1,49 @@ # Debugging Dawn -(TODO) +## 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: + ```c++ + 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()`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/dawn/src/dawn/common/Assert.cpp?q=dawn::Breakpoint)) as soon as any type of error is generated. diff --git a/src/dawn/common/Assert.h b/src/dawn/common/Assert.h index 849116ec2f..f39de6fddd 100644 --- a/src/dawn/common/Assert.h +++ b/src/dawn/common/Assert.h @@ -74,6 +74,7 @@ namespace dawn { +void BreakPoint(); void HandleAssertionFailure(const char* file, const char* function, int line, diff --git a/src/dawn/native/ErrorData.cpp b/src/dawn/native/ErrorData.cpp index ee962403b4..290d2812ed 100644 --- a/src/dawn/native/ErrorData.cpp +++ b/src/dawn/native/ErrorData.cpp @@ -16,6 +16,8 @@ #include +#include "dawn/common/Assert.h" +#include "dawn/common/SystemUtils.h" #include "dawn/native/Error.h" #include "dawn/native/ObjectBase.h" #include "dawn/native/dawn_platform.h" @@ -29,6 +31,11 @@ std::unique_ptr ErrorData::Create(InternalErrorType type, int line) { std::unique_ptr error = std::make_unique(type, message); error->AppendBacktrace(file, function, line); + + auto [var, present] = GetEnvironmentVar("DAWN_DEBUG_BREAK_ON_ERROR"); + if (present && !var.empty() && var != "0") { + BreakPoint(); + } return error; }