Callbacks#
The library requires the client to provide a number of services. More...
Data Structures | |
struct | amd_dbgapi_breakpoint_id_t |
Opaque breakpoint handle. More... | |
struct | amd_dbgapi_callbacks_s |
Callbacks that the client of the library must provide. More... | |
Macros | |
#define | AMD_DBGAPI_BREAKPOINT_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_breakpoint_id_t, 0) |
The NULL breakpoint handle. More... | |
Typedefs | |
typedef struct amd_dbgapi_callbacks_s | amd_dbgapi_callbacks_t |
Forward declaration of callbacks used to specify services that must be provided by the client. More... | |
typedef struct amd_dbgapi_client_thread_s * | amd_dbgapi_client_thread_id_t |
Opaque client thread handle. More... | |
Enumerations | |
enum | amd_dbgapi_breakpoint_info_t { AMD_DBGAPI_BREAKPOINT_INFO_PROCESS = 1 } |
Breakpoint queries that are supported by amd_dbgapi_breakpoint_get_info. More... | |
enum | amd_dbgapi_breakpoint_action_t { AMD_DBGAPI_BREAKPOINT_ACTION_RESUME = 1 , AMD_DBGAPI_BREAKPOINT_ACTION_HALT = 2 } |
The action to perform after reporting a breakpoint has been hit. More... | |
enum | amd_dbgapi_client_process_info_t { AMD_DBGAPI_CLIENT_PROCESS_INFO_OS_PID = 1 , AMD_DBGAPI_CLIENT_PROCESS_INFO_CORE_STATE = 2 } |
Client queries that are supported by the client_process_get_info callback. More... | |
Functions | |
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_breakpoint_get_info (amd_dbgapi_breakpoint_id_t breakpoint_id, amd_dbgapi_breakpoint_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_54 |
Query information about a breakpoint. More... | |
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_report_breakpoint_hit (amd_dbgapi_breakpoint_id_t breakpoint_id, amd_dbgapi_client_thread_id_t client_thread_id, amd_dbgapi_breakpoint_action_t *breakpoint_action) AMD_DBGAPI_VERSION_0_54 |
Report that a breakpoint inserted by the amd_dbgapi_callbacks_s::insert_breakpoint callback has been hit. More... | |
Detailed Description
The library requires the client to provide a number of services.
These services are specified by providing callbacks when initializing the library using amd_dbgapi_initialize.
The callbacks defined in this section are invoked by the library and must not themselves invoke any function provided by the library before returning.
Macro Definition Documentation
◆ AMD_DBGAPI_BREAKPOINT_NONE
#define AMD_DBGAPI_BREAKPOINT_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_breakpoint_id_t, 0) |
The NULL breakpoint handle.
Typedef Documentation
◆ amd_dbgapi_callbacks_t
typedef struct amd_dbgapi_callbacks_s amd_dbgapi_callbacks_t |
Forward declaration of callbacks used to specify services that must be provided by the client.
◆ amd_dbgapi_client_thread_id_t
typedef struct amd_dbgapi_client_thread_s* amd_dbgapi_client_thread_id_t |
Opaque client thread handle.
A pointer to client data associated with a thread. This pointer is passed in to the amd_dbgapi_report_breakpoint_hit so it can be passed out by the AMD_DBGAPI_EVENT_KIND_BREAKPOINT_RESUME event to allow the client of the library to identify the thread that must be resumed.
Enumeration Type Documentation
◆ amd_dbgapi_breakpoint_action_t
◆ amd_dbgapi_breakpoint_info_t
Breakpoint queries that are supported by amd_dbgapi_breakpoint_get_info.
Each query specifies the type of data returned in the value
argument to amd_dbgapi_breakpoint_get_info.
Enumerator | |
---|---|
AMD_DBGAPI_BREAKPOINT_INFO_PROCESS | Return the process to which this breakpoint belongs. The type of this attribute is amd_dbgapi_process_id_t. |
◆ amd_dbgapi_client_process_info_t
Client queries that are supported by the client_process_get_info callback.
Each query specifies the type of data returned in the value
argument to amd_dbgapi_callbacks_s::client_process_get_info.
Enumerator | |
---|---|
AMD_DBGAPI_CLIENT_PROCESS_INFO_OS_PID | Return the native operating system process handle. This value is required to not change during the lifetime of the process associated with the client process handle. For Linux® this is the The type of this attribute is amd_dbgapi_os_process_id_t. |
AMD_DBGAPI_CLIENT_PROCESS_INFO_CORE_STATE | If the current process is created from a core file, return the content of the AMDGPU state note if present. If the process image is not created from a core dump or if such state note is not present in the core dump, the client_process_get_info callback returns AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE. The type of this attribute is amd_dbgapi_core_state_data_t. |
Function Documentation
◆ amd_dbgapi_breakpoint_get_info()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_breakpoint_get_info | ( | amd_dbgapi_breakpoint_id_t | breakpoint_id, |
amd_dbgapi_breakpoint_info_t | query, | ||
size_t | value_size, | ||
void * | value | ||
) |
Query information about a breakpoint.
amd_dbgapi_breakpoint_info_t specifies the queries supported and the type returned using the value
argument.
- Parameters
-
[in] breakpoint_id The handle of the breakpoint 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_BREAKPOINT_ID breakpoint_id
is invalid.value
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT value
is NULL orquery
is invalid.value
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY value_size
does not match the size of thequery
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_report_breakpoint_hit()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_report_breakpoint_hit | ( | amd_dbgapi_breakpoint_id_t | breakpoint_id, |
amd_dbgapi_client_thread_id_t | client_thread_id, | ||
amd_dbgapi_breakpoint_action_t * | breakpoint_action | ||
) |
Report that a breakpoint inserted by the amd_dbgapi_callbacks_s::insert_breakpoint callback has been hit.
The thread that hit the breakpoint must remain halted while this function executes, at which point it must be resumed if breakpoint_action
is AMD_DBGAPI_BREAKPOINT_ACTION_RESUME. If breakpoint_action
is :AMD_DBGAPI_BREAKPOINT_ACTION_HALT then the client should process pending events which will cause a AMD_DBGAPI_EVENT_KIND_BREAKPOINT_RESUME event to be added which specifies that the thread should now be resumed.
- Parameters
-
[in] breakpoint_id The breakpoint that has been hit. [in] client_thread_id The client identification of the thread that hit the breakpoint. [out] breakpoint_action Indicate if the thread hitting the breakpoint should be resumed or remain halted when this function returns.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and breakpoint_action
indicates if the thread hitting the breakpoint should be resumed.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized and breakpoint_action
is unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and breakpoint_action
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_BREAKPOINT_ID The breakpoint_id
is invalid.breakpoint_action
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT breakpoint_action
is NULL.breakpoint_action
is unaltered.