AMD_DBGAPI: Dispatches

AMD_DBGAPI 0.62.1

Data Structures | Macros | Enumerations | Functions
Dispatches

Operations related to AMD GPU dispatches. More...

## Data Structures
struct | amd_dbgapi_dispatch_id_t
| Opaque dispatch handle. More...

## Macros
#define | AMD_DBGAPI_DISPATCH_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_dispatch_id_t, 0)
| The NULL dispatch handle. More...

## Enumerations
enum | amd_dbgapi_dispatch_info_t { AMD_DBGAPI_DISPATCH_INFO_QUEUE = 1, AMD_DBGAPI_DISPATCH_INFO_AGENT = 2, AMD_DBGAPI_DISPATCH_INFO_PROCESS = 3, AMD_DBGAPI_DISPATCH_INFO_ARCHITECTURE = 4, AMD_DBGAPI_DISPATCH_INFO_OS_QUEUE_PACKET_ID = 5, AMD_DBGAPI_DISPATCH_INFO_BARRIER = 6, AMD_DBGAPI_DISPATCH_INFO_ACQUIRE_FENCE = 7, AMD_DBGAPI_DISPATCH_INFO_RELEASE_FENCE = 8, AMD_DBGAPI_DISPATCH_INFO_GRID_DIMENSIONS = 9, AMD_DBGAPI_DISPATCH_INFO_WORK_GROUP_SIZES = 10, AMD_DBGAPI_DISPATCH_INFO_GRID_SIZES = 11, AMD_DBGAPI_DISPATCH_INFO_PRIVATE_SEGMENT_SIZE = 12, AMD_DBGAPI_DISPATCH_INFO_GROUP_SEGMENT_SIZE = 13, AMD_DBGAPI_DISPATCH_INFO_KERNEL_ARGUMENT_SEGMENT_ADDRESS = 14, AMD_DBGAPI_DISPATCH_INFO_KERNEL_DESCRIPTOR_ADDRESS = 15, AMD_DBGAPI_DISPATCH_INFO_KERNEL_CODE_ENTRY_ADDRESS = 16, AMD_DBGAPI_DISPATCH_INFO_KERNEL_COMPLETION_ADDRESS = 17 }
| Dispatch queries that are supported by amd_dbgapi_dispatch_get_info. More...
enum | amd_dbgapi_dispatch_barrier_t { AMD_DBGAPI_DISPATCH_BARRIER_NONE = 0, AMD_DBGAPI_DISPATCH_BARRIER_PRESENT = 1 }
| Dispatch barrier. More...
enum | amd_dbgapi_dispatch_fence_scope_t { AMD_DBGAPI_DISPATCH_FENCE_SCOPE_NONE = 0, AMD_DBGAPI_DISPATCH_FENCE_SCOPE_AGENT = 1, AMD_DBGAPI_DISPATCH_FENCE_SCOPE_SYSTEM = 2 }
| Dispatch memory fence scope. More...

## Functions
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_dispatch_get_info (amd_dbgapi_dispatch_id_t dispatch_id, amd_dbgapi_dispatch_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_54
| Query information about a dispatch. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_process_dispatch_list (amd_dbgapi_process_id_t process_id, size_t *dispatch_count, amd_dbgapi_dispatch_id_t **dispatches, amd_dbgapi_changed_t *changed) AMD_DBGAPI_VERSION_0_54
| Return the list of dispatches. More...

## Detailed Description

Operations related to AMD GPU dispatches.

Dispatches are initiated by queue dispatch packets in the format supported by the queue. See amd_dbgapi_os_queue_type_t. Dispatches are the means that waves are created on the AMD GPU.

## Macro Definition Documentation

## ◆ AMD_DBGAPI_DISPATCH_NONE

#define AMD_DBGAPI_DISPATCH_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_dispatch_id_t, 0)

The NULL dispatch handle.

## Enumeration Type Documentation

## ◆ amd_dbgapi_dispatch_barrier_t

enum amd_dbgapi_dispatch_barrier_t

Dispatch barrier.

Controls when the dispatch will start being executed relative to previous packets on the queue.

Enumerator
AMD_DBGAPI_DISPATCH_BARRIER_NONE | Dispatch has no barrier.
AMD_DBGAPI_DISPATCH_BARRIER_PRESENT | Dispatch has a barrier. The dispatch will not be executed until all proceeding packets on the queue have completed.

## ◆ amd_dbgapi_dispatch_fence_scope_t

enum amd_dbgapi_dispatch_fence_scope_t

Dispatch memory fence scope.

Controls how memory is acquired before a dispatch starts executing and released after the dispatch completes execution.

Enumerator
AMD_DBGAPI_DISPATCH_FENCE_SCOPE_NONE | There is no fence.
AMD_DBGAPI_DISPATCH_FENCE_SCOPE_AGENT | There is a fence with agent memory scope.
AMD_DBGAPI_DISPATCH_FENCE_SCOPE_SYSTEM | There is a fence with system memory scope.

## ◆ amd_dbgapi_dispatch_info_t

enum amd_dbgapi_dispatch_info_t

Dispatch queries that are supported by amd_dbgapi_dispatch_get_info.

Each query specifies the type of data returned in the `value` argument to amd_dbgapi_queue_get_info.

Enumerator
AMD_DBGAPI_DISPATCH_INFO_QUEUE | Return the queue to which this dispatch belongs. The type of this attribute is amd_dbgapi_queue_id_t.
AMD_DBGAPI_DISPATCH_INFO_AGENT | Return the agent to which this dispatch belongs. The type of this attribute is amd_dbgapi_agent_id_t.
AMD_DBGAPI_DISPATCH_INFO_PROCESS | Return the process to which this dispatch belongs. The type of this attribute is amd_dbgapi_process_id_t.
AMD_DBGAPI_DISPATCH_INFO_ARCHITECTURE | Return the architecture of this dispatch. The type of this attribute is amd_dbgapi_architecture_id_t.
AMD_DBGAPI_DISPATCH_INFO_OS_QUEUE_PACKET_ID | Return the queue packet ID of the dispatch packet that initiated the dispatch. The type of this attribute is `amd_dbgapi_os_queue_packet_id_t`.
AMD_DBGAPI_DISPATCH_INFO_BARRIER | Return the dispatch barrier setting. The type of this attribute is `uint32_t` with values defined by amd_dbgapi_dispatch_barrier_t.
AMD_DBGAPI_DISPATCH_INFO_ACQUIRE_FENCE | Return the dispatch acquire fence. The type of this attribute is `uint32_t` with values defined by amd_dbgapi_dispatch_fence_scope_t.
AMD_DBGAPI_DISPATCH_INFO_RELEASE_FENCE | Return the dispatch release fence. The type of this attribute is `uint32_t` with values defined by amd_dbgapi_dispatch_fence_scope_t.
AMD_DBGAPI_DISPATCH_INFO_GRID_DIMENSIONS | Return the dispatch grid dimensionality. The type of this attribute is `uint32` with a value of 1, 2, or 3.
AMD_DBGAPI_DISPATCH_INFO_WORK_GROUP_SIZES | Return the dispatch workgroup size (work-items) in the X, Y, and Z dimensions. The type of this attribute is `uint16_t`[3].
AMD_DBGAPI_DISPATCH_INFO_GRID_SIZES | Return the dispatch grid size (work-items) in the X, Y, and Z dimensions. The type of this attribute is `uint32_t`[3].
AMD_DBGAPI_DISPATCH_INFO_PRIVATE_SEGMENT_SIZE | Return the dispatch private segment size in bytes. The type of this attribute is amd_dbgapi_size_t.
AMD_DBGAPI_DISPATCH_INFO_GROUP_SEGMENT_SIZE | Return the dispatch group segment size in bytes. The type of this attribute is amd_dbgapi_size_t.
AMD_DBGAPI_DISPATCH_INFO_KERNEL_ARGUMENT_SEGMENT_ADDRESS | Return the dispatch kernel argument segment address. The type of this attribute is amd_dbgapi_global_address_t.
AMD_DBGAPI_DISPATCH_INFO_KERNEL_DESCRIPTOR_ADDRESS | Return the dispatch kernel descriptor address. The type of this attribute is amd_dbgapi_global_address_t.
AMD_DBGAPI_DISPATCH_INFO_KERNEL_CODE_ENTRY_ADDRESS | Return the dispatch kernel code entry address. The type of this attribute is amd_dbgapi_global_address_t.
AMD_DBGAPI_DISPATCH_INFO_KERNEL_COMPLETION_ADDRESS | Return the dispatch completion event address. The type of this attribute is amd_dbgapi_global_address_t. The ABI of the completion event varies depending on the queue type available using the AMD_DBGAPI_QUEUE_INFO_TYPE query. See amd_dbgapi_os_queue_type_t. If the queue type does not use completion events, or the dispatch packet does not define a completion event, then amd_dbgapi_dispatch_get_info will return AMD_DBGAPI_STATUS_ERROR_NOT_SUPPORTED.

## Function Documentation

## ◆ amd_dbgapi_dispatch_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_dispatch_get_info | ( | amd_dbgapi_dispatch_id_t | dispatch_id,
|  | amd_dbgapi_dispatch_info_t | query,
|  | size_t | value_size,
|  | void * | value
| ) |  |

Query information about a dispatch.

amd_dbgapi_dispatch_info_t specifies the queries supported and the type returned using the `value` argument.

Parameters

  [in] | dispatch_id | The handle of the dispatch being queried.
  [in] | query | The query being requested.
  [in] | value_size | Size of the memory pointed to by `value`. Must be equal to the byte size of the query result.
  [out] | value | Pointer to memory where the query result is stored.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in `value`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized and `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized and `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_DISPATCH_ID | `queue_id` is invalid. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_SUPPORTED | The requested `query` is not supported for the specified `dispatch_id`. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `value` is NULL or `query` is invalid. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | `value_size` does not match the size of the `query` result. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK | This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate `value` returns NULL. `value` is unaltered.

## ◆ amd_dbgapi_process_dispatch_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_dispatch_list | ( | amd_dbgapi_process_id_t | process_id,
|  | size_t * | dispatch_count,
|  | amd_dbgapi_dispatch_id_t ** | dispatches,
|  | amd_dbgapi_changed_t * | changed
| ) |  |

Return the list of dispatches.

The order of the dispatch handles in the list is unspecified and can vary between calls.

Parameters

  [in] | process_id | If AMD_DBGAPI_PROCESS_NONE then the dispatch list for all processes is requested. Otherwise, the dispatch list of process `process_id` is requested.
  [out] | dispatch_count | The number of dispatches active for a process.
  [out] | dispatches | If `changed` is not NULL and the dispatch list of all of the processes requested have not changed since the last call(s) to amd_dbgapi_process_dispatch_list for each of them, then return NULL. Otherwise, return a pointer to an array of amd_dbgapi_dispatch_id_t with `dispatch_count` elements. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.
  [in,out] | changed | If NULL then left unaltered. If non-NULL, set to AMD_DBGAPI_CHANGED_NO if the list of dispatches for each requested process is the same as when amd_dbgapi_process_dispatch_list was last called for them. Otherwise, set to AMD_DBGAPI_CHANGED_YES.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in `changed`, `dispatch_count`, and `dispatches`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized; and `changed`, `dispatch_count`, and `dispatches` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized; and `changed`, `dispatch_count`, and `dispatches` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | `process_id` is invalid. `dispatch_count`, `dispatches`, and `changed` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `dispatch_count` or `dispatches` are NULL, or `changed` is invalid. `dispatch_count`, `dispatches`, and `changed` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK | This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate `dispatches` returns NULL. `dispatch_count`, `dispatches`, and `changed` are unaltered.