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

Callbacks

Callbacks#

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

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

The action to perform after reporting a breakpoint has been hit.

Enumerator
AMD_DBGAPI_BREAKPOINT_ACTION_RESUME 

Resume execution.

AMD_DBGAPI_BREAKPOINT_ACTION_HALT 

Leave execution halted.

◆ 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 pid_t from sys/types.h and the corresponding process is required to have already been ptrace enabled.

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_idThe handle of the breakpoint 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_BREAKPOINT_IDbreakpoint_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_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_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_idThe breakpoint that has been hit.
[in]client_thread_idThe client identification of the thread that hit the breakpoint.
[out]breakpoint_actionIndicate if the thread hitting the breakpoint should be resumed or remain halted when this function returns.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and breakpoint_action indicates if the thread hitting the breakpoint should be resumed.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and breakpoint_action is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and breakpoint_action is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_BREAKPOINT_IDThe breakpoint_id is invalid. breakpoint_action is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTbreakpoint_action is NULL. breakpoint_action is unaltered.