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

Agents

Agents#

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

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

Agent state.

Enumerator
AMD_DBGAPI_AGENT_STATE_SUPPORTED 

Agent supports debugging.

AMD_DBGAPI_AGENT_STATE_NOT_SUPPORTED 

Agent does not support debugging.

Reasons include:

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_idThe handle of the agent 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_AGENT_IDagent_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_COMPATIBILITYvalue_size does not match the size of the query result. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLEThe 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_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_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_idIf 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_countThe number of agents accessed by the process.
[out]agentsIf 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]changedIf 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_SUCCESSThe function has been executed successfully and the result is stored in changed, agent_count, and agents.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and agent_count, agents, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and agent_count, agents, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. agent_count, agents, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTagent_count or agents are NULL, or changed is invalid. agent_count, agents, 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 agents returns NULL. agent_count, agents, and changed are unaltered.