1// Copyright (c) 2018-2020 Advanced Micro Devices, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5// This section is included inside the Pipelines chapter (pipelines.adoc) 6 7[open,refpage='vkGetShaderInfoAMD',desc='Get information about a shader in a pipeline',type='protos'] 8-- 9Information about a particular shader that has been compiled as part of a 10pipeline object can be extracted by calling: 11 12include::{generated}/api/protos/vkGetShaderInfoAMD.adoc[] 13 14 * pname:device is the device that created pname:pipeline. 15 * pname:pipeline is the target of the query. 16 * pname:shaderStage is a elink:VkShaderStageFlagBits specifying the 17 particular shader within the pipeline about which information is being 18 queried. 19 * pname:infoType describes what kind of information is being queried. 20 * pname:pInfoSize is a pointer to a value related to the amount of data 21 the query returns, as described below. 22 * pname:pInfo is either `NULL` or a pointer to a buffer. 23 24If pname:pInfo is `NULL`, then the maximum size of the information that can: 25be retrieved about the shader, in bytes, is returned in pname:pInfoSize. 26Otherwise, pname:pInfoSize must: point to a variable set by the user to the 27size of the buffer, in bytes, pointed to by pname:pInfo, and on return the 28variable is overwritten with the amount of data actually written to 29pname:pInfo. 30If pname:pInfoSize is less than the maximum size that can: be retrieved by 31the pipeline cache, then at most pname:pInfoSize bytes will be written to 32pname:pInfo, and ename:VK_INCOMPLETE will be returned, instead of 33ename:VK_SUCCESS, to indicate that not all required of the pipeline cache 34was returned. 35 36Not all information is available for every shader and implementations may 37not support all kinds of information for any shader. 38When a certain type of information is unavailable, the function returns 39ename:VK_ERROR_FEATURE_NOT_PRESENT. 40 41If information is successfully and fully queried, the function will return 42ename:VK_SUCCESS. 43 44For pname:infoType ename:VK_SHADER_INFO_TYPE_STATISTICS_AMD, a 45sname:VkShaderStatisticsInfoAMD structure will be written to the buffer 46pointed to by pname:pInfo. 47This structure will be populated with statistics regarding the physical 48device resources used by that shader along with other miscellaneous 49information and is described in further detail below. 50 51For pname:infoType ename:VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD, pname:pInfo is 52a pointer to a UTF-8 null-terminated string containing human-readable 53disassembly. 54The exact formatting and contents of the disassembly string are 55vendor-specific. 56 57The formatting and contents of all other types of information, including 58pname:infoType ename:VK_SHADER_INFO_TYPE_BINARY_AMD, are left to the vendor 59and are not further specified by this extension. 60 61include::{generated}/validity/protos/vkGetShaderInfoAMD.adoc[] 62-- 63 64[open,refpage='VkShaderInfoTypeAMD',desc='Enum specifying which type of shader information to query',type='enums'] 65-- 66Possible values of flink:vkGetShaderInfoAMD::pname:infoType, specifying the 67information being queried from a shader, are: 68 69include::{generated}/api/enums/VkShaderInfoTypeAMD.adoc[] 70 71 * ename:VK_SHADER_INFO_TYPE_STATISTICS_AMD specifies that device resources 72 used by a shader will be queried. 73 * ename:VK_SHADER_INFO_TYPE_BINARY_AMD specifies that 74 implementation-specific information will be queried. 75 * ename:VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD specifies that human-readable 76 disassembly of a shader. 77-- 78 79[open,refpage='VkShaderStatisticsInfoAMD',desc='Statistical information about a particular shader within a pipeline',type='structs'] 80-- 81The sname:VkShaderStatisticsInfoAMD structure is defined as: 82 83include::{generated}/api/structs/VkShaderStatisticsInfoAMD.adoc[] 84 85 * pname:shaderStageMask are the combination of logical shader stages 86 contained within this shader. 87 * pname:resourceUsage is a slink:VkShaderResourceUsageAMD structure 88 describing internal physical device resources used by this shader. 89 * pname:numPhysicalVgprs is the maximum number of vector instruction 90 general-purpose registers (VGPRs) available to the physical device. 91 * pname:numPhysicalSgprs is the maximum number of scalar instruction 92 general-purpose registers (SGPRs) available to the physical device. 93 * pname:numAvailableVgprs is the maximum limit of VGPRs made available to 94 the shader compiler. 95 * pname:numAvailableSgprs is the maximum limit of SGPRs made available to 96 the shader compiler. 97 * pname:computeWorkGroupSize is the local workgroup size of this shader in 98 { X, Y, Z } dimensions. 99 100Some implementations may merge multiple logical shader stages together in a 101single shader. 102In such cases, pname:shaderStageMask will contain a bitmask of all of the 103stages that are active within that shader. 104Consequently, if specifying those stages as input to 105flink:vkGetShaderInfoAMD, the same output information may: be returned for 106all such shader stage queries. 107 108The number of available VGPRs and SGPRs (pname:numAvailableVgprs and 109pname:numAvailableSgprs respectively) are the shader-addressable subset of 110physical registers that is given as a limit to the compiler for register 111assignment. 112These values may: further be limited by implementations due to performance 113optimizations where register pressure is a bottleneck. 114 115include::{generated}/validity/structs/VkShaderStatisticsInfoAMD.adoc[] 116-- 117 118[open,refpage='VkShaderResourceUsageAMD',desc='Resource usage information about a particular shader within a pipeline',type='structs'] 119-- 120The sname:VkShaderResourceUsageAMD structure is defined as: 121 122include::{generated}/api/structs/VkShaderResourceUsageAMD.adoc[] 123 124 * pname:numUsedVgprs is the number of vector instruction general-purpose 125 registers used by this shader. 126 * pname:numUsedSgprs is the number of scalar instruction general-purpose 127 registers used by this shader. 128 * pname:ldsSizePerLocalWorkGroup is the maximum local data store size per 129 work group in bytes. 130 * pname:ldsUsageSizeInBytes is the LDS usage size in bytes per work group 131 by this shader. 132 * pname:scratchMemUsageInBytes is the scratch memory usage in bytes by 133 this shader. 134 135include::{generated}/validity/structs/VkShaderResourceUsageAMD.adoc[] 136-- 137