--- title: Validating your app’s Metal shader usage framework: xcode role: article role_heading: Article path: xcode/validating-your-apps-metal-shader-usage --- # Validating your app’s Metal shader usage Catch common shader runtime issues using Shader Validation. ## Overview Overview Metal Shader Validation detects errors only discoverable during shader execution, such as accesses to non-resident resources, out-of-bounds memory accesses, undefined behavior, and attempts to access nil textures. Examples of issues Shader Validation can detect in Metal apps include: | | | | | | | | | | You can enable Shader Validation using the runtime diagnostics options in Xcode and visualizing issues in the Xcode UI, or by using environment variables and printing its results to the app’s standard error or log stream. To ensure you see the most up-to-date debug information, set your app’s deployment target to the matching OS version, even if only temporarily. You can change the deployment target in the Xcode project settings. If you change the deployment target temporarily, remember to change it back before deploying your app. important: The Shader Validation layer has a corresponding impact on GPU performance, and shaders might take longer to compile at runtime. This layer adds instrumentation code to all your GPU functions, which increases the amount of work they perform and the number of times they access memory. For more information, see the WWDC20 video Debug GPU-side errors in Metal and the WWDC21 video Discover Metal debugging, profiling, and asset creation tools. Enable Shader Validation in Xcode Follow these steps to enable Shader Validation using the runtime diagnostics options in the Scheme settings: In the Xcode toolbar, choose Edit Scheme from the Scheme menu. Alternatively, choose Product > Scheme > Edit Scheme. In the Edit Scheme dialog, select Run. Click the Diagnostics tab. Select Shader Validation to enable it, and click Close. Xcode enables Shader Validation each time you run your scheme. Customize Shader Validation options You can customize Shader Validation behaviors from the Diagnostics tab: Select Raise Runtime Issues on Error to log errors Shader Validation detects in the Issue navigator. When you specify this option, you can also create a shader breakpoint. Choose Abort on Error to cause Shader Validation to stop the program when it logs an error. Use in situations where repeated GPU restarts affect system responsiveness. Enable Log Allocation Stacktraces to track CPU stacktraces where your app allocates Metal resources. Use this option to obtain the CPU allocation stacktrace of the resource involved in an error. This option increases memory usage. Choose Detect GPU Stack Overflow to check for GPU stack overflow caused by indirect function calls and recursion. note: Except for setting an Xcode shader breakpoint, you can control these options through the environment variables in section “Enable Shader Validation with environment variables” below. Selectively enable Shader Validation When enabling Shader Validation, you can also choose to only enable (or disable) Shader Validation for specific pipelines. This advanced control can be particularly useful when you want to focus your debugging on specific pipelines of interest. It can also greatly improve the performance of the apps you debug, due to the reduced amount of instrumented pipelines. Shader Validation instruments all pipelines by default (MTL_SHADER_VALIDATION_DEFAULT_STATE=all). To change this behavior, you can set MTL_SHADER_VALIDATION_DEFAULT_STATE=none. Next, you can set MTL_SHADER_VALIDATION_ENABLE_PIPELINES and MTL_SHADER_VALIDATION_DISABLE_PIPELINES to selectively enable and disable instrumentation for given pipelines. You can use the pipeline labels and Shader Validation unique identifiers (UIDs) as entries (see Print pipeline UIDs). Multiple entries need to be comma-separated, without spaces (see man MetalValidation for more information). In the following example, the pipelines with the label foo are the only pipelines not instrumented by Shader Validation. > export MTL_SHADER_VALIDATION=1 > export MTL_SHADER_VALIDATION_DEFAULT_STATE=all > export MTL_SHADER_VALIDATION_DISABLE_PIPELINES="foo" ... > ./ Alternatively, you can programmatically set your pipeline descriptor property shaderValidation to either MTLShaderValidationEnabled or MTLShaderValidationDisabled. In the following example, pipe is the only pipeline instrumented by Shader Validation. > export MTL_SHADER_VALIDATION=1 > export MTL_SHADER_VALIDATION_DEFAULT_STATE=none > ... > ./ Finally, you can query the Shader Validation state of a pipeline through the shaderValidation property of pipeline state objects. Print pipeline UIDs Shader Validation generates UIDs for all pipelines you process, which you can use as an entry to MTL_SHADER_VALIDATION_ENABLE_PIPELINES and MTL_SHADER_VALIDATION_DISABLE_PIPELINES. This is useful when your app has no pipeline labels. To print the UIDs to Console or a log stream instance, set MTL_SHADER_VALIDATION_DUMP_PIPELINES=1 in your terminal or Xcode Environment Variables Scheme settings. note: To see the logs, go to Action > Include Debug Messages in Console. View Shader Validation errors in Xcode After enabling Shader Validation, if Metal encounters errors while executing the commands in a command buffer, Xcode displays the error details in the source editor as shown below: You can find the breakpoint in the Breakpoint navigator if you want to modify or remove it in the future. For more information, see Setting breakpoints to pause your running app. If you discover an error in your shader, consider taking a capture and investigating with the shader debugger (see Investigating visual artifacts). View Shader Validation errors in the terminal You can enable Shader Validation for any Metal app via environment variables, even when you don’t have access to its source. By default, Shader Validation logs any issues it finds to the OS log. You can view these directly in the terminal, using the log stream command: log stream -process You can also configure Shader Validation to copy its messages to the app’s standard error stream by setting environment variables MTL_SHADER_VALIDATION=1 and MTL_SHADER_VALIDATION_REPORT_TO_STDERR=1. Enable Shader Validation with environment variables You can also enable Shader Validation and customize its behavior by setting the following environment variables on your Metal app: For a complete list of settings, run man MetalValidation in Terminal. If you discover an error in your shader, consider taking a capture (see Capturing a Metal workload programmatically) and investigating with the Metal debugger (see Debugging the shaders within a draw command or compute dispatch). Review Metal Shader Validation constraints Because Metal Shader Validation relies on live shader instrumentation, it’s incompatible with Metal Binary Archives. Additionally, to use indirect command buffers with Shader Validation, enable pipeline and buffer inheritance. Metal Shader Validation doesn’t track residency of pages backing Metal sparse resources. ## See Also ### Runtime diagnostics - [Inspecting live resources at runtime](xcode/inspecting-live-resources-at-runtime.md) - [Validating your app’s Metal API usage](xcode/validating-your-apps-metal-api-usage.md) - [Monitoring your Metal app’s graphics performance](xcode/monitoring-your-metal-apps-graphics-performance.md) - [Customizing the Metal Performance HUD](xcode/customizing-metal-performance-hud.md) - [Understanding the Metal Performance HUD metrics](xcode/understanding-metal-performance-hud-metrics.md) - [Gaining performance insights with the Metal Performance HUD](xcode/gaining-performance-insights-with-metal-performance-hud.md) - [Generating performance reports with the Metal Performance HUD](xcode/generating-performance-reports-with-metal-performance-hud.md)