METALVALIDATION(1) General Commands Manual METALVALIDATION(1)

Metal Validation — Metal Runtime Validation

MTL_DEBUG_LAYER
MTL_DEBUG_LAYER_ERROR_MODE
MTL_DEBUG_LAYER_WARNING_MODE
MTL_DEBUG_LAYER_VALIDATE_LOAD_ACTIONS
MTL_DEBUG_LAYER_VALIDATE_STORE_ACTIONS
MTL_DEBUG_LAYER_VALIDATE_UNRETAINED_RESOURCES
MTL_SHADER_VALIDATION
MTL_SHADER_VALIDATION_DEFAULT_STATE
MTL_SHADER_VALIDATION_ENABLE_PIPELINES
MTL_SHADER_VALIDATION_DISABLE_PIPELINES
MTL_SHADER_VALIDATION_DUMP_PIPELINES
MTL_SHADER_VALIDATION_ENABLE_ERROR_REPORTING
MTL_SHADER_VALIDATION_TEXTURE_USAGE
MTL_SHADER_VALIDATION_THREADGROUP_MEMORY
MTL_SHADER_VALIDATION_RESOURCE_USAGE
MTL_SHADER_VALIDATION_COMPILER_INLINING
MTL_SHADER_VALIDATION_FAIL_MODE
MTL_SHADER_VALIDATION_REPORT_TO_STDERR

Unless otherwise noted all environment variables listed must be set before any Metal device is created in the process. Any changes to these values after device creation will not take effect.

Metal provides two modes of validation, API and GPU.

API validation validates CPU API usage correctness such as calling draw without a pipeline set.

GPU validation validates GPU API correctness such as accessing invalid GPU memory.


Defaults to 0.
All environment variables prefixed with MTL_DEBUG_LAYER only apply when MTL_DEBUG_LAYER is non-zero.
Any value other than 0 will enable API validation.

Defaults to "assert"
Valid values are "assert", "ignore" and "nslog"
Sets the behavior for when a debug layer error occurs.

Setting "assert" will cause the debug layer to log and then assert on error.

Setting "ignore" will cause the debug layer to ignore errors, this may cause undefined behavior.

Setting "nslog" will cause the debug layer to log errors using NSLog, this may cause undefined behavior.


Defaults to "ignore"
Valid values are "assert", "ignore" and "nslog"
Sets the behavior for when a debug layer warning occurs.

Setting "assert" will cause the debug layer to log and then assert on warnings.

Setting "ignore" will cause the debug layer to ignore warnings.

Setting "nslog" will cause the debug layer to log warnings using NSLog.


Defaults to 0
Setting this value to "1" will convert any MTLLoadActionDontCare to MTLLoadActionClear of fuchsia. This can be used to debug incorrect load action modes or assumptions on DontCare behavior.

Defaults to 0
Setting this value to "1" will write an alternating red and white checkerboard into each render target with a store action of MTLStoreActionDontCare. This can be used to debug incorrect store action modes or assumptions on DontCare behavior.

Defaults to 1
This option takes a bitfield of modes to enable. The bitfield values are:

0x1 : Enabling this flag will cause command buffer to tag any objects bound to the command buffer, which are not retained internally. If a tagged object is deallocated before the command buffer completes, an error is raised.

0x2 : Enabling this flag will cause command buffer to tag objects that are internally retained by the command buffer. This should usually not be needed, because an object cannot be deallocated while the command buffer itself isn't complete.

0x4 : Enabling this flag will cause deallocated tagged objects to be considered an error even before committing the command buffer. This will lead to more immediate error (ie: in the call stack of the dealloc) rather than at commit, which is more debuggable.


Defaults to 0
All environment variables prefixed with MTL_SHADER_VALIDATION only apply when MTL_SHADER_VALIDATION is non zero.
Any value other than 0 will enable GPU validation.
Sets the behavior of API usage errors. Using a value of "4" for this setting may result in undefined behavior as otherwise fatal errors will be ignored.

Defaults to "all"
Defines the default behavior of Shader Validation for all pipelines.
If set to "all", every pipeline will be created with Shader Validation by default.
If set to "none", no pipeline will be created with Shader Validation by default.
This default behavior can be bypassed with MTL_SHADER_VALIDATION_ENABLE_PIPELINES and MTL_SHADER_VALIDATION_DISABLE_PIPELINES
MTL_SHADER_VALIDATION_ENABLE_PIPELINES

Defaults to an empty string
List of pipeline labels (or Shader Validation UIDs generated by MTL_SHADER_VALIDATION_DUMP_PIPELINES) for which Shader Validation should be enabled. Only relevant when MTL_SHADER_VALIDATION_DEFAULT_STATE is set to "none".
The list is comma-separated, and spaces are part of the parsed name.
MTL_SHADER_VALIDATION_DISABLE_PIPELINES

Defaults to an empty string
List of pipeline labels (or Shader Validation UIDs generated by MTL_SHADER_VALIDATION_DUMP_PIPELINES) for which Shader Validation should be disabled. Only relevant when MTL_SHADER_VALIDATION_DEFAULT_STATE is set to "all".
The list is comma-separated, and spaces are part of the parsed name.
MTL_SHADER_VALIDATION_DUMP_PIPELINES

Defaults to 0
If set to "1", dumps the list of UIDs referencing the pipelines compiled in the program into Console.app
The UIDs are persistent across multiple runs and can be used as inputs to MTL_SHADER_VALIDATION_ENABLE_PIPELINES and MTL_SHADER_VALIDATION_DISABLE_PIPELINES
UIDs are logged using Unified Logging and can be viewed in Console.app by filtering with "Shader Validation UID"

Defaults to 1
Setting this value to "0" will disable shader validation error reporting but not instrumentation or detection.

Defaults to 1
Setting this value to "0" will disable instrumentation of device & constant memory access. The result of accessing invalid global memory on the GPU will be undefined.

If this value is set to any non-zero value, shader validation will instrument all global memory accesses and result of accessing invalid memory is determined by MTL_SHADER_VALIDATION_FAIL_MODE


Defaults to 1
Setting this value to "0" will disable instrumentation of texture member functions. The result of the following operations on the GPU will be undefined:
1. Accessing a nil texture object
2. Accessing a texture object with a type different than what is expected by the shader signature
3. Accessing a non-resident texture or without the appropriate MTLResourceUsage flag set on a useResource or useHeap call

If this value is set to any non-zero value, shader validation will instrument all texture member functions (e.g read, write, get_width) and the result of the following operations on the GPU is determined by MTL_SHADER_VALIDATION_FAIL_MODE
1. Accessing a nil texture object
2. Accessing a texture object with a type different than what is expected by the shader signature
3. Accessing a non-resident texture or without the appropriate MTLResourceUsage flag set on a useResource or useHeap call


Defaults to 1
Setting this value to "0" will disable instrumentation of threadgroup memory access. The result of accessing invalid threadgroup memory on the GPU will be undefined.

If this value is set to any non-zero value, shader validation will instrument all threadgroup memory accesses and result of accessing invalid memory is determined by MTL_SHADER_VALIDATION_FAIL_MODE


Defaults to 1
Setting this value to "0" will disable instrumentation of resource usage. The result of accessing resources that are not resident on the GPU will be undefined.

If this value is set to any non-zero value, shader validation will instrument all resource accesses to check resource usage. It will detect missing calls to useResource and useHeap with the appropriate MTLResourceUsage flag on resources used by the GPU. The result of accessing invalid memory is determined by MTL_SHADER_VALIDATION_FAIL_MODE


Defaults to 1
Setting this value to "0" will disable instrumentation of indirect and recursive function calls. The result of exceeding "maxCallStackDepth" will be undefined.

If this value is set to any non-zero value, shader validation will instrument all indirect calls (calls by function pointer, visible functions, intersection functions, dylib calls) and recursive calls. If the call stack depth for such functions exeecds the value set for "maxCallStackDepth" for that stage, an error will be raised and the function call will be skipped.


Valid options are "default", "full".

Determines whether code inlining will occur.
Setting this value to "full" will force inlining
Adding inlining may result in improved runtime performance at the cost of compile time performance.
Reducing inlining may result in improved compile time performance at the cost of runtime performance.


Defaults to "zerofill"
Valid options are "zerofill", "allow".

Sets the behavior for how invalid accesses should be handled. Setting this value to "zerofill" causes invalid reads to return 0. Invalid writes are dropped.

Setting this value to "allow" allows the invalid read or write, which may result in command buffer failure depending on platform, but has reduced compile & runtime performance impact.


Defaults to "0"
Setting this value to any value other than "0" will redirect shader validation error messages to stderr. This is useful if there is any issue with the OS logging mechanism.
05/03/20 Darwin