SPV_AMDX_shader_enqueue

SPV_AMDX_shader_enqueue
SPV_AMDX_shader_enqueue
Table of Contents
Name Strings
Contact
Provisional
Contributors
Notice
Status
Version
Dependencies
Overview
Extension Name
Execution Modes
Decorations
Builtins
Instructions
Issues
Revision History
Name Strings
SPV_AMDX_shader_enqueue
Contact
See
Issues
list in the Khronos SPIRV-Headers repository:
Provisional
This extension is
provisional
and should: not be used in production applications.
The functionality may change in ways that break backwards compatibility between
revisions, and before final release.
Contributors
Tobias Hector, AMD
Matthäus Chajdas, AMD
Nicolai Hähnle, AMD
Junda Liu, AMD
Maciej Jesionowski, AMD
Daniel Brown, AMD
Stuart Smith, AMD
Notice
Copyright (c) 2024 The Khronos Group Inc. Copyright terms at
Status
Provisional.
Version
Last Modified Date
2024-07-26
Revision
Dependencies
This extension is written against the Unified SPIR-V Specification,
Version 1.6, Revision 1.
This extension requires SPIR-V 1.4.
Overview
This extension adds the ability for developers to enqueue compute
and mesh shader workgroups from compute shaders.
Extension Name
To use this extension within a SPIR-V module, the following
OpExtension
must be present in the module:
OpExtension "SPV_AMDX_shader_enqueue"
Capabilities
Modify Section 3.31, "Capability", adding this row to the table:
Capability
Implicitly Declares
5067
ShaderEnqueueAMDX
Uses shader enqueue capabilities
Shader
Storage Class
Modify Section 3.7, "Storage Class", adding this row to the table:
Storage Class
Enabling Capabilities
5068
NodePayloadAMDX
Storage for Node Payloads.
Variables declared with
OpVariable
in the
GLCompute
execution model with the
CoalescingAMDX
execution mode are visible across all invocations within a workgroup; and other variables declared with
OpVariable
in this storage class are visible across all invocations within a node dispatch.
Variables declared with this storage class are readable and writable, and must not have initializers.
Pointers to this storage class are also used to point to payloads allocated and enqueued for other nodes.
ShaderEnqueueAMDX
Execution Modes
Modify Section 3.6, "Execution Mode", adding the following rows to the table:
Execution Mode
Extra Operands
Enabling Capabilities
5069
CoalescingAMDX
Indicates that a GLCompute shader has coalescing semantics. (GLCompute only)
Must not be declared alongside
StaticNumWorkgroupsAMDX
or
MaxNumWorkgroupsAMDX
ShaderEnqueueAMDX
5071
MaxNodeRecursionAMDX
Maximum number of times a node can enqueue payloads for itself.

Number of recursions
ShaderEnqueueAMDX
5070
IsApiEntryAMDX
Indicates whether the shader can be dispatched directly by the client API or not. (GLCompute and MeshEXT execution models only)
Is Entry
is a scalar Boolean value, with a value of
true
indicating that it can be dispatched from the API, and
false
indicating that it cannot.
If not specified, defaults to
true
Must be set to
false
if
SharesInputWithAMDX
is specified.

Is Entry
ShaderEnqueueAMDX
5072
StaticNumWorkgroupsAMDX
Statically declare the number of workgroups dispatched for this shader, instead of obeying an API- or payload-specified value. (GLCompute and MeshEXT only)
Must not be declared alongside
CoalescingAMDX
or
MaxNumWorkgroupsAMDX

x size

y size

z size
ShaderEnqueueAMDX
5077
MaxNumWorkgroupsAMDX
Declare the maximum number of workgroups dispatched for this shader. Dispatches must not exceed this value (GLCompute and MeshEXT only)
Must not be declared alongside
CoalescingAMDX
or
StaticNumWorkgroupsAMDX

x size

y size

z size
ShaderEnqueueAMDX
5073
ShaderIndexAMDX
Declare the node index for this shader. (GLCompute and MeshEXT only)

Shader Index
ShaderEnqueueAMDX
5102
SharesInputWithAMDX
Declare that this shader is paired with another node, such that it will be dispatched with the same input payload when the identified node is dispatched.
Node Name
and
Shader Index
indicate the node that the input will be shared with.
Node Name
must be an
OpConstantStringAMDX
or
OpSpecConstantStringAMDX
instruction.

Node Name

Shader Index
ShaderEnqueueAMDX
Decorations
Modify Section 3.20, "Decoration", adding the following row to the table:
Decoration
Extra Operands
Enabling Capabilities
5020
NodeMaxPayloadsAMDX
Must only be used to decorate an
OpTypeNodePayloadArrayAMDX
OpTypeNodePayloadArrayAMDX
must have this decoration.
The operand indicates the maximum number of payloads that can be in the array, and the maximum number of payloads that can be enqueued with this type.

Max number of payloads
ShaderEnqueueAMDX
5019
NodeSharesPayloadLimitsWithAMDX
Decorates an
OpTypeNodePayloadArrayAMDX
declaration to indicate that payloads of this type share output resources with
Payload Type
when allocated.
Without the decoration, each types’s resources are separately allocated against the output limits; by using the decoration only the limits of
Payload Type
are considered.
Applications must still ensure that at runtime the actual usage does not exceed these limits, as this decoration only modifies static validation.
Must only be used to decorate an
OpTypeNodePayloadArrayAMDX
declaration,
Payload Type
must be a different
OpTypeNodePayloadArrayAMDX
declaration, and
Payload Type
must not be itself decorated with
NodeSharesPayloadLimitsWithAMDX
It is only necessary to decorate one
OpTypeNodePayloadArrayAMDX
declaration to indicate sharing between two node outputs.
Multiple variables can be decorated with the same
Payload Type
to indicate sharing across multiple node outputs.

Payload Type
ShaderEnqueueAMDX
5091
PayloadNodeNameAMDX
Decorates an
OpTypeNodePayloadArrayAMDX
declaration to indicate that the payloads in the array
will be enqueued for the shader with
Node Name
Must only be used to decorate an
OpTypeNodePayloadArrayAMDX
declaration.
Node Name
must be an
OpConstantStringAMDX
or
OpSpecConstantStringAMDX
instruction.

Node Name
ShaderEnqueueAMDX
5098
PayloadNodeBaseIndexAMDX
Decorates an
OpTypeNodePayloadArrayAMDX
declaration to indicate a base index that
will be added to the
Node Index
when allocating payloads of this type.
If not specified, it is equivalent to specifying a value of 0.
Must only be used to decorate an
OpTypeNodePayloadArrayAMDX
declaration.

Base Index
ShaderEnqueueAMDX
5099
PayloadNodeSparseArrayAMDX
Decorates an
OpTypeNodePayloadArrayAMDX
declaration to indicate that nodes at some node indexes may not exist in the execution graph pipeline and cannot be used to allocate payloads.
If not specified, all node indexes between 0 and the
PayloadNodeArraySizeAMDX
value must be valid nodes in the graph.
Must only be used to decorate an
OpTypeNodePayloadArrayAMDX
declaration.
ShaderEnqueueAMDX
5100
PayloadNodeArraySizeAMDX
Decorates an
OpTypeNodePayloadArrayAMDX
declaration to indicate the maximum node index that can be used when allocating payloads of this type, including the base index offset in
PayloadNodeBaseIndexAMDX
decoration (if present).
If not specified, the node array is considered unbounded.
Must only be used to decorate an
OpTypeNodePayloadArrayAMDX
declaration.
If
PayloadNodeSparseArrayAMDX
is not set to
true
for a type initialized by
OpAllocateNodePayloadsAMDX
, this must be specified.

Array Size
ShaderEnqueueAMDX
5078
TrackFinishWritingAMDX
Decorates a structure to indicate that when used as a payload it can be written to and works with the
OpFinishWritingNodePayloadAMDX
instruction.
Must only be used to decorate a structure type declaration.
If the payload enqueued for a node is using a structure decorated with this value, the input payload in the
NodePayloadAMDX
storage class in the receiving node must use a structure decorated with it as well.
ShaderEnqueueAMDX
5105
PayloadDispatchIndirectAMDX
Indicates the dispatch indirect arguments describing the number of workgroups to dispatch in a payload.
Must only be used with
OpMemberDecorate
to decorate the member of a structure.
Must decorate a structure member with a type of
OpTypeInt
or
OpTypeVector
with two or three components.
The integer type or the type of the vector component must be an
OpTypeInt
with up to 32-bit
Width
and 0
Signedness
If a single integer is used, the Y and Z dispatch indirect arguments are assumed to be 1.
If a vector of two components is used, the Z dispatch indirect argument is assumed to be 1.
ShaderEnqueueAMDX
Builtins
Modify Section 3.21, "BuiltIn", adding the following row to the table:
BuiltIn
Enabling Capabilities
5021
RemainingRecursionLevelsAMDX
The number of times this node can still enqueue payloads for itself.
Is equal to 0 if at the leaf or if the node is not recursive at all.
ShaderEnqueueAMDX
5073
ShaderIndexAMDX
Index assigned to the current shader.
ShaderEnqueueAMDX
Instructions
Add the following new instructions:
OpConstantStringAMDX
Declare a new string specialization constant.
String
is the value of the constant.
Unlike
OpString
, this is a semantically meaningful instruction and cannot be safely removed from a module.
Capability:
ShaderEnqueueAMDX
3 + variable
5103
Result
Literal
String
OpSpecConstantStringAMDX
Declare a new string specialization constant.
String
is the default value of the constant.
Unlike
OpString
, this is a semantically meaningful instruction and cannot be safely removed from a module.
This instruction can be specialized to become an
OpConstantStringAMDX
instruction.
See
Specialization
Capability:
ShaderEnqueueAMDX
3 + variable
5104
Result
Literal
String
OpTypeNodePayloadArrayAMDX
Declare a new payload array type. Its length is not known at compile time.
Payload Type
is the type of each payload in the array.
See
OpNodePayloadArrayLengthAMDX
for getting the length of an array of this type.
A payload array can be allocated by either
OpAllocateNodePayloadsAMDX
to be enqueued as an output, or via
OpVariable
in the
NodePayloadAMDX
storage class to be consumed as an input.
Can be dereferenced using an access chain in the same way as
OpTypeRuntimeArray
or
OpTypeArray
Capability
ShaderEnqueueAMDX
5076
Result

Payload Type
OpAllocateNodePayloadsAMDX
Allocates payloads for a node to be later enqueued via
OpEnqueueNodePayloadsAMDX
Result Type
must be an
OpTypePointer
to an
OpTypeNodePayloadArrayAMDX
in the
NodePayloadAMDX
storage class.
The payloads are allocated for the node identified by the
Node Name
in the
PayloadNodeNameAMDX
decoration on
Result Type
with an index equal to the sum of its
PayloadNodeBaseIndexAMDX
decoration (if present) and
Node Index
Payloads are allocated for the
Scope
indicated by
Visibility
, and are visible to all invocations in that
Scope
Payload Count
is the number of payloads to allocate in the resulting array.
Behavior is undefined if
Payload Count
is greater than the
NodeMaxPayloadsAMDX
decoration on
Result Type
Payload Count
and
Node Index
must be dynamically uniform within the scope identified by
Visibility
Visibility
must only be either
Invocation
or
Workgroup
This instruction must be called in uniform control flow within the same workgroup.
Capability:
ShaderEnqueueAMDX
5074

Result Type
Result

Scope
Visibility

Payload Count

Node Index
OpEnqueueNodePayloadsAMDX
Enqueues a previously allocated payload array for execution by its node.
Payload Array
is a pointer to a payload array that was previously allocated by
OpAllocateNodePayloadsAMDX
This instruction must be called in uniform control flow within the workgroup.
Capability:
ShaderEnqueueAMDX
5075

Payload Array
OpNodePayloadArrayLengthAMDX
Query the length of a payload array. Must only be used with input payload arrays or allocated output payload arrays.
Result
will be equal to the
Payload Count
value used to allocate
Payload Array
, or to the number of received payloads if the shader is using
CoalescingAMDX
execution mode. Otherwise,
Result
will be 1.
Result Type
must be an
OpTypeInt
with 32-bit
Width
and 0
Signedness
Payload Array
is a pointer to a payload array previously allocated by
OpAllocateNodePayloadsAMDX
, or declared via
OpVariable
in the
NodePayloadAMDX
storage class as an input.
Capability
ShaderEnqueueAMDX
5090

Result Type
Result

Payload Array
OpIsNodePayloadValidAMDX
Check if the node payload identified by the
Node Name
in the
PayloadNodeNameAMDX
decoration,
with an index equal to the sum of its
PayloadNodeBaseIndexAMDX
decoration (if present) and
Node Index
can be allocated.
Result
is equal to
OpConstantTrue
if the payload is valid and can be allocated,
OpConstantFalse
otherwise.
Result Type
must be
OpTypeBool
Payload Type
must be an
OpTypeNodePayloadArrayAMDX
declaration.
NodeIndex
must be less than the value specified by the
PayloadNodeArraySizeAMDX
decoration if specified.
Capability:
ShaderEnqueueAMDX
5101

Result Type
Result


Payload Type

Node Index
OpFinishWritingNodePayloadAMDX
Optionally indicates that all writes to the input payload by the current workgroup have completed.
Result
is equal to
OpConstantTrue
if all workgroups that can access this payload have called this function.
Must not be called if the shader is using
CoalescingAMDX
execution mode,
or if the shader was dispatched with a
vkCmdDispatchGraph*
client API command,
rather than enqueued from another shader.
Must not be called if the input payload is not decorated with
TrackFinishWritingAMDX
Result Type
must be
OpTypeBool
Payload
must be the result of an
OpVariable
in the
NodePayloadAMDX
storage class.
Capability:
ShaderEnqueueAMDX
5078

Result Type
Result


Payload
Validation Rules
In section 2.16, Validation Rules for Shader Capabilities, Add
NodePayloadAMDX
to the list of storage classes where composite variables must be explicitly laid out.
Issues
None
Revision History
Rev
Date
Author
Changes
2023-07-22
Tobias Hector
Initial revision.
2024-07-26
Tobias Hector
Update to better match HLSL