Queues

Queues#

AMD DBG API: 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_HANDLE_LITERAL (amd_dbgapi_queue_id_t, 0)
	The NULL queue handle. More...

Enumerations
enum	amd_dbgapi_queue_info_t { AMD_DBGAPI_QUEUE_INFO_AGENT = 1 , AMD_DBGAPI_QUEUE_INFO_PROCESS = 2 , AMD_DBGAPI_QUEUE_INFO_ARCHITECTURE = 3 , AMD_DBGAPI_QUEUE_INFO_TYPE = 4 , AMD_DBGAPI_QUEUE_INFO_STATE = 5 , AMD_DBGAPI_QUEUE_INFO_ERROR_REASON = 6 , AMD_DBGAPI_QUEUE_INFO_ADDRESS = 7 , AMD_DBGAPI_QUEUE_INFO_SIZE = 8 , AMD_DBGAPI_QUEUE_INFO_OS_ID = 9 }
	Queue queries that are supported by amd_dbgapi_queue_get_info. 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_exceptions_t { AMD_DBGAPI_EXCEPTION_NONE = 0ULL , AMD_DBGAPI_EXCEPTION_WAVE_ABORT = (1ULL << 0) , AMD_DBGAPI_EXCEPTION_WAVE_TRAP = (1ULL << 1) , AMD_DBGAPI_EXCEPTION_WAVE_MATH_ERROR = (1ULL << 2) , AMD_DBGAPI_EXCEPTION_WAVE_ILLEGAL_INSTRUCTION = (1ULL << 3) , AMD_DBGAPI_EXCEPTION_WAVE_MEMORY_VIOLATION = (1ULL << 4) , AMD_DBGAPI_EXCEPTION_WAVE_APERTURE_VIOLATION = (1ULL << 5) , AMD_DBGAPI_EXCEPTION_PACKET_DISPATCH_DIM_INVALID = (1ULL << 16) , AMD_DBGAPI_EXCEPTION_PACKET_DISPATCH_GROUP_SEGMENT_SIZE_INVALID = (1ULL << 17) , AMD_DBGAPI_EXCEPTION_PACKET_DISPATCH_CODE_INVALID = (1ULL << 18) , AMD_DBGAPI_EXCEPTION_PACKET_UNSUPPORTED = (1ULL << 20) , AMD_DBGAPI_EXCEPTION_PACKET_DISPATCH_WORK_GROUP_SIZE_INVALID = (1ULL << 21) , AMD_DBGAPI_EXCEPTION_PACKET_DISPATCH_REGISTER_COUNT_TOO_LARGE = (1ULL << 22) , AMD_DBGAPI_EXCEPTION_PACKET_VENDOR_UNSUPPORTED = (1ULL << 23) , AMD_DBGAPI_EXCEPTION_QUEUE_PREEMPTION_ERROR = (1ULL << 31) }
	A bit mask of the exceptions that can cause a queue to enter the queue error state. More...

Functions
amd_dbgapi_status_t AMD_DBGAPI	amd_dbgapi_queue_get_info (amd_dbgapi_queue_id_t queue_id, amd_dbgapi_queue_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_58
	Query information about a queue. More...

amd_dbgapi_status_t AMD_DBGAPI	amd_dbgapi_process_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_54
	Return the list of queues. More...

amd_dbgapi_status_t AMD_DBGAPI	amd_dbgapi_queue_packet_list (amd_dbgapi_queue_id_t queue_id, amd_dbgapi_os_queue_packet_id_t read_packet_id, amd_dbgapi_os_queue_packet_id_t write_packet_id, size_t packets_byte_size, void *packets_bytes) AMD_DBGAPI_VERSION_0_54
	Return the packets for a queue. 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_HANDLE_LITERAL (amd_dbgapi_queue_id_t, 0)

The NULL queue handle.

Enumeration Type Documentation

◆ amd_dbgapi_exceptions_t

enum amd_dbgapi_exceptions_t

A bit mask of the exceptions that can cause a queue to enter the queue error state.

Enumerator
AMD_DBGAPI_EXCEPTION_NONE	If none of the bits are set, then the queue is not in the error state.
AMD_DBGAPI_EXCEPTION_WAVE_ABORT	A wave on the queue executed a trap instruction used to abort a dispatch.
AMD_DBGAPI_EXCEPTION_WAVE_TRAP	A wave on the queue executed an instruction that caused an exception. This includes executing a trap instruction (other than the trap reported as AMD_DBGAPI_EXCEPTION_WAVE_ABORT), executing an instruction that causes a fatal halt, executing an instruction that causes an ECC error, or executing an instruction that triggers a watchpoint (normally watchpoints are handled by the library and are never passed to the inferior's runtime to cause this exception).
AMD_DBGAPI_EXCEPTION_WAVE_MATH_ERROR	A wave on the queue executed an instruction that had a floating point or integer enabled exception condition. The conditions include: Floating point operation is invalid. Floating point operation had subnormal input that was rounded to zero. Floating point operation performed a division by zero. Floating point operation produced an overflow result. The result was rounded to infinity. Floating point operation produced an underflow result. A subnormal result was rounded to zero. Floating point operation produced an inexact result. Integer operation performed a division by zero.
AMD_DBGAPI_EXCEPTION_WAVE_ILLEGAL_INSTRUCTION	A wave on the queue executed an illegal instruction.
AMD_DBGAPI_EXCEPTION_WAVE_MEMORY_VIOLATION	A wave on the queue had a memory violation. This happens when accessing a non-existent memory page or a page without the necessary permission (such as writing to a readonly page or executing a non-execute page).
AMD_DBGAPI_EXCEPTION_WAVE_APERTURE_VIOLATION	A wave on the queue had an aperture violation. This happens when accessing a memory address outside the virtual memory address range.
AMD_DBGAPI_EXCEPTION_PACKET_DISPATCH_DIM_INVALID	A dispatch packet on the queue has an invalid dimension.
AMD_DBGAPI_EXCEPTION_PACKET_DISPATCH_GROUP_SEGMENT_SIZE_INVALID	A dispatch packet on the queue has an invalid group segment size.
AMD_DBGAPI_EXCEPTION_PACKET_DISPATCH_CODE_INVALID	A dispatch packet on the queue has a NULL code address.
AMD_DBGAPI_EXCEPTION_PACKET_UNSUPPORTED	A packet on the queue has an unsupported code.
AMD_DBGAPI_EXCEPTION_PACKET_DISPATCH_WORK_GROUP_SIZE_INVALID	A dispatch packet on the queue has an invalid work-group size.
AMD_DBGAPI_EXCEPTION_PACKET_DISPATCH_REGISTER_COUNT_TOO_LARGE	A dispatch packet on the queue requires too many registers.
AMD_DBGAPI_EXCEPTION_PACKET_VENDOR_UNSUPPORTED	A packet on the queue has an invalid vendor code.
AMD_DBGAPI_EXCEPTION_QUEUE_PREEMPTION_ERROR	There was an error preempting the queue. When the AMD GPU device driver generates this error it may cause all waves associated with the queue to be killed. Killing a wave causes it to be terminated immediately without reporting any exceptions. Any killed waves that have a pending single step will report a AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED event to indicate that the single step has been cancelled.

◆ amd_dbgapi_queue_info_t

enum 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_PROCESS	Return the process to which this queue belongs. The type of this attribute is amd_dbgapi_process_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_INFO_TYPE	Return the queue type. The type of this attribute is `uint32_t` with values from amd_dbgapi_os_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 set of exceptions that caused the queue to enter the queue error state. If the queue is not in the queue error state then AMD_DBGAPI_EXCEPTION_NONE is returned. The type of this attribute is `uint32_t` with values defined by amd_dbgapi_exceptions_t.
AMD_DBGAPI_QUEUE_INFO_ADDRESS	Return the base address of the memory holding the queue packets. The type of this attribute is amd_dbgapi_global_address_t.
AMD_DBGAPI_QUEUE_INFO_SIZE	Return the size in bytes of the memory holding the queue packets. The type of this attribute is amd_dbgapi_size_t.
AMD_DBGAPI_QUEUE_INFO_OS_ID	Native operating system queue ID. The type of this attribute is amd_dbgapi_os_queue_id_t.

◆ amd_dbgapi_queue_state_t

enum 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 the queue error state.

No further waves will be started on the queue. All waves that belong to the queue are inhibited from executing further instructions regardless of whether they are in the halt state.

When the inferior's runtime puts a queue into the queue error state, a AMD_DBGAPI_EVENT_KIND_QUEUE_ERROR event will be reported. In addition, any waves that belong to the queue that have pending single step requests will cause a AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED event to be generated to indicate the single step has been cancelled.

Function Documentation

◆ amd_dbgapi_process_queue_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_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.

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

The queues of the process that are associated with agents that do not support debugging are not reported. See AMD_DBGAPI_AGENT_STATE_NOT_SUPPORTED.

Parameters

[in]	process_id	If AMD_DBGAPI_PROCESS_NONE then the queue list for all processes is requested. Otherwise, the queue list of process `process_id` is requested.
[out]	queue_count	The number of queues accessed by the process.
[out]	queues	If `changed` is not NULL and the queues list of all of the processes requested have not changed since the last call(s) to amd_dbgapi_process_queue_list for each of them, 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]	changed	If NULL then left unaltered. If non-NULL, set to AMD_DBGAPI_CHANGED_NO if the list of queues for each requested process is the same as when amd_dbgapi_process_queue_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`, `queue_count`, and `queues`.
AMD_DBGAPI_STATUS_FATAL	A fatal error occurred. The library is left uninitialized; and `queue_count`, `queues`, and `changed` are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED	The library is not initialized. The library is left uninitialized; and `queue_count`, `queues`, and `changed` are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID	`process_id` is invalid. `queue_count`, `queues`, and `changed` are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT	`queue_count` or `queues` are NULL, or `changed` is invalid. `queue_count`, `queues`, 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 `queues` returns NULL. `queue_count`, `queues`, and `changed` are unaltered.

◆ amd_dbgapi_queue_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_queue_get_info	(	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]	queue_id	The handle of the queue being queried.
[in]	query	The query being requested.
[out]	value	Pointer to memory where the query result is stored.
[in]	value_size	Size of the memory pointed to by `value`. Must be equal to the byte size of the query result.

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_QUEUE_ID	`queue_id` is invalid. `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_queue_packet_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_queue_packet_list	(	amd_dbgapi_queue_id_t	queue_id,
		amd_dbgapi_os_queue_packet_id_t *	read_packet_id,
		amd_dbgapi_os_queue_packet_id_t *	write_packet_id,
		size_t *	packets_byte_size,
		void **	packets_bytes
	)

Return the packets for a queue.

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_INFO_TYPE query. See amd_dbgapi_os_queue_type_t.

Parameters

[in]	queue_id	The queue for which the packet list is requested.
[out]	read_packet_id	The packet ID for the next packet to be read from the queue. It corresponds to 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]	write_packet_id	The packet ID for the next packet to be written to the queue. It corresponds to the next packet after the last 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_size	The number of bytes of packets on the queue.
[out]	packets_bytes	If non-NULL, it references a pointer to an array of `packets_byte_size` bytes which is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client. If NULL, the packet bytes are not returned, just `packets_byte_size`.

Return values

AMD_DBGAPI_STATUS_SUCCESS	The function has been executed successfully and the result is stored in `read_packet_id`, `write_packet_id`, `packets_byte_size` and `packets_bytes`.
AMD_DBGAPI_STATUS_FATAL	A fatal error occurred. The library is left uninitialized; and `read_packet_id`, `write_packet_id`, `packets_byte_size` and `packets_bytes` are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED	The library is not initialized. The library is left uninitialized; and `read_packet_id`, `write_packet_id`, `packets_byte_size` and `packets_bytes` are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT	`read_packet_id`, `write_packet_id`, or `packets_byte_size` are NULL. `read_packet_id`, `write_packet_id`, `packets_byte_size` and `packets_bytes` are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_SUPPORTED	`queue_id` has a queue type that is not supported. `read_packet_id`, `write_packet_id`, `packets_byte_size` and `packets_bytes` are unaltered.
AMD_DBGAPI_STATUS_ERROR	An error was encountered when attempting to access the queue `queue_id`. For example, the queue may be corrupted. `read_packet_id`, `write_packet_id`, `packets_byte_size` and `packets_bytes` are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK	This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate `packets_bytes` returns NULL. `read_packet_id`, `write_packet_id`, `packets_byte_size` and `packets_bytes` are unaltered.

Queues

Queues#

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AMD_DBGAPI_QUEUE_NONE

Enumeration Type Documentation

◆ amd_dbgapi_exceptions_t

◆ amd_dbgapi_queue_info_t

◆ amd_dbgapi_queue_state_t

Function Documentation

◆ amd_dbgapi_process_queue_list()

◆ amd_dbgapi_queue_get_info()

◆ amd_dbgapi_queue_packet_list()