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>

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.

src/dawn/common/Assert.h

@@ -74,6 +74,7 @@
 
 namespace dawn {
 
+void BreakPoint();
 void HandleAssertionFailure(const char* file,
                             const char* function,
                             int line,

src/dawn/native/ErrorData.cpp

@@ -16,6 +16,8 @@
 
 #include <utility>
 
+#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> ErrorData::Create(InternalErrorType type,
                                              int line) {
     std::unique_ptr<ErrorData> error = std::make_unique<ErrorData>(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;
 }