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