// Copyright (c) 2018-2020 Advanced Micro Devices, Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

// This section is included inside the Pipelines chapter (pipelines.txt)

[open,refpage='vkGetShaderInfoAMD',desc='Get information about a shader in a pipeline',type='protos']
--
Information about a particular shader that has been compiled as part of a
pipeline object can be extracted by calling:

include::{generated}/api/protos/vkGetShaderInfoAMD.txt[]

  * pname:device is the device that created pname:pipeline.
  * pname:pipeline is the target of the query.
  * pname:shaderStage is a elink:VkShaderStageFlagBits specifying the
    particular shader within the pipeline about which information is being
    queried.
  * pname:infoType describes what kind of information is being queried.
  * pname:pInfoSize is a pointer to a value related to the amount of data
    the query returns, as described below.
  * pname:pInfo is either `NULL` or a pointer to a buffer.

If pname:pInfo is `NULL`, then the maximum size of the information that can:
be retrieved about the shader, in bytes, is returned in pname:pInfoSize.
Otherwise, pname:pInfoSize must: point to a variable set by the user to the
size of the buffer, in bytes, pointed to by pname:pInfo, and on return the
variable is overwritten with the amount of data actually written to
pname:pInfo.
If pname:pInfoSize is less than the maximum size that can: be retrieved by
the pipeline cache, then at most pname:pInfoSize bytes will be written to
pname:pInfo, and ename:VK_INCOMPLETE will be returned, instead of
ename:VK_SUCCESS, to indicate that not all required of the pipeline cache
was returned.

Not all information is available for every shader and implementations may
not support all kinds of information for any shader.
When a certain type of information is unavailable, the function returns
ename:VK_ERROR_FEATURE_NOT_PRESENT.

If information is successfully and fully queried, the function will return
ename:VK_SUCCESS.

For pname:infoType ename:VK_SHADER_INFO_TYPE_STATISTICS_AMD, a
sname:VkShaderStatisticsInfoAMD structure will be written to the buffer
pointed to by pname:pInfo.
This structure will be populated with statistics regarding the physical
device resources used by that shader along with other miscellaneous
information and is described in further detail below.

For pname:infoType ename:VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD, pname:pInfo is
a pointer to a UTF-8 null-terminated string containing human-readable
disassembly.
The exact formatting and contents of the disassembly string are
vendor-specific.

The formatting and contents of all other types of information, including
pname:infoType ename:VK_SHADER_INFO_TYPE_BINARY_AMD, are left to the vendor
and are not further specified by this extension.

include::{generated}/validity/protos/vkGetShaderInfoAMD.txt[]
--

[open,refpage='VkShaderInfoTypeAMD',desc='Enum specifying which type of shader information to query',type='enums']
--
Possible values of flink:vkGetShaderInfoAMD::pname:infoType, specifying the
information being queried from a shader, are:

include::{generated}/api/enums/VkShaderInfoTypeAMD.txt[]

  * ename:VK_SHADER_INFO_TYPE_STATISTICS_AMD specifies that device resources
    used by a shader will be queried.
  * ename:VK_SHADER_INFO_TYPE_BINARY_AMD specifies that
    implementation-specific information will be queried.
  * ename:VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD specifies that human-readable
    dissassembly of a shader.
--

[open,refpage='VkShaderStatisticsInfoAMD',desc='Statistical information about a particular shader within a pipeline',type='structs']
--
The sname:VkShaderStatisticsInfoAMD structure is defined as:

include::{generated}/api/structs/VkShaderStatisticsInfoAMD.txt[]

  * pname:shaderStageMask are the combination of logical shader stages
    contained within this shader.
  * pname:resourceUsage is a slink:VkShaderResourceUsageAMD structure
    describing internal physical device resources used by this shader.
  * pname:numPhysicalVgprs is the maximum number of vector instruction
    general-purpose registers (VGPRs) available to the physical device.
  * pname:numPhysicalSgprs is the maximum number of scalar instruction
    general-purpose registers (SGPRs) available to the physical device.
  * pname:numAvailableVgprs is the maximum limit of VGPRs made available to
    the shader compiler.
  * pname:numAvailableSgprs is the maximum limit of SGPRs made available to
    the shader compiler.
  * pname:computeWorkGroupSize is the local workgroup size of this shader in
    { X, Y, Z } dimensions.

Some implementations may merge multiple logical shader stages together in a
single shader.
In such cases, pname:shaderStageMask will contain a bitmask of all of the
stages that are active within that shader.
Consequently, if specifying those stages as input to
flink:vkGetShaderInfoAMD, the same output information may: be returned for
all such shader stage queries.

The number of available VGPRs and SGPRs (pname:numAvailableVgprs and
pname:numAvailableSgprs respectively) are the shader-addressable subset of
physical registers that is given as a limit to the compiler for register
assignment.
These values may: further be limited by implementations due to performance
optimizations where register pressure is a bottleneck.

include::{generated}/validity/structs/VkShaderStatisticsInfoAMD.txt[]
--

[open,refpage='VkShaderResourceUsageAMD',desc='Resource usage information about a particular shader within a pipeline',type='structs']
--
The sname:VkShaderResourceUsageAMD structure is defined as:

include::{generated}/api/structs/VkShaderResourceUsageAMD.txt[]

  * pname:numUsedVgprs is the number of vector instruction general-purpose
    registers used by this shader.
  * pname:numUsedSgprs is the number of scalar instruction general-purpose
    registers used by this shader.
  * pname:ldsSizePerLocalWorkGroup is the maximum local data store size per
    work group in bytes.
  * pname:ldsUsageSizeInBytes is the LDS usage size in bytes per work group
    by this shader.
  * pname:scratchMemUsageInBytes is the scratch memory usage in bytes by
    this shader.

include::{generated}/validity/structs/VkShaderResourceUsageAMD.txt[]
--