AMD_DBGAPI  0.48.0
Data Structures | Macros | Typedefs | Enumerations | Functions
Callbacks

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. More...

Data Structures

struct  amd_dbgapi_shared_library_id_t
 Opaque shared library handle. More...
 
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_SHARED_LIBRARY_NONE   ((amd_dbgapi_shared_library_id_t){ 0 })
 The NULL shared library handle. More...
 
#define AMD_DBGAPI_BREAKPOINT_NONE   ((amd_dbgapi_breakpoint_id_t){ 0 })
 The NULL breakpoint handle. More...
 

Typedefs

typedef struct amd_dbgapi_callbacks_s amd_dbgapi_callbacks_t
 
typedef struct amd_dbgapi_client_thread_s * amd_dbgapi_client_thread_id_t
 Opaque client thread handle. More...
 

Enumerations

enum  amd_dbgapi_shared_library_state_t { AMD_DBGAPI_SHARED_LIBRARY_STATE_LOADED = 1, AMD_DBGAPI_SHARED_LIBRARY_STATE_UNLOADED = 2 }
 The state of a shared library. More...
 
enum  amd_dbgapi_shared_library_info_t { AMD_DBGAPI_SHARED_LIBRARY_INFO_PROCESS = 1 }
 Shared library queries that are supported by amd_dbgapi_shared_library_get_info. More...
 
enum  amd_dbgapi_breakpoint_info_t { AMD_DBGAPI_BREAKPOINT_INFO_SHARED_LIBRARY = 1, AMD_DBGAPI_BREAKPOINT_INFO_PROCESS = 2 }
 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...
 

Functions

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_shared_library_get_info (amd_dbgapi_shared_library_id_t shared_library_id, amd_dbgapi_shared_library_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_41
 Query information about a shared library. More...
 
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_report_shared_library (amd_dbgapi_shared_library_id_t shared_library_id, amd_dbgapi_shared_library_state_t shared_library_state) AMD_DBGAPI_VERSION_0_41
 Report that a shared library enabled by the amd_dbgapi_callbacks_s::enable_notify_shared_library callback has been loaded or unloaded. More...
 
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_41
 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_41
 Report that a breakpoint inserted by the amd_dbgapi_callbacks_s::insert_breakpoint calback 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_breakpoint_id_t){ 0 })

The NULL breakpoint handle.

◆ AMD_DBGAPI_SHARED_LIBRARY_NONE

#define AMD_DBGAPI_SHARED_LIBRARY_NONE   ((amd_dbgapi_shared_library_id_t){ 0 })

The NULL shared library 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_SHARED_LIBRARY 

Return the shared library to which this breakpoint belongs.

The type of this attribute is amd_dbgapi_shared_library_id_t.

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_shared_library_info_t

Shared library queries that are supported by amd_dbgapi_shared_library_get_info.

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

Enumerator
AMD_DBGAPI_SHARED_LIBRARY_INFO_PROCESS 

Return the process to which this shared library belongs.

The type of this attribute is amd_dbgapi_process_id_t.

◆ amd_dbgapi_shared_library_state_t

The state of a shared library.

Enumerator
AMD_DBGAPI_SHARED_LIBRARY_STATE_LOADED 

The shared library is loaded.

AMD_DBGAPI_SHARED_LIBRARY_STATE_UNLOADED 

The shared library is unloaded.

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 calback 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.

◆ amd_dbgapi_report_shared_library()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_report_shared_library ( amd_dbgapi_shared_library_id_t  shared_library_id,
amd_dbgapi_shared_library_state_t  shared_library_state 
)

Report that a shared library enabled by the amd_dbgapi_callbacks_s::enable_notify_shared_library callback has been loaded or unloaded.

The thread that is performing the shared library load or unload must remain halted while this function executes. This allows the library to use the amd_dbgapi_callbacks_s::get_symbol_address, amd_dbgapi_callbacks_s::insert_breakpoint and amd_dbgapi_callbacks_s::remove_breakpoint callbacks to add or remove breakpoints on library load or unload respectively. The breakpoints must be inserted before any code can execute in the shared library.

Parameters
[in]shared_library_idThe shared library that has been loaded or unloaded.
[in]shared_library_stateThe shared library state.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The amd-dbgapi library is left uninitialized and resume is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe amd-dbgapi library is not initialized. The amd-dbgapi library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_INVALID_SHARED_LIBRARY_IDThe shared_library_id is invalid.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTshared_library_state is invalid.
AMD_DBGAPI_STATUS_ERRORshared_library_state is not consistent with the previously reported load state. For example, it is reported as loaded when previously also reported as loaded.

◆ amd_dbgapi_shared_library_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_shared_library_get_info ( amd_dbgapi_shared_library_id_t  shared_library_id,
amd_dbgapi_shared_library_info_t  query,
size_t  value_size,
void *  value 
)

Query information about a shared library.

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

Parameters
[in]shared_library_idThe handle of the shared_library 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_SHARED_LIBRARY_IDshared_library_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.