Vulkan.Extensions.VK_AMD_gpa_interface

vkCreateGpaSessionAMD - Create a new GPA session object

Valid Usage (Implicit)

• device must be a valid Device handle

• pCreateInfo must be a valid pointer to a valid GpaSessionCreateInfoAMD structure

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure

• pGpaSession must be a valid pointer to a GpaSessionAMD handle

• The device must have been created with at least 1 queue

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_AMD_gpa_interface, AllocationCallbacks, Device, GpaSessionAMD, GpaSessionCreateInfoAMD

A convenience wrapper to make a compatible pair of calls to createGpaSessionAMD and destroyGpaSessionAMD

To ensure that destroyGpaSessionAMD is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

vkDestroyGpaSessionAMD - Destroy a GPA session object

Valid Usage

• All submitted commands that refer to gpaSession must have completed execution

Valid Usage (Implicit)

• device must be a valid Device handle

• If gpaSession is not NULL_HANDLE, gpaSession must be a valid GpaSessionAMD handle

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure

• If gpaSession is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to gpaSession must be externally synchronized

See Also

VK_AMD_gpa_interface, AllocationCallbacks, Device, GpaSessionAMD

vkSetGpaDeviceClockModeAMD - Setting a device clock

Valid Usage

• The ::clockModes feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pInfo must be a valid pointer to a GpaDeviceClockModeInfoAMD structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_AMD_gpa_interface, Device, GpaDeviceClockModeInfoAMD

vkGetGpaDeviceClockInfoAMD - Getting device clocks and ratios

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_AMD_gpa_interface, Device, GpaDeviceGetClockInfoAMD

vkCmdBeginGpaSessionAMD - Begin a GPA session

Valid Usage

• If gpaSession has been used previously to begin and end a session, resetGpaSessionAMD must have first been called

• If another GPA session has been started with cmdBeginGpaSessionAMD in commandBuffer, it must have been ended using cmdEndGpaSessionAMD before this call

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• gpaSession must be a valid GpaSessionAMD handle

• commandBuffer must be in the recording state

• The CommandPool that commandBuffer was allocated from must support QUEUE_COMPUTE_BIT, or QUEUE_GRAPHICS_BIT operations

• This command must not be called between suspended render pass instances

• This command must only be called outside of a video coding scope

• Both of commandBuffer, and gpaSession must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Conditional Rendering

vkCmdBeginGpaSessionAMD is not affected by conditional rendering

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_AMD_gpa_interface, CommandBuffer, GpaSessionAMD

vkCmdEndGpaSessionAMD - End a GPA session

Valid Usage

• gpaSession must have previously begun using cmdBeginGpaSessionAMD

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• gpaSession must be a valid GpaSessionAMD handle

• commandBuffer must be in the recording state

• The CommandPool that commandBuffer was allocated from must support QUEUE_COMPUTE_BIT, or QUEUE_GRAPHICS_BIT operations

• This command must not be called between suspended render pass instances

• This command must only be called outside of a video coding scope

• Both of commandBuffer, and gpaSession must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Conditional Rendering

vkCmdEndGpaSessionAMD is not affected by conditional rendering

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_AMD_gpa_interface, CommandBuffer, GpaSessionAMD

vkCmdBeginGpaSampleAMD - Beginning a sample

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• gpaSession must be a valid GpaSessionAMD handle

• pGpaSampleBeginInfo must be a valid pointer to a valid GpaSampleBeginInfoAMD structure

• pSampleID must be a valid pointer to a uint32_t value

• commandBuffer must be in the recording state

• The CommandPool that commandBuffer was allocated from must support QUEUE_COMPUTE_BIT, or QUEUE_GRAPHICS_BIT operations

• This command must not be called between suspended render pass instances

• This command must only be called outside of a video coding scope

• Both of commandBuffer, and gpaSession must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Conditional Rendering

vkCmdBeginGpaSampleAMD is not affected by conditional rendering

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_AMD_gpa_interface, CommandBuffer, GpaSampleBeginInfoAMD, GpaSessionAMD

vkCmdEndGpaSampleAMD - Ending a sample

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• gpaSession must be a valid GpaSessionAMD handle

• commandBuffer must be in the recording state

• The CommandPool that commandBuffer was allocated from must support QUEUE_COMPUTE_BIT, or QUEUE_GRAPHICS_BIT operations

• This command must not be called between suspended render pass instances

• This command must only be called outside of a video coding scope

• Both of commandBuffer, and gpaSession must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Conditional Rendering

vkCmdEndGpaSampleAMD is not affected by conditional rendering

See Also

VK_AMD_gpa_interface, CommandBuffer, GpaSessionAMD

vkGetGpaSessionStatusAMD - Getting the status of a GPA session

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_AMD_gpa_interface, Device, GpaSessionAMD

vkGetGpaSessionResultsAMD - Getting the status of a GPA session

Valid Usage (Implicit)

• device must be a valid Device handle

• gpaSession must be a valid GpaSessionAMD handle

• pSizeInBytes must be a valid pointer to a size_t value

• If pData is not NULL, pData must be a valid pointer to an array of pSizeInBytes bytes

• If pData is not NULL, the value referenced by pSizeInBytes must be greater than 0

• gpaSession must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_AMD_gpa_interface, Device, GpaSessionAMD

vkResetGpaSessionAMD - Reset a GPA session

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_AMD_gpa_interface, Device, GpaSessionAMD

vkCmdCopyGpaSessionResultsAMD - Copying GPA session results

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• gpaSession must be a valid GpaSessionAMD handle

• commandBuffer must be in the recording state

• The CommandPool that commandBuffer was allocated from must support QUEUE_COMPUTE_BIT, QUEUE_GRAPHICS_BIT, or QUEUE_TRANSFER_BIT operations

• This command must not be called between suspended render pass instances

• This command must only be called outside of a video coding scope

• Both of commandBuffer, and gpaSession must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Conditional Rendering

vkCmdCopyGpaSessionResultsAMD is not affected by conditional rendering

See Also

VK_AMD_gpa_interface, CommandBuffer, GpaSessionAMD

VkGpaPerfBlockPropertiesAMD - Structure describing GPU performance API block properties for a physical device

Members

The members of the GpaPerfBlockPropertiesAMD structure describe the following:

Description

If the GpaPerfBlockPropertiesAMD structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Valid Usage (Implicit)

See Also

VK_AMD_gpa_interface, GpaPerfBlockAMD, GpaPerfBlockPropertiesFlagsAMD, PhysicalDeviceGpaPropertiesAMD

VkPhysicalDeviceGpaFeaturesAMD - Structure describing support for GPU performance API

Description

If the PhysicalDeviceGpaFeaturesAMD structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. If the application wishes to use a Device with any features described by PhysicalDeviceGpaFeaturesAMD, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Structure Chaining

Extends the structures

• DeviceCreateInfo

• PhysicalDeviceFeatures2

See Also

VK_AMD_gpa_interface, Bool32, StructureType

VkPhysicalDeviceGpaPropertiesAMD - Structure describing GPU performance API properties for a physical device

Members

The members of the PhysicalDeviceGpaPropertiesAMD structure describe the following:

Description

If the PhysicalDeviceGpaPropertiesAMD structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Structure Chaining

Extends the structure

• PhysicalDeviceProperties2

See Also

VK_AMD_gpa_interface, DeviceSize, GpaPerfBlockPropertiesAMD, PhysicalDeviceGpaPropertiesFlagsAMD, StructureType

VkPhysicalDeviceGpaProperties2AMD - Structure describing additional GPU performance API properties for a physical device

Members

The members of the PhysicalDeviceGpaProperties2AMD structure describe the following:

Description

If the PhysicalDeviceGpaProperties2AMD structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Structure Chaining

Extends the structure

• PhysicalDeviceProperties2

See Also

VK_AMD_gpa_interface, StructureType

VkGpaPerfCounterAMD - Structure specifying parameters of a GPA sample

Valid Usage (Implicit)

See Also

VK_AMD_gpa_interface, GpaPerfBlockAMD, GpaSampleBeginInfoAMD

VkGpaSampleBeginInfoAMD - Structure specifying parameters of a GPA sample

Valid Usage

• If sampleType is GPA_SAMPLE_TYPE_CUMULATIVE_AMD, the ::perfCounters feature must be enabled

• If sampleType is GPA_SAMPLE_TYPE_TRACE_AMD, at least one of the ::streamingPerfCounters or ::sqThreadTracing features must be enabled

• If sqThreadTraceEnable is TRUE, the ::sqThreadTracing feature must be enabled

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_GPA_SAMPLE_BEGIN_INFO_AMD

• pNext must be NULL

• sampleType must be a valid GpaSampleTypeAMD value

• sqShaderMask must be a valid combination of GpaSqShaderStageFlagBitsAMD values

• sqShaderMask must not be 0

• pPerfCounters must be a valid pointer to an array of perfCounterCount valid GpaPerfCounterAMD structures

• timingPreSample must be a valid combination of PipelineStageFlagBits values

• timingPreSample must not be 0

• timingPostSample must be a valid combination of PipelineStageFlagBits values

• timingPostSample must not be 0

• perfCounterCount must be greater than 0

See Also

VK_AMD_gpa_interface, Bool32, DeviceSize, GpaPerfCounterAMD, GpaSampleTypeAMD, GpaSqShaderStageFlagsAMD, PipelineStageFlags, StructureType, cmdBeginGpaSampleAMD

VkGpaDeviceClockModeInfoAMD - Structure containing returned clock ratios or clock mode to set

Description

If clockMode is GPA_DEVICE_CLOCK_MODE_QUERY_AMD, memoryClockRatioToPeak and engineClockRatioToPeak are filled with the ratios of their current values to their maximums respectively, otherwise they are left unchanged.

Valid Usage (Implicit)

See Also

VK_AMD_gpa_interface, GpaDeviceClockModeAMD, StructureType, setGpaDeviceClockModeAMD

VkGpaDeviceGetClockInfoAMD - Structure containing returned clock ratios or clock mode to set

Valid Usage (Implicit)

See Also

VK_AMD_gpa_interface, StructureType, getGpaDeviceClockInfoAMD

VkGpaSessionCreateInfoAMD - Structure specifying parameters of a newly created GPA session

Description

When sampling counters inside secondary command buffers, repeated invocations of the same secondary command buffer causes the previous results to be overwritten. To avoid this a GPA session object’s memory layout can be cloned for use with multiple secondary invocations by specifying its handle in secondaryCopySource, allowing the new GPA session object to be the target of a copy using cmdCopyGpaSessionResultsAMD.

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_GPA_SESSION_CREATE_INFO_AMD

• pNext must be NULL

• If secondaryCopySource is not NULL_HANDLE, secondaryCopySource must be a valid GpaSessionAMD handle

See Also

VK_AMD_gpa_interface, GpaSessionAMD, StructureType, createGpaSessionAMD

VkGpaPerfBlockPropertiesFlagsAMD - Reserved for future use

Description

GpaPerfBlockPropertiesFlagsAMD is a bitmask type for setting GPA performance block property flags, but is currently reserved for future use.

See Also

VK_AMD_gpa_interface, Flags, GpaPerfBlockPropertiesAMD

VkPhysicalDeviceGpaPropertiesFlagsAMD - Reserved for future use

Description

PhysicalDeviceGpaPropertiesFlagsAMD is a bitmask type for setting physical device GPA property flags, but is currently reserved for future use.

See Also

VK_AMD_gpa_interface, Flags, PhysicalDeviceGpaPropertiesAMD

VkGpaSqShaderStageFlagBitsAMD - Bitmask specifying GPU shader stage to sample

Description

• GPA_SQ_SHADER_STAGE_PS_BIT_AMD specifies the pixel shader stage.

• GPA_SQ_SHADER_STAGE_VS_BIT_AMD specifies the vertex shader stage.

• GPA_SQ_SHADER_STAGE_GS_BIT_AMD specifies the geometry shader stage.

• GPA_SQ_SHADER_STAGE_ES_BIT_AMD specifies the export shader stage.

• GPA_SQ_SHADER_STAGE_HS_BIT_AMD specifies the hull shader stage.

• GPA_SQ_SHADER_STAGE_LS_BIT_AMD specifies the local shader stage.

• GPA_SQ_SHADER_STAGE_CS_BIT_AMD specifies the compute shader stage.

See Also

VK_AMD_gpa_interface, GpaSqShaderStageFlagsAMD

VkGpaPerfBlockAMD - Enum providing performance counter types

See Also

VK_AMD_gpa_interface, GpaPerfBlockPropertiesAMD, GpaPerfCounterAMD

VkGpaSampleTypeAMD - Enum providing the sample type

Description

• GPA_SAMPLE_TYPE_CUMULATIVE_AMD specifies that one 64-bit result will be returned per global performance counter, representing the cumulative delta for that counter over the sample period. Cumulative samples must begin and end in the same command buffer.

• GPA_SAMPLE_TYPE_TRACE_AMD specifies that a buffer will be filled with SQTT results data in RGP file format, and/or streaming performance monitor data. Trace samples may span multiple command buffers.

• GPA_SAMPLE_TYPE_TIMING_AMD specifies that two 64-bit results will be recorded to gather timestamp data.

See Also

VK_AMD_gpa_interface, GpaSampleBeginInfoAMD

VkGpaDeviceClockModeAMD - Enum providing the clock mode or query

Description

• GPA_DEVICE_CLOCK_MODE_DEFAULT_AMD specifies that device clocks and other power settings are restored to their default values.

• GPA_DEVICE_CLOCK_MODE_QUERY_AMD specifies that the current clock values should be queried, with no new values set.

• GPA_DEVICE_CLOCK_MODE_PROFILING_AMD specifies that clocks are set to a constant amount which is known to be power and thermal sustainable. The engine/memory clock ratio will be kept the same as much as possible.

• GPA_DEVICE_CLOCK_MODE_MIN_MEMORY_AMD specifies that the memory clock is set to the lowest available level and the engine clock is set to a thermal and power sustainable level.

• GPA_DEVICE_CLOCK_MODE_MIN_ENGINE_AMD specifies that the engine clock is set to the lowest available level and the memory clock is set to a thermal and power sustainable level.

• GPA_DEVICE_CLOCK_MODE_PEAK_AMD specifies that the clocks set to maximum when possible and fans set to maximum. Under power and thermal constraints device will clock down.

See Also

VK_AMD_gpa_interface, GpaDeviceClockModeInfoAMD

VkGpaSessionAMD - Opaque handle to a GPU Performance API object

See Also

VK_AMD_gpa_interface, VK_DEFINE_NON_DISPATCHABLE_HANDLE, GpaSessionCreateInfoAMD, cmdBeginGpaSampleAMD, cmdBeginGpaSessionAMD, cmdCopyGpaSessionResultsAMD, cmdEndGpaSampleAMD, cmdEndGpaSessionAMD, createGpaSessionAMD, destroyGpaSessionAMD, getGpaSessionResultsAMD, getGpaSessionStatusAMD, resetGpaSessionAMD