Dispatches

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.