1// Copyright 2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[executiongraphs]] 6= Execution Graphs 7 8_Execution graphs_ provide a way for applications to dispatch multiple 9operations dynamically from a single initial command on the host. 10To achieve this, a new execution graph pipeline is provided, that links 11together multiple shaders or pipelines which each describe one or more 12operations that can be dispatched within the execution graph. 13Each linked pipeline or shader describes an _execution node_ within the 14graph, which can: be dispatched dynamically from another shader within the 15same graph. 16This allows applications to describe much richer execution topologies at a 17finer granularity than would typically be possible with API commands alone. 18 19 20== Pipeline Creation 21 22[open,refpage='vkCreateExecutionGraphPipelinesAMDX',desc='Creates a new execution graph pipeline object',type='protos'] 23-- 24To create execution graph pipelines, call: 25 26include::{generated}/api/protos/vkCreateExecutionGraphPipelinesAMDX.adoc[] 27 28 * pname:device is the logical device that creates the execution graph 29 pipelines. 30 * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that 31 pipeline caching is disabled; or the handle of a valid 32 <<pipelines-cache,pipeline cache>> object, in which case use of that 33 cache is enabled for the duration of the command. 34 * pname:createInfoCount is the length of the pname:pCreateInfos and 35 pname:pPipelines arrays. 36 * pname:pCreateInfos is a pointer to an array of 37 slink:VkExecutionGraphPipelineCreateInfoAMDX structures. 38 * pname:pAllocator controls host memory allocation as described in the 39 <<memory-allocation, Memory Allocation>> chapter. 40 * pname:pPipelines is a pointer to an array of slink:VkPipeline handles in 41 which the resulting execution graph pipeline objects are returned. 42 43The implementation will create a pipeline in each element of 44pname:pPipelines from the corresponding element of pname:pCreateInfos. 45If creation of any pipeline fails, that pipeline will be set to 46dlink:VK_NULL_HANDLE. 47 48ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] 49If creation fails for a pipeline create info with a 50slink:VkExecutionGraphPipelineCreateInfoAMDX::pname:flags value that 51included ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT, all pipelines 52at a greater index all automatically fail. 53endif::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] 54 55.Valid Usage 56**** 57 * [[VUID-vkCreateExecutionGraphPipelinesAMDX-shaderEnqueue-09124]] 58 The <<features-shaderEnqueue,pname:shaderEnqueue feature>> must: be 59 enabled 60 * [[VUID-vkCreateExecutionGraphPipelinesAMDX-flags-09125]] 61 If the pname:flags member of any element of pname:pCreateInfos contains 62 the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the 63 pname:basePipelineIndex member of that same element is not `-1`, 64 pname:basePipelineIndex must: be less than the index into 65 pname:pCreateInfos that corresponds to that element 66 * [[VUID-vkCreateExecutionGraphPipelinesAMDX-flags-09126]] 67 If the pname:flags member of any element of pname:pCreateInfos contains 68 the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline 69 must: have been created with the 70 ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set 71ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] 72 * [[VUID-vkCreateExecutionGraphPipelinesAMDX-pipelineCache-09127]] 73 If pname:pipelineCache was created with 74 ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, host access 75 to pname:pipelineCache must: be 76 <<fundamentals-threadingbehavior,externally synchronized>> 77endif::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] 78**** 79 80include::{generated}/validity/protos/vkCreateExecutionGraphPipelinesAMDX.adoc[] 81-- 82 83[open,refpage='VkExecutionGraphPipelineCreateInfoAMDX',desc='Structure specifying parameters of a newly created execution graph pipeline',type='structs'] 84-- 85:refpage: VkExecutionGraphPipelineCreateInfoAMDX 86 87The sname:VkExecutionGraphPipelineCreateInfoAMDX structure is defined as: 88 89include::{generated}/api/structs/VkExecutionGraphPipelineCreateInfoAMDX.adoc[] 90 91 * pname:sType is a elink:VkStructureType value identifying this structure. 92 * pname:pNext is `NULL` or a pointer to a structure extending this 93 structure. 94 * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying 95 how the pipeline will be generated. 96 * pname:stageCount is the number of entries in the pname:pStages array. 97 * pname:pStages is a pointer to an array of pname:stageCount 98 slink:VkPipelineShaderStageCreateInfo structures describing the set of 99 the shader stages to be included in the execution graph pipeline. 100 * pname:pLibraryInfo is a pointer to a 101 slink:VkPipelineLibraryCreateInfoKHR structure defining pipeline 102 libraries to include. 103 * pname:layout is the description of binding locations used by both the 104 pipeline and descriptor sets used with the pipeline. 105 * pname:basePipelineHandle is a pipeline to derive from 106 * pname:basePipelineIndex is an index into the pname:pCreateInfos 107 parameter to use as a pipeline to derive from 108 109The parameters pname:basePipelineHandle and pname:basePipelineIndex are 110described in more detail in <<pipelines-pipeline-derivatives,Pipeline 111Derivatives>>. 112 113Each shader stage provided when creating an execution graph pipeline 114(including those in libraries) is associated with a name and an index, 115determined by the inclusion or omission of a 116slink:VkPipelineShaderStageNodeCreateInfoAMDX structure in its pname:pNext 117chain. 118 119In addition to the shader name and index, an internal "node index" is also 120generated for each node, which can be queried with 121flink:vkGetExecutionGraphPipelineNodeIndexAMDX, and is used exclusively for 122initial dispatch of an execution graph. 123 124.Valid Usage 125**** 126:pipelineType: execution graph 127include::{chapters}/commonvalidity/pipeline_create_info_common.adoc[] 128include::{chapters}/commonvalidity/compute_graph_pipeline_create_info_common.adoc[] 129 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-stage-09128]] 130 The pname:stage member of any element of pname:pStages must: be 131 ename:VK_SHADER_STAGE_COMPUTE_BIT 132 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-pStages-09129]] 133 The shader code for the entry point identified by each element of 134 pname:pStages and the rest of the state identified by this structure 135 must: adhere to the pipeline linking rules described in the 136 <<interfaces,Shader Interfaces>> chapter 137 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-layout-09130]] 138 pname:layout must: be 139 <<descriptorsets-pipelinelayout-consistency,consistent>> with the layout 140 of the shaders specified in pname:pStages 141 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-pLibraryInfo-09131]] 142 If pname:pLibraryInfo is not `NULL`, each element of its 143 pname:pLibraries member must: have been created with a pname:layout that 144 is compatible with the pname:layout in this pipeline 145 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-layout-09132]] 146 The number of resources in pname:layout accessible to each shader stage 147 that is used by the pipeline must: be less than or equal to 148 sname:VkPhysicalDeviceLimits::pname:maxPerStageResources 149 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-pLibraryInfo-09133]] 150 If pname:pLibraryInfo is not `NULL`, each element of 151 pname:pLibraryInfo->libraries must: be either a compute pipeline or an 152 execution graph pipeline 153 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-None-09134]] 154 There must: be no two nodes in the pipeline that share both the same 155 shader name and index, as specified by 156 slink:VkPipelineShaderStageNodeCreateInfoAMDX 157 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-None-09135]] 158 There must: be no two nodes in the pipeline that share the same shader 159 name and have input payload declarations with different sizes 160 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-None-09136]] 161 There must: be no two nodes in the pipeline that share the same name but 162 have different execution models 163 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-CoalescedInputCountAMDX-09137]] 164 There must: be no two nodes in the pipeline that share the same name 165 where one includes code:CoalescedInputCountAMDX and the other does not 166 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-StaticNumWorkgroupsAMDX-09138]] 167 There must: be no two nodes in the pipeline that share the same name 168 where one includes code:StaticNumWorkgroupsAMDX and the other does not 169 * [[VUID-VkExecutionGraphPipelineCreateInfoAMDX-PayloadNodeNameAMDX-09139]] 170 If an output payload declared in any shader in the pipeline has a 171 code:PayloadNodeNameAMDX decoration with a code:Node code:Name that 172 matches the shader name of any other node in the graph, the size of the 173 output payload must: match the size of the input payload in the matching 174 node 175**** 176 177include::{generated}/validity/structs/VkExecutionGraphPipelineCreateInfoAMDX.adoc[] 178-- 179 180[open,refpage='VK_SHADER_INDEX_UNUSED_AMDX',desc='Sentinel for an unused shader index',type='consts'] 181-- 182ename:VK_SHADER_INDEX_UNUSED_AMDX is a special shader index used to indicate 183that the created node does not override the index. 184In this case, the shader index is determined through other means. 185It is defined as: 186 187include::{generated}/api/enums/VK_SHADER_INDEX_UNUSED_AMDX.adoc[] 188-- 189 190[open,refpage='VkPipelineShaderStageNodeCreateInfoAMDX',desc='Structure specifying the shader name and index with an execution graph',type='structs'] 191-- 192:refpage: VkPipelineShaderStageNodeCreateInfoAMDX 193 194The sname:VkPipelineShaderStageNodeCreateInfoAMDX structure is defined as: 195 196include::{generated}/api/structs/VkPipelineShaderStageNodeCreateInfoAMDX.adoc[] 197 198 * pname:sType is a elink:VkStructureType value identifying this structure. 199 * pname:pNext is `NULL` or a pointer to a structure extending this 200 structure. 201 * pname:pName is the shader name to use when creating a node in an 202 execution graph. 203 If pname:pName is `NULL`, the name of the entry point specified in 204 SPIR-V is used as the shader name. 205 * pname:index is the shader index to use when creating a node in an 206 execution graph. 207 If pname:index is ename:VK_SHADER_INDEX_UNUSED_AMDX then the original 208 index is used, either as specified by the code:ShaderIndexAMDX execution 209 mode, or `0` if that too is not specified. 210 211When included in the pname:pNext chain of a 212slink:VkPipelineShaderStageCreateInfo structure, this structure specifies 213the shader name and shader index of a node when creating an execution graph 214pipeline. 215If this structure is omitted, the shader name is set to the name of the 216entry point in SPIR-V and the shader index is set to `0`. 217 218When dispatching a node from another shader, the name is fixed at pipeline 219creation, but the index can: be set dynamically. 220By associating multiple shaders with the same name but different indexes, 221applications can dynamically select different nodes to execute. 222Applications must: ensure each node has a unique name and index. 223 224include::{generated}/validity/structs/VkPipelineShaderStageNodeCreateInfoAMDX.adoc[] 225-- 226 227[open,refpage='vkGetExecutionGraphPipelineNodeIndexAMDX',desc='Query internal id of a node in an execution graph',type='protos'] 228-- 229:refpage: vkGetExecutionGraphPipelineNodeIndexAMDX 230 231To query the internal node index for a particular node in an execution 232graph, call: 233 234include::{generated}/api/protos/vkGetExecutionGraphPipelineNodeIndexAMDX.adoc[] 235 236 * pname:device is the that pname:executionGraph was created on. 237 * pname:executionGraph is the execution graph pipeline to query the 238 internal node index for. 239 * pname:pNodeInfo is a pointer to a 240 slink:VkPipelineShaderStageNodeCreateInfoAMDX structure identifying the 241 name and index of the node to query. 242 * pname:pNodeIndex is the returned internal node index of the identified 243 node. 244 245Once this function returns, the contents of pname:pNodeIndex contain the 246internal node index of the identified node. 247 248 249.Valid Usage 250**** 251 * [[VUID-vkGetExecutionGraphPipelineNodeIndexAMDX-pNodeInfo-09140]] 252 pname:pNodeInfo->pName must: not be `NULL` 253 * [[VUID-vkGetExecutionGraphPipelineNodeIndexAMDX-pNodeInfo-09141]] 254 pname:pNodeInfo->index must: not be ename:VK_SHADER_INDEX_UNUSED_AMDX 255 * [[VUID-vkGetExecutionGraphPipelineNodeIndexAMDX-executionGraph-09142]] 256 There must: be a node in pname:executionGraph with a shader name and 257 index equal to pname:pNodeInfo->pName and pname:pNodeInfo->index 258**** 259 260include::{generated}/validity/protos/vkGetExecutionGraphPipelineNodeIndexAMDX.adoc[] 261-- 262 263 264== Initializing Scratch Memory 265 266Implementations may: need scratch memory to manage dispatch queues or 267similar when executing a pipeline graph, and this is explicitly managed by 268the application. 269 270[open,refpage='vkGetExecutionGraphPipelineScratchSizeAMDX',desc='Query scratch space required to dispatch an execution graph',type='protos'] 271-- 272:refpage: vkGetExecutionGraphPipelineScratchSizeAMDX 273 274To query the scratch space required to dispatch an execution graph, call: 275 276include::{generated}/api/protos/vkGetExecutionGraphPipelineScratchSizeAMDX.adoc[] 277 278 * pname:device is the that pname:executionGraph was created on. 279 * pname:executionGraph is the execution graph pipeline to query the 280 scratch space for. 281 * pname:pSizeInfo is a pointer to a 282 slink:VkExecutionGraphPipelineScratchSizeAMDX structure that will 283 contain the required scratch size. 284 285After this function returns, information about the scratch space required 286will be returned in pname:pSizeInfo. 287 288include::{generated}/validity/protos/vkGetExecutionGraphPipelineScratchSizeAMDX.adoc[] 289-- 290 291[open,refpage='VkExecutionGraphPipelineScratchSizeAMDX',desc='Structure describing the scratch space required to dispatch an execution graph',type='structs'] 292-- 293:refpage: VkExecutionGraphPipelineScratchSizeAMDX 294 295The sname:VkExecutionGraphPipelineScratchSizeAMDX structure is defined as: 296 297include::{generated}/api/structs/VkExecutionGraphPipelineScratchSizeAMDX.adoc[] 298 299 * pname:sType is a elink:VkStructureType value identifying this structure. 300 * pname:pNext is `NULL` or a pointer to a structure extending this 301 structure. 302 * pname:size indicates the scratch space required for dispatch the queried 303 execution graph. 304 305include::{generated}/validity/structs/VkExecutionGraphPipelineScratchSizeAMDX.adoc[] 306-- 307 308[open,refpage='vkCmdInitializeGraphScratchMemoryAMDX',desc='Initialize scratch memory for an execution graph',type='protos'] 309-- 310:refpage: vkCmdInitializeGraphScratchMemoryAMDX 311 312To initialize scratch memory for a particular execution graph, call: 313 314include::{generated}/api/protos/vkCmdInitializeGraphScratchMemoryAMDX.adoc[] 315 316 * pname:commandBuffer is the command buffer into which the command will be 317 recorded. 318 * pname:scratch is a pointer to the scratch memory to be initialized. 319 320This command must: be called before using pname:scratch to dispatch the 321currently bound execution graph pipeline. 322 323Execution of this command may: modify any memory locations in the range 324[pname:scratch,pname:scratch + pname:size), where pname:size is the value 325returned in slink:VkExecutionGraphPipelineScratchSizeAMDX::pname:size by 326slink:VkExecutionGraphPipelineScratchSizeAMDX for the currently bound 327execution graph pipeline. 328Accesses to this memory range are performed in the 329ename:VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the 330ename:VK_ACCESS_2_SHADER_STORAGE_READ_BIT and 331ename:VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT access flags. 332 333If any portion of pname:scratch is modified by any command other than 334flink:vkCmdDispatchGraphAMDX, flink:vkCmdDispatchGraphIndirectAMDX, 335flink:vkCmdDispatchGraphIndirectCountAMDX, or 336fname:vkCmdInitializeGraphScratchMemoryAMDX with the same execution graph, 337it must: be reinitialized for the execution graph again before dispatching 338against it. 339 340.Valid Usage 341**** 342 * [[VUID-vkCmdInitializeGraphScratchMemoryAMDX-scratch-09143]] 343 pname:scratch must: be the device address of an allocated memory range 344 at least as large as the value of 345 slink:VkExecutionGraphPipelineScratchSizeAMDX::pname:size returned by 346 slink:VkExecutionGraphPipelineScratchSizeAMDX for the currently bound 347 execution graph pipeline. 348 * [[VUID-vkCmdInitializeGraphScratchMemoryAMDX-scratch-09144]] 349 pname:scratch must: be a multiple of 64 350**** 351 352include::{generated}/validity/protos/vkCmdInitializeGraphScratchMemoryAMDX.adoc[] 353-- 354 355 356== Dispatching a Graph 357 358Initial dispatch of an execution graph is done from the host in the same way 359as any other command, and can: be used in a similar way to compute dispatch 360commands, with indirect variants available. 361 362[open,refpage='vkCmdDispatchGraphAMDX',desc='Dispatch an execution graph',type='protos'] 363-- 364:refpage: vkCmdDispatchGraphAMDX 365 366To record an execution graph dispatch, call: 367 368include::{generated}/api/protos/vkCmdDispatchGraphAMDX.adoc[] 369 370 * pname:commandBuffer is the command buffer into which the command will be 371 recorded. 372 * pname:scratch is a pointer to the scratch memory to be used. 373 * pname:pCountInfo is a host pointer to a 374 slink:VkDispatchGraphCountInfoAMDX structure defining the nodes which 375 will be initially executed. 376 377When this command is executed, the nodes specified in pname:pCountInfo are 378executed. 379Nodes executed as part of this command are not implicitly synchronized in 380any way against each other once they are dispatched. 381 382For this command, all device/host pointers in substructures are treated as 383host pointers and read only during host execution of this command. 384Once this command returns, no reference to the original pointers is 385retained. 386 387Execution of this command may: modify any memory locations in the range 388[pname:scratch,pname:scratch + pname:size), where pname:size is the value 389returned in slink:VkExecutionGraphPipelineScratchSizeAMDX::pname:size by 390slink:VkExecutionGraphPipelineScratchSizeAMDX for the currently bound 391execution graph pipeline Accesses to this memory range are performed in the 392ename:VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the 393ename:VK_ACCESS_2_SHADER_STORAGE_READ_BIT and 394ename:VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT access flags. 395 396.Valid Usage 397**** 398include::{chapters}/commonvalidity/dispatch_graph_common.adoc[] 399 * [[VUID-vkCmdDispatchGraphAMDX-pCountInfo-09145]] 400 pname:pCountInfo->infos must: be a host pointer to a memory allocation 401 at least as large as the product of pname:count and pname:stride 402 * [[VUID-vkCmdDispatchGraphAMDX-infos-09146]] 403 Host memory locations at indexes in the range [pname:infos, pname:infos 404 + (pname:count*pname:stride)), at a granularity of pname:stride must: 405 contain valid slink:VkDispatchGraphInfoAMDX structures in the first 24 406 bytes 407 * [[VUID-vkCmdDispatchGraphAMDX-pCountInfo-09147]] 408 For each slink:VkDispatchGraphInfoAMDX structure in 409 pname:pCountInfo->infos, pname:payloads must: be a host pointer to a 410 memory allocation at least as large as the product of pname:payloadCount 411 and pname:payloadStride 412 * [[VUID-vkCmdDispatchGraphAMDX-pCountInfo-09148]] 413 For each slink:VkDispatchGraphInfoAMDX structure in 414 pname:pCountInfo->infos, pname:nodeIndex must: be a valid node index in 415 the currently bound execution graph pipeline, as returned by 416 flink:vkGetExecutionGraphPipelineNodeIndexAMDX 417 * [[VUID-vkCmdDispatchGraphAMDX-pCountInfo-09149]] 418 For each slink:VkDispatchGraphInfoAMDX structure in 419 pname:pCountInfo->infos, host memory locations at indexes in the range 420 [pname:payloads, pname:payloads + (pname:payloadCount * 421 pname:payloadStride)), at a granularity of pname:payloadStride must: 422 contain a payload matching the size of the input payload expected by the 423 node in pname:nodeIndex in the first bytes 424**** 425 426include::{generated}/validity/protos/vkCmdDispatchGraphAMDX.adoc[] 427-- 428 429[open,refpage='vkCmdDispatchGraphIndirectAMDX',desc='Dispatch an execution graph with node and payload parameters read on the device',type='protos'] 430-- 431:refpage: vkCmdDispatchGraphIndirectAMDX 432 433To record an execution graph dispatch with node and payload parameters read 434on device, call: 435 436include::{generated}/api/protos/vkCmdDispatchGraphIndirectAMDX.adoc[] 437 438 * pname:commandBuffer is the command buffer into which the command will be 439 recorded. 440 * pname:scratch is a pointer to the scratch memory to be used. 441 * pname:pCountInfo is a host pointer to a 442 slink:VkDispatchGraphCountInfoAMDX structure defining the nodes which 443 will be initially executed. 444 445When this command is executed, the nodes specified in pname:pCountInfo are 446executed. 447Nodes executed as part of this command are not implicitly synchronized in 448any way against each other once they are dispatched. 449 450For this command, all device/host pointers in substructures are treated as 451device pointers and read during device execution of this command. 452The allocation and contents of these pointers only needs to be valid during 453device execution. 454All of these addresses will be read in the 455ename:VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the 456ename:VK_ACCESS_2_SHADER_STORAGE_READ_BIT access flag. 457 458Execution of this command may: modify any memory locations in the range 459[pname:scratch,pname:scratch + pname:size), where pname:size is the value 460returned in slink:VkExecutionGraphPipelineScratchSizeAMDX::pname:size by 461slink:VkExecutionGraphPipelineScratchSizeAMDX for the currently bound 462execution graph pipeline. 463Accesses to this memory range are performed in the 464ename:VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the 465ename:VK_ACCESS_2_SHADER_STORAGE_READ_BIT and 466ename:VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT access flags. 467 468.Valid Usage 469**** 470include::{chapters}/commonvalidity/dispatch_graph_common.adoc[] 471 * [[VUID-vkCmdDispatchGraphIndirectAMDX-pCountInfo-09150]] 472 pname:pCountInfo->infos must: be a device pointer to a memory allocation 473 at least as large as the product of pname:count and pname:stride when 474 this command is executed on the device 475 * [[VUID-vkCmdDispatchGraphIndirectAMDX-pCountInfo-09151]] 476 pname:pCountInfo->infos must: be a device address within a 477 slink:VkBuffer created with the 478 ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT flag 479 * [[VUID-vkCmdDispatchGraphIndirectAMDX-pCountInfo-09152]] 480 pname:pCountInfo->infos must: be a multiple of 481 <<limits-executionGraphDispatchAddressAlignment, 482 pname:executionGraphDispatchAddressAlignment>> 483 * [[VUID-vkCmdDispatchGraphIndirectAMDX-infos-09153]] 484 Device memory locations at indexes in the range [pname:infos, 485 pname:infos + (pname:count*pname:stride)), at a granularity of 486 pname:stride must: contain valid slink:VkDispatchGraphInfoAMDX 487 structures in the first 24 bytes when this command is executed on the 488 device 489 * [[VUID-vkCmdDispatchGraphIndirectAMDX-pCountInfo-09154]] 490 For each slink:VkDispatchGraphInfoAMDX structure in 491 pname:pCountInfo->infos, pname:payloads must: be a device pointer to a 492 memory allocation at least as large as the product of pname:payloadCount 493 and pname:payloadStride when this command is executed on the device 494 * [[VUID-vkCmdDispatchGraphIndirectAMDX-pCountInfo-09155]] 495 For each slink:VkDispatchGraphInfoAMDX structure in 496 pname:pCountInfo->infos, pname:payloads must: be a device address within 497 a slink:VkBuffer created with the 498 ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT flag 499 * [[VUID-vkCmdDispatchGraphIndirectAMDX-pCountInfo-09156]] 500 For each slink:VkDispatchGraphInfoAMDX structure in 501 pname:pCountInfo->infos, pname:payloads must: be a multiple of 502 <<limits-executionGraphDispatchAddressAlignment, 503 pname:executionGraphDispatchAddressAlignment>> 504 * [[VUID-vkCmdDispatchGraphIndirectAMDX-pCountInfo-09157]] 505 For each slink:VkDispatchGraphInfoAMDX structure in 506 pname:pCountInfo->infos, pname:nodeIndex must: be a valid node index in 507 the currently bound execution graph pipeline, as returned by 508 flink:vkGetExecutionGraphPipelineNodeIndexAMDX when this command is 509 executed on the device 510 * [[VUID-vkCmdDispatchGraphIndirectAMDX-pCountInfo-09158]] 511 For each slink:VkDispatchGraphInfoAMDX structure in 512 pname:pCountInfo->infos, device memory locations at indexes in the range 513 [pname:payloads, pname:payloads + (pname:payloadCount * 514 pname:payloadStride)), at a granularity of pname:payloadStride must: 515 contain a payload matching the size of the input payload expected by the 516 node in pname:nodeIndex in the first bytes when this command is executed 517 on the device 518**** 519 520include::{generated}/validity/protos/vkCmdDispatchGraphIndirectAMDX.adoc[] 521-- 522 523[open,refpage='vkCmdDispatchGraphIndirectCountAMDX',desc='Dispatch an execution graph with all parameters read on the device',type='protos'] 524-- 525:refpage: vkCmdDispatchGraphIndirectCountAMDX 526 527To record an execution graph dispatch with all parameters read on device, 528call: 529 530include::{generated}/api/protos/vkCmdDispatchGraphIndirectCountAMDX.adoc[] 531 532 * pname:commandBuffer is the command buffer into which the command will be 533 recorded. 534 * pname:scratch is a pointer to the scratch memory to be used. 535 * pname:countInfo is a device address of a 536 slink:VkDispatchGraphCountInfoAMDX structure defining the nodes which 537 will be initially executed. 538 539When this command is executed, the nodes specified in pname:countInfo are 540executed. 541Nodes executed as part of this command are not implicitly synchronized in 542any way against each other once they are dispatched. 543 544For this command, all pointers in substructures are treated as device 545pointers and read during device execution of this command. 546The allocation and contents of these pointers only needs to be valid during 547device execution. 548All of these addresses will be read in the 549ename:VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the 550ename:VK_ACCESS_2_SHADER_STORAGE_READ_BIT access flag. 551 552Execution of this command may: modify any memory locations in the range 553[pname:scratch,pname:scratch + pname:size), where pname:size is the value 554returned in slink:VkExecutionGraphPipelineScratchSizeAMDX::pname:size by 555slink:VkExecutionGraphPipelineScratchSizeAMDX for the currently bound 556execution graph pipeline. 557Accesses to this memory range are performed in the 558ename:VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the 559ename:VK_ACCESS_2_SHADER_STORAGE_READ_BIT and 560ename:VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT access flags. 561 562.Valid Usage 563**** 564include::{chapters}/commonvalidity/dispatch_graph_common.adoc[] 565 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-countInfo-09159]] 566 pname:countInfo must: be a device pointer to a memory allocation 567 containing a valid slink:VkDispatchGraphCountInfoAMDX structure when 568 this command is executed on the device 569 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-countInfo-09160]] 570 pname:countInfo must: be a device address within a slink:VkBuffer 571 created with the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT flag 572 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-countInfo-09161]] 573 pname:countInfo must: be a multiple of 574 <<limits-executionGraphDispatchAddressAlignment, 575 pname:executionGraphDispatchAddressAlignment>> 576 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-countInfo-09162]] 577 pname:countInfo->infos must: be a device pointer to a memory allocation 578 at least as large as the product of pname:count and pname:stride when 579 this command is executed on the device 580 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-countInfo-09163]] 581 pname:countInfo->infos must: be a device address within a slink:VkBuffer 582 created with the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT flag 583 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-countInfo-09164]] 584 pname:countInfo->infos must: be a multiple of 585 <<limits-executionGraphDispatchAddressAlignment, 586 pname:executionGraphDispatchAddressAlignment>> 587 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-infos-09165]] 588 Device memory locations at indexes in the range [pname:infos, 589 pname:infos + (pname:count*pname:stride)), at a granularity of 590 pname:stride must: contain valid slink:VkDispatchGraphInfoAMDX 591 structures in the first 24 bytes when this command is executed on the 592 device 593 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-countInfo-09166]] 594 For each slink:VkDispatchGraphInfoAMDX structure in 595 pname:countInfo->infos, pname:payloads must: be a device pointer to a 596 memory allocation at least as large as the product of pname:payloadCount 597 and pname:payloadStride when this command is executed on the device 598 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-countInfo-09167]] 599 For each slink:VkDispatchGraphInfoAMDX structure in 600 pname:countInfo->infos, pname:payloads must: be a device address within 601 a slink:VkBuffer created with the 602 ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT flag 603 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-countInfo-09168]] 604 For each slink:VkDispatchGraphInfoAMDX structure in 605 pname:countInfo->infos, pname:payloads must: be a multiple of 606 <<limits-executionGraphDispatchAddressAlignment, 607 pname:executionGraphDispatchAddressAlignment>> 608 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-countInfo-09169]] 609 For each slink:VkDispatchGraphInfoAMDX structure in 610 pname:countInfo->infos, pname:nodeIndex must: be a valid node index in 611 the currently bound execution graph pipeline, as returned by 612 flink:vkGetExecutionGraphPipelineNodeIndexAMDX when this command is 613 executed on the device 614 * [[VUID-vkCmdDispatchGraphIndirectCountAMDX-countInfo-09170]] 615 For each slink:VkDispatchGraphInfoAMDX structure in 616 pname:countInfo->infos, device memory locations at indexes in the range 617 [pname:payloads, pname:payloads + (pname:payloadCount * 618 pname:payloadStride)), at a granularity of pname:payloadStride must: 619 contain a payload matching the size of the input payload expected by the 620 node in pname:nodeIndex in the first bytes when this command is executed 621 on the device 622**** 623 624include::{generated}/validity/protos/vkCmdDispatchGraphIndirectCountAMDX.adoc[] 625-- 626 627[open,refpage='VkDeviceOrHostAddressConstAMDX',desc='Union specifying a const device or host address',type='structs'] 628-- 629:refpage: VkDeviceOrHostAddressConstAMDX 630 631The sname:VkDeviceOrHostAddressConstAMDX union is defined as: 632 633include::{generated}/api/structs/VkDeviceOrHostAddressConstAMDX.adoc[] 634 635 * pname:deviceAddress is a buffer device address as returned by the 636 flink:vkGetBufferDeviceAddressKHR command. 637 * pname:hostAddress is a const host memory address. 638 639include::{generated}/validity/structs/VkDeviceOrHostAddressConstAMDX.adoc[] 640-- 641 642[open,refpage='VkDispatchGraphCountInfoAMDX',desc='Structure specifying count parameters for execution graph dispatch',type='structs',xrefs='vkCmdDispatchGraphIndirectCountAMDX'] 643-- 644:refpage: VkDispatchGraphCountInfoAMDX 645 646The sname:VkDispatchGraphCountInfoAMDX structure is defined as: 647 648include::{generated}/api/structs/VkDispatchGraphCountInfoAMDX.adoc[] 649 650 * pname:count is the number of dispatches to perform. 651 * pname:infos is the device or host address of a flat array of 652 slink:VkDispatchGraphInfoAMDX structures 653 * pname:stride is the byte stride between successive 654 slink:VkDispatchGraphInfoAMDX structures in pname:infos 655 656Whether pname:infos is consumed as a device or host pointer is defined by 657the command this structure is used in. 658 659include::{generated}/validity/structs/VkDispatchGraphCountInfoAMDX.adoc[] 660-- 661 662[open,refpage='VkDispatchGraphInfoAMDX',desc='Structure specifying node parameters for execution graph dispatch',type='structs',xrefs='VkDispatchGraphCountInfoAMDX'] 663-- 664:refpage: VkDispatchGraphInfoAMDX 665 666The sname:VkDispatchGraphInfoAMDX structure is defined as: 667 668include::{generated}/api/structs/VkDispatchGraphInfoAMDX.adoc[] 669 670 * pname:nodeIndex is the index of a node in an execution graph to be 671 dispatched. 672 * pname:payloadCount is the number of payloads to dispatch for the 673 specified node. 674 * pname:payloads is a device or host address pointer to a flat array of 675 payloads with size equal to the product of pname:payloadCount and 676 pname:payloadStride 677 * pname:payloadStride is the byte stride between successive payloads in 678 pname:payloads 679 680Whether pname:payloads is consumed as a device or host pointer is defined by 681the command this structure is used in. 682 683.Valid Usage 684**** 685 * [[VUID-VkDispatchGraphInfoAMDX-payloadCount-09171]] 686 pname:payloadCount must: be no greater than 687 <<limits-maxExecutionGraphShaderPayloadCount, 688 pname:maxExecutionGraphShaderPayloadCount>> 689**** 690 691include::{generated}/validity/structs/VkDispatchGraphInfoAMDX.adoc[] 692-- 693 694 695== Shader Enqueue 696 697Compute shaders in an execution graph can: use the 698code:OpInitializeNodePayloadsAMDX to initialize nodes for dispatch. 699Any node payload initialized in this way will be enqueued for dispatch once 700the shader is done writing to the payload. 701As compilers may: be conservative when making this determination, shaders 702can: further call code:OpFinalizeNodePayloadsAMDX to guarantee that the 703payload is no longer being written. 704 705The code:Node code:Name operand of the code:PayloadNodeNameAMDX decoration 706on a payload identifies the shader name of the node to be enqueued, and the 707code:Shader code:Index operand of code:OpInitializeNodePayloadsAMDX 708identifies the shader index. 709A node identified in this way is dispatched as described in the following 710sections. 711 712 713=== Compute Nodes 714 715Compute shaders added as nodes to an execution graph are executed 716differently based on the presence or absence of the 717code:StaticNumWorkgroupsAMDX or code:CoalescingAMDX execution modes. 718 719Dispatching a compute shader node that does not declare either the 720code:StaticNumWorkgroupsAMDX or code:CoalescingAMDX execution mode will 721execute a number of workgroups in each dimension specified by the first 12 722bytes of the payload, interpreted as a slink:VkDispatchIndirectCommand. 723The same payload will be broadcast to each workgroup in the same dispatch. 724Additional values in the payload are have no effect on execution. 725 726Dispatching a compute shader node with the code:StaticNumWorkgroupsAMDX 727execution mode will execute workgroups in each dimension according to the 728code:x, code:y, and code:z code:size operands to the 729code:StaticNumWorkgroupsAMDX execution mode. 730The same payload will be broadcast to each workgroup in the same dispatch. 731Any values in the payload have no effect on execution. 732 733Dispatching a compute shader node with the code:CoalescingAMDX execution 734mode will enqueue a single invocation for execution. 735Implementations may: combine multiple such dispatches into the same 736workgroup, up to the size of the workgroup. 737The number of invocations coalesced into a given workgroup in this way can: 738be queried via the <<interfaces-builtin-variables-coalescedinputcountamd, 739code:CoalescedInputCountAMDX>> built-in. 740Any values in the payload have no effect on execution. 741