AMD_DBGAPI  0.30.0
Data Structures | Macros | Typedefs | Enumerations | Functions
Queues

Operations related to AMD GPU queues. More...

Data Structures

struct  amd_dbgapi_queue_id_t
 Opaque queue handle. More...
 

Macros

#define AMD_DBGAPI_QUEUE_NONE   (amd_dbgapi_queue_id_t{ 0 })
 The NULL queue handle. More...
 

Typedefs

typedef uint64_t amd_dbgapi_queue_packet_id_t
 Queue packet ID. More...
 

Enumerations

enum  amd_dbgapi_queue_info_t {
  AMD_DBGAPI_QUEUE_INFO_AGENT = 1, AMD_DBGAPI_QUEUE_INFO_ARCHITECTURE = 2, AMD_DBGAPI_QUEUE_TYPE = 3, AMD_DBGAPI_QUEUE_INFO_STATE = 4,
  AMD_DBGAPI_QUEUE_INFO_ERROR_REASON = 5
}
 Queue queries that are supported by amd_dbgapi_queue_get_info. More...
 
enum  amd_dbgapi_queue_type_t {
  AMD_DBGAPI_QUEUE_TYPE_UNKNOWN = 0, AMD_DBGAPI_QUEUE_TYPE_HSA_KERNEL_DISPATCH_MULTIPLE_PRODUCER = 1, AMD_DBGAPI_QUEUE_TYPE_HSA_KERNEL_DISPATCH_SINGLE_PRODUCER = 2, AMD_DBGAPI_QUEUE_TYPE_HSA_KERNEL_DISPATCH_COOPERATIVE = 3,
  AMD_DBGAPI_QUEUE_TYPE_AMD_PM4 = 257, AMD_DBGAPI_QUEUE_TYPE_AMD_SDMA = 513, AMD_DBGAPI_QUEUE_TYPE_AMD_SDMA_XGMI = 514
}
 Queue type. More...
 
enum  amd_dbgapi_queue_state_t { AMD_DBGAPI_QUEUE_STATE_VALID = 1, AMD_DBGAPI_QUEUE_STATE_ERROR = 2 }
 Queue state. More...
 
enum  amd_dbgapi_queue_error_reason_t {
  AMD_DBGAPI_QUEUE_ERROR_REASON_NONE = 0ULL, AMD_DBGAPI_QUEUE_ERROR_REASON_INVALID_PACKET = (1ULL << 0), AMD_DBGAPI_QUEUE_ERROR_REASON_MEMORY_VIOLATION = (1ULL << 1), AMD_DBGAPI_QUEUE_ERROR_REASON_ASSERT_TRAP = (1ULL << 2),
  AMD_DBGAPI_QUEUE_ERROR_REASON_WAVE_ERROR = (1ULL << 3), AMD_DBGAPI_QUEUE_ERROR_REASON_RESERVED = (1ULL << 63)
}
 A bit mask of the reasons that a queue is in error. More...
 

Functions

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_queue_get_info (amd_dbgapi_process_id_t process_id, amd_dbgapi_queue_id_t queue_id, amd_dbgapi_queue_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_24
 Query information about a queue. More...
 
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_queue_list (amd_dbgapi_process_id_t process_id, size_t *queue_count, amd_dbgapi_queue_id_t **queues, amd_dbgapi_changed_t *changed) AMD_DBGAPI_VERSION_0_24
 Return the list of queues for a process. More...
 
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_queue_packet_list (amd_dbgapi_process_id_t process_id, amd_dbgapi_queue_id_t queue_id, amd_dbgapi_queue_packet_id_t *first_packet_id, amd_dbgapi_size_t *packets_byte_size, void **packets_bytes) AMD_DBGAPI_VERSION_0_24
 Return the packets for a queue of a process. More...
 

Detailed Description

Operations related to AMD GPU queues.

Queues are user mode data structures that allow packets to be inserted that control the AMD GPU agents. The dispatch packet is used to initiate the execution of a grid of waves.

Macro Definition Documentation

◆ AMD_DBGAPI_QUEUE_NONE

#define AMD_DBGAPI_QUEUE_NONE   (amd_dbgapi_queue_id_t{ 0 })

The NULL queue handle.

Typedef Documentation

◆ amd_dbgapi_queue_packet_id_t

typedef uint64_t amd_dbgapi_queue_packet_id_t

Queue packet ID.

The meaning of the packet ID is dependent on the queue type. See amd_dbgapi_queue_type_t.

Enumeration Type Documentation

◆ amd_dbgapi_queue_error_reason_t

A bit mask of the reasons that a queue is in error.

Enumerator
AMD_DBGAPI_QUEUE_ERROR_REASON_NONE 

If none of the bits are set, then the queue is not in the error state.

AMD_DBGAPI_QUEUE_ERROR_REASON_INVALID_PACKET 

A packet on the queue is invalid.

AMD_DBGAPI_QUEUE_ERROR_REASON_MEMORY_VIOLATION 

A wave on the queue had a memory violation.

AMD_DBGAPI_QUEUE_ERROR_REASON_ASSERT_TRAP 

A wave on the queue had an assert trap.

AMD_DBGAPI_QUEUE_ERROR_REASON_WAVE_ERROR 

A wave on the queue executed an instruction that caused an error.

The AMD_DBGAPI_WAVE_INFO_STOP_REASON query can be used on the waves of the queue to determine the exact reason.

AMD_DBGAPI_QUEUE_ERROR_REASON_RESERVED 

A reserved value only present to ensure that the underlying representation of this enumeration type is uint64_t.

◆ amd_dbgapi_queue_info_t

Queue queries that are supported by amd_dbgapi_queue_get_info.

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

Enumerator
AMD_DBGAPI_QUEUE_INFO_AGENT 

Return the agent to which this queue belongs.

The type of this attribute is amd_dbgapi_agent_id_t.

AMD_DBGAPI_QUEUE_INFO_ARCHITECTURE 

Return the architecture of this queue.

The type of this attribute is amd_dbgapi_architecture_id_t.

AMD_DBGAPI_QUEUE_TYPE 

Return the queue type.

The type of this attribute is uint32_t with values from amd_dbgapi_queue_type_t.

AMD_DBGAPI_QUEUE_INFO_STATE 

Return the queue state.

The type of this attribute is uint32_t with values from amd_dbgapi_queue_state_t.

AMD_DBGAPI_QUEUE_INFO_ERROR_REASON 

Return the reason the queue is in error as a bit set.

If the queue is not in the error state then AMD_DBGAPI_QUEUE_ERROR_REASON_NONE is returned. The type of this attribute is uint64_t with values defined by amd_dbgapi_queue_error_reason_t.

◆ amd_dbgapi_queue_state_t

Queue state.

Enumerator
AMD_DBGAPI_QUEUE_STATE_VALID 

Queue is in a valid state.

AMD_DBGAPI_QUEUE_STATE_ERROR 

Queue is in an error state.

When a queue enters the error state, a wave stop event will be created for all non-stopped waves. All waves of the queue will include the AMD_DBGAPI_WAVE_STOP_REASON_QUEUE_ERROR stop reason.

◆ amd_dbgapi_queue_type_t

Queue type.

Indicates which queue mechanic is supported by the queue.

Enumerator
AMD_DBGAPI_QUEUE_TYPE_UNKNOWN 

Unknown queue type.

AMD_DBGAPI_QUEUE_TYPE_HSA_KERNEL_DISPATCH_MULTIPLE_PRODUCER 

Queue supports the HSA kernel dispatch with multiple producers protocol.

This follows the multiple producers mechanics described by HSA Platform System Architecture Specification: Requirement: User mode queuing and uses the HSA Architected Queuing Language (AQL) packet format described in HSA Platform System Architecture Specification: Requirement: Architected Queuing Language (AQL).

For this queue type the AQL dispatch ID is used for amd_dbgapi_queue_packet_id_t.

AMD_DBGAPI_QUEUE_TYPE_HSA_KERNEL_DISPATCH_SINGLE_PRODUCER 

Queue supports the HSA kernel dispatch with single producer protocol.

This follows the single producer mechanics described by HSA Platform System Architecture Specification: Requirement: User mode queuing and uses the HSA Architected Queuing Language (AQL) packet format described in HSA Platform System Architecture Specification: Requirement: Architected Queuing Language (AQL).

For this queue type the AQL dispatch ID is used for amd_dbgapi_queue_packet_id_t. It is only unique within a single queue of a single process.

AMD_DBGAPI_QUEUE_TYPE_HSA_KERNEL_DISPATCH_COOPERATIVE 

Queue supports HSA kernel dispatch with multiple producers protocol that supports cooperative dispatches.

Queues of this type follow the same protocol as AMD_DBGAPI_QUEUE_TYPE_HSA_KERNEL_DISPATCH_MULTIPLE_PRODUCER. In addition, dispatches are able to use global wave synchronization (GWS) operations.

AMD_DBGAPI_QUEUE_TYPE_AMD_PM4 

Queue supports the AMD PM4 protocol.

AMD_DBGAPI_QUEUE_TYPE_AMD_SDMA 

Queue supports the AMD SDMA protocol.

AMD_DBGAPI_QUEUE_TYPE_AMD_SDMA_XGMI 

Queue supports the AMD SDMA XGMI protocol.

Function Documentation

◆ amd_dbgapi_queue_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_queue_get_info ( amd_dbgapi_process_id_t  process_id,
amd_dbgapi_queue_id_t  queue_id,
amd_dbgapi_queue_info_t  query,
size_t  value_size,
void *  value 
)

Query information about a queue.

amd_dbgapi_queue_info_t specifies the queries supported and the type returned using the value argument.

Parameters
[in]process_idThe process to which the queue belongs.
[in]queue_idThe handle of the queue being queried.
[in]queryThe query being requested.
[out]valuePointer to memory where the query result is stored.
[in]value_sizeSize of the memory pointed to by value. Must be equal to the byte size of the query result.
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_PROCESS_IDprocess_id is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_QUEUE_IDqueue_id is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTvalue is NULL or query is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_SIZEvalue_size does not match the size of the 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_queue_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_queue_list ( amd_dbgapi_process_id_t  process_id,
size_t *  queue_count,
amd_dbgapi_queue_id_t **  queues,
amd_dbgapi_changed_t changed 
)

Return the list of queues for a process.

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

Parameters
[in]process_idThe process for which the queue list is requested.
[out]queue_countThe number of queues accessed by the process.
[out]queuesIf changed is not NULL and the queue list has not changed since the last call to amd_dbgapi_queue_list then return NULL. Otherwise, return a pointer to an array of amd_dbgapi_queue_id_t with queue_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 queues is the same as when amd_dbgapi_queue_list was last called, 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, queue_count, and queues.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and queue_count, queues, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and queue_count, queues, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. queue_count, queues, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTqueue_count or queues are NULL, or changed is invalid. queue_count, queues, 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 queues returns NULL. queue_count, queues, and changed are unaltered.

◆ amd_dbgapi_queue_packet_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_queue_packet_list ( amd_dbgapi_process_id_t  process_id,
amd_dbgapi_queue_id_t  queue_id,
amd_dbgapi_queue_packet_id_t first_packet_id,
amd_dbgapi_size_t packets_byte_size,
void **  packets_bytes 
)

Return the packets for a queue of a process.

Since the AMD GPU is asynchronously reading the packets this is only a snapshot of the packets present in the queue, and only includes the packets that the producer has made available to the queue. In obtaining the snapshot the library may pause the queue processing in order to get a consistent snapshot.

The queue packets are returned as a byte block that the client must interpret according to the packet ABI determined by the queue type available using the AMD_DBGAPI_QUEUE_TYPE query. See amd_dbgapi_queue_type_t.

Parameters
[in]process_idThe process of the queue for which the packet list is requested.
[in]queue_idThe queue for which the packet list is requested.
[out]first_packet_idThe packet ID for the first packet in packets_bytes. If packets_byte_size is zero, then the packet ID for the next packet added to the queue.
[out]packets_byte_sizeThe number of bytes of packets on the queue.
[out]packets_bytesA pointer to an array of packets_byte_size bytes. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in packets_byte_size and packets_bytes.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and packets_byte_size and packets_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and packets_byte_size and packets_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. packets_byte_size and packets_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTpackets_byte_size or packets_bytes are NULL. packets_byte_size and packets_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate packets_bytes returns NULL. packets_byte_size and packets_bytes are unaltered.