1# Vulkan Shader Debugging
2
3SwiftShader implements a Vulkan shader debugger that uses the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol).
4
5This debugger is still actively being developed. Please see the [Known Issues](#Known-Issues).
6
7# Enabling
8
9To enable the debugger functionality, SwiftShader needs to be built using the CMake `SWIFTSHADER_ENABLE_VULKAN_DEBUGGER` flag (`-DSWIFTSHADER_ENABLE_VULKAN_DEBUGGER=1`):
10
11Once SwiftShader is built with the debugger functionality, there are two environment flags that control the runtime behavior:
12
13* `VK_DEBUGGER_PORT` - set to an unused port number that will be used to create the DAP localhost socket. If this environment variable is not set, then the debugger functionality will not be enabled.
14* `VK_WAIT_FOR_DEBUGGER` - if defined, the debugger will block on `vkCreateDevice()` until a debugger connection is established, before allowing `vkCreateDevice()` to return. This allows breakpoints to be set before execution continues.
15
16# Connecting using Visual Studio Code
17
18Once you have built SwiftShader with the debugger functionality enabled, and the `VK_DEBUGGER_PORT` environment variable set, you can connect to the debugger using the following Visual Studio Code `"debugServer"` [Launch Configuration](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations):
19
20```json
21    {
22        "name": "Vulkan Shader Debugger",
23        "type": "node",
24        "request": "launch",
25        "debugServer": 19020,
26    }
27```
28
29Note that the `"type": "node"` field is unused, but is required.
30
31[TODO](https://issuetracker.google.com/issues/148373102): Create a Visual Studio Code extension that provides a pre-built SwiftShader driver and debugger type.
32
33# Shader entry breakpoints
34
35You can use the following function breakpoint names to set a breakpoint on the entry to all shaders of the corresponding shader type:
36* `"VertexShader"`
37* `"FragmentShader"`
38* `"ComputeShader"`
39
40# High-level Shader debugging
41
42The debugger, will by default, automatically disassemble the SPIR-V shader code, and provide this as the source for the shader program.
43
44However, if the shader program contains [`OpenCL.DebugInfo.100`](https://www.khronos.org/registry/spir-v/specs/unified1/OpenCL.DebugInfo.100.mobile.html) debug info instructions, then the debugger will allow you to debug the high-level shader source (please see [Known Issues](#Known-Issues)).
45
46
47# Known Issues
48
49* Currently enabling the debugger dramatically affects performance for all shader invocations. We may want to just-in-time recompile shaders that are actively being debugged to keep the invocations of non-debugged shaders performant. [Tracker bug](https://issuetracker.google.com/issues/148372410)
50* Support for [`OpenCL.DebugInfo.100`](https://www.khronos.org/registry/spir-v/specs/unified1/OpenCL.DebugInfo.100.mobile.html) is still in early, but active development. Many features are still incomplete.
51* Shader subgroup invocations are currently presented as a single thread, with each invocation presented as `Lane N` groups in the watch window(s). This approach is still being evaluated, and may be reworked.