Agents

Data Structures | Macros | Enumerations | Functions

Agents

Operations related to AMD GPU agents accessible to a process. More...

Data Structures
struct	amd_dbgapi_agent_id_t
	Opaque agent handle. More...

Macros
#define	AMD_DBGAPI_AGENT_NONE    AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_agent_id_t, 0)
	The NULL agent handle. More...

Enumerations
enum	amd_dbgapi_agent_info_t {   AMD_DBGAPI_AGENT_INFO_PROCESS = 1 , AMD_DBGAPI_AGENT_INFO_NAME = 2 , AMD_DBGAPI_AGENT_INFO_ARCHITECTURE = 3 , AMD_DBGAPI_AGENT_INFO_STATE = 4 ,   AMD_DBGAPI_AGENT_INFO_PCI_DOMAIN = 5 , AMD_DBGAPI_AGENT_INFO_PCI_SLOT = 6 , AMD_DBGAPI_AGENT_INFO_PCI_VENDOR_ID = 7 , AMD_DBGAPI_AGENT_INFO_PCI_DEVICE_ID = 8 ,   AMD_DBGAPI_AGENT_INFO_EXECUTION_UNIT_COUNT = 9 , AMD_DBGAPI_AGENT_INFO_MAX_WAVES_PER_EXECUTION_UNIT = 10 , AMD_DBGAPI_AGENT_INFO_OS_ID = 11 }
	Agent queries that are supported by amd_dbgapi_agent_get_info. More...
enum	amd_dbgapi_agent_state_t { AMD_DBGAPI_AGENT_STATE_SUPPORTED = 1 , AMD_DBGAPI_AGENT_STATE_NOT_SUPPORTED = 2 }
	Agent state. More...

Functions
amd_dbgapi_status_t AMD_DBGAPI	amd_dbgapi_agent_get_info (amd_dbgapi_agent_id_t agent_id, amd_dbgapi_agent_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_67
	Query information about an agent. More...
amd_dbgapi_status_t AMD_DBGAPI	amd_dbgapi_process_agent_list (amd_dbgapi_process_id_t process_id, size_t *agent_count, amd_dbgapi_agent_id_t **agents, amd_dbgapi_changed_t *changed) AMD_DBGAPI_VERSION_0_54
	Return the list of agents. More...

Detailed Description

Operations related to AMD GPU agents accessible to a process.

Agent is the term for AMD GPU devices that can be accessed by the process.

Macro Definition Documentation

◆ AMD_DBGAPI_AGENT_NONE

#define AMD_DBGAPI_AGENT_NONE    AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_agent_id_t, 0)

The NULL agent handle.

Enumeration Type Documentation

◆ amd_dbgapi_agent_info_t

enum amd_dbgapi_agent_info_t

Agent queries that are supported by amd_dbgapi_agent_get_info.

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

Enumerator
AMD_DBGAPI_AGENT_INFO_PROCESS	Return the process to which this agent belongs. The type of this attribute is amd_dbgapi_process_id_t.
AMD_DBGAPI_AGENT_INFO_NAME	Agent name. The type of this attribute is a pointer to a NUL terminated char*. It is allocated by amd_dbgapi_callbacks_s::allocate_memory and is owned by the client.
AMD_DBGAPI_AGENT_INFO_ARCHITECTURE	Return the architecture of this agent. The type of this attribute is amd_dbgapi_architecture_id_t. If the architecture of the agent is not supported by the library then amd_dbgapi_agent_get_info returns the AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE error. See the Supported AMD GPU Architectures section.
AMD_DBGAPI_AGENT_INFO_STATE	Return the agent state. The type of this attribute is uint32_t with values from amd_dbgapi_agent_state_t.
AMD_DBGAPI_AGENT_INFO_PCI_DOMAIN	PCI domain the agent is in. The type of this attribute is uint16_t.
AMD_DBGAPI_AGENT_INFO_PCI_SLOT	PCI slot of the agent in BDF format (see [Bus:Device.Function (BDF) Notation][bfd]. The type of this attribute is uint16_t.
AMD_DBGAPI_AGENT_INFO_PCI_VENDOR_ID	PCI vendor ID of the agent. The type of this attribute is uint32_t.
AMD_DBGAPI_AGENT_INFO_PCI_DEVICE_ID	PCI device ID of the agent. The type of this attribute is uint32_t.
AMD_DBGAPI_AGENT_INFO_EXECUTION_UNIT_COUNT	Total number of Execution Units (EUs) available in the agent. The type of this attribute is size_t.
AMD_DBGAPI_AGENT_INFO_MAX_WAVES_PER_EXECUTION_UNIT	Maximum number of waves supported by an execution unit. The type of this attribute is size_t.
AMD_DBGAPI_AGENT_INFO_OS_ID	Native operating system agent ID. The type of this attribute is amd_dbgapi_os_agent_id_t.

◆ amd_dbgapi_agent_state_t

enum amd_dbgapi_agent_state_t

Agent state.

Enumerator
AMD_DBGAPI_AGENT_STATE_SUPPORTED	Agent supports debugging.
AMD_DBGAPI_AGENT_STATE_NOT_SUPPORTED	Agent does not support debugging. Reasons include: The architecture of the agent is not supported by the library. See the Supported AMD GPU Architectures section. If there is such an agent then some features may be treated conservatively since the library does not know if the agent really supports the feature. The conservative treatment of such features include: AMD_DBGAPI_PROCESS_INFO_PRECISE_MEMORY_SUPPORTED is conservatively treated as AMD_DBGAPI_MEMORY_PRECISION_NONE. AMD_DBGAPI_PROCESS_INFO_PRECISE_ALU_EXCEPTIONS_SUPPORTED is conservatively treated as AMD_DBGAPI_ALU_EXCEPTIONS_PRECISION_NONE. AMD_DBGAPI_PROCESS_INFO_WATCHPOINT_COUNT is conservatively treated as 0. The firmware version of the agent is not compatible with the library. The AMD GPU driver does not support debugging for the the agent's architecture. No queues, dispatches, or waves will be reported for the agent.

Function Documentation

◆ amd_dbgapi_agent_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_agent_get_info	(	amd_dbgapi_agent_id_t	agent_id,
		amd_dbgapi_agent_info_t	query,
		size_t	value_size,
		void *	value
	)

Query information about an agent.

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

Parameters

[in]	agent_id	The handle of the agent 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_AGENT_ID	agent_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_NOT_AVAILABLE	The requested information is not available. See amd_dbgapi_agent_info_t for queries that can produce this error. 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_agent_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_agent_list	(	amd_dbgapi_process_id_t	process_id,
		size_t *	agent_count,
		amd_dbgapi_agent_id_t **	agents,
		amd_dbgapi_changed_t *	changed
	)

Return the list of agents.

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

All agents of the process are reported, even if they do not support debugging. See AMD_DBGAPI_AGENT_STATE_NOT_SUPPORTED.

Parameters

[in]	process_id	If AMD_DBGAPI_PROCESS_NONE then the agent list for all processes is requested. Otherwise, the agent list of process process_id is requested.
[out]	agent_count	The number of agents accessed by the process.
[out]	agents	If changed is not NULL and the agent list of all of the processes requested have not changed since the last call(s) to amd_dbgapi_process_agent_list for each of them, then return NULL. Otherwise, return a pointer to an array of amd_dbgapi_agent_id_t with agent_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 agents for each requested process is the same as when amd_dbgapi_process_agent_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, agent_count, and agents.
AMD_DBGAPI_STATUS_FATAL	A fatal error occurred. The library is left uninitialized; and agent_count, agents, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED	The library is not initialized. The library is left uninitialized; and agent_count, agents, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID	process_id is invalid. agent_count, agents, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT	agent_count or agents are NULL, or changed is invalid. agent_count, agents, 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 agents returns NULL. agent_count, agents, and changed are unaltered.