AMD_DBGAPI: Agents

AMD_DBGAPI 0.62.1

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_SLOT = 5, AMD_DBGAPI_AGENT_INFO_PCI_VENDOR_ID = 6, AMD_DBGAPI_AGENT_INFO_PCI_DEVICE_ID = 7, AMD_DBGAPI_AGENT_INFO_EXECUTION_UNIT_COUNT = 8, AMD_DBGAPI_AGENT_INFO_MAX_WAVES_PER_EXECUTION_UNIT = 9, AMD_DBGAPI_AGENT_INFO_OS_ID = 10 }
| 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_56
| 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_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_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.