AMD_DBGAPI  0.31.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_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_report_shared_library (amd_dbgapi_process_id_t process_id, amd_dbgapi_shared_library_id_t shared_library_id, amd_dbgapi_shared_library_state_t shared_library_state) AMD_DBGAPI_VERSION_0_24
 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_report_breakpoint_hit (amd_dbgapi_process_id_t process_id, 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_24
 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_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_report_breakpoint_hit()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_report_breakpoint_hit ( amd_dbgapi_process_id_t  process_id,
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]process_idThe process to which the client_thread_id hitting the breakpoint belongs.
[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_PROCESS_IDThe process_id is invalid. 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_process_id_t  process_id,
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]process_idThe process to which the shared_library_id belongs.
[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_PROCESS_IDThe process_id is invalid.
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.