AMD_DBGAPI: Callbacks

AMD_DBGAPI 0.64.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_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
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...

## 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

enum 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

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

## 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 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_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.