This page contains changes for a test release of ROCm. Read the latest Linux release of ROCm documentation for your production environments.

Dispatches

Dispatches#

AMD DBG API: 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_WORKGROUP_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

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

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

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_WORKGROUP_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_idThe handle of the dispatch being queried.
[in]queryThe query being requested.
[in]value_sizeSize of the memory pointed to by value. Must be equal to the byte size of the query result.
[out]valuePointer to memory where the query result is stored.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in value.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_DISPATCH_IDqueue_id is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_SUPPORTEDThe requested query is not supported for the specified dispatch_id. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTvalue is NULL or query is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYvalue_size does not match the size of the query result. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis 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_idIf 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_countThe number of dispatches active for a process.
[out]dispatchesIf 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]changedIf 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_SUCCESSThe function has been executed successfully and the result is stored in changed, dispatch_count, and dispatches.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and changed, dispatch_count, and dispatches are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and changed, dispatch_count, and dispatches are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. dispatch_count, dispatches, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTdispatch_count or dispatches are NULL, or changed is invalid. dispatch_count, dispatches, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis 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.