amd_dbgapi_callbacks_s Struct Reference

amd_dbgapi_callbacks_s Struct Reference#

AMD Debugger API: amd_dbgapi_callbacks_s Struct Reference

Callbacks that the client of the library must provide. More...

#include <amd-dbgapi.h>

Data Fields
void (	allocate_memory )(size_t byte_size)
	Allocate memory to be used to return a value from the library that is then owned by the client. More...

void(*	deallocate_memory )(void *data)
	Deallocate memory that was allocated by amd_dbgapi_callbacks_s::allocate_memory. More...

amd_dbgapi_status_t(*	client_process_get_info )(amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_client_process_info_t query, size_t value_size, void *value)
	Query information about the client process. More...

amd_dbgapi_status_t(*	insert_breakpoint )(amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_global_address_t address, amd_dbgapi_breakpoint_id_t breakpoint_id)
	Insert a breakpoint in a shared library using a global address. More...

amd_dbgapi_status_t(*	remove_breakpoint )(amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_breakpoint_id_t breakpoint_id)
	Remove a breakpoint previously inserted by amd_dbgapi_callbacks_s::insert_breakpoint. More...

amd_dbgapi_status_t(*	xfer_global_memory )(amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_global_address_t global_address, amd_dbgapi_size_t value_size, void read_buffer, const void *write_buffer)
	Uncached global memory transfer. More...

void(*	log_message )(amd_dbgapi_log_level_t level, const char *message)
	Report a log message. More...

Detailed Description

Callbacks that the client of the library must provide.

The client implementation of the callbacks must not invoke any operation of the library.

Field Documentation

◆ allocate_memory

void*(* amd_dbgapi_callbacks_s::allocate_memory) (size_t byte_size)

Allocate memory to be used to return a value from the library that is then owned by the client.

The memory should be suitably aligned for any type. If byte_size is 0 or if unable to allocate memory of the byte size specified by byte_size then return NULL and allocate no memory. The client is responsible for deallocating this memory, and so is responsible for tracking the size of the allocation. Note that these requirements can be met by implementing using malloc.

◆ client_process_get_info

amd_dbgapi_status_t(* amd_dbgapi_callbacks_s::client_process_get_info) (amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_client_process_info_t query, size_t value_size, void *value)

Query information about the client process.

client_process_id is the client handle of the process for which the operating system process handle is being queried.

query identifies the client process information queried by the library.

value_size is the size in bytes of the buffer value points to.

value points to a buffer of size value_size where the client should copy the value requested by the library.

Return AMD_DBGAPI_STATUS_SUCCESS if successful and value is updated.

Return AMD_DBGAPI_STATUS_ERROR_INVALID_CLIENT_PROCESS_ID if the client_process_id handle is invalid.

Return AMD_DBGAPI_STATUS_ERROR_PROCESS_EXITED if the client_process_id handle is associated with a native operating system process that has already exited.

Return AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT if value is NULL.

Return AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE if the requested information is not available for the process referenced by client_process_id.

Return AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY if value_size does not match the size of the data requested by the library.

Return AMD_DBGAPI_STATUS_ERROR if an error was encountered.

◆ deallocate_memory

void(* amd_dbgapi_callbacks_s::deallocate_memory) (void *data)

Deallocate memory that was allocated by amd_dbgapi_callbacks_s::allocate_memory.

data will be a pointer returned by amd_dbgapi_callbacks_s::allocate_memory that will not be returned to the client. If data is NULL then it indicates the allocation failed or was for 0 bytes: in either case the callback is required to take no action. If data is not NULL then it will not have been deallocated by a previous call to amd_dbgapi_callbacks_s::allocate_memory. Note that these requirements can be met by implementing using free.

Note this callback may be used by the library implementation if it encounters an error after using amd_dbgapi_callbacks_s::allocate_memory to allocate memory.

◆ insert_breakpoint

amd_dbgapi_status_t(* amd_dbgapi_callbacks_s::insert_breakpoint) (amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_global_address_t address, amd_dbgapi_breakpoint_id_t breakpoint_id)

Insert a breakpoint in a shared library using a global address.

The library only inserts breakpoints in loaded shared libraries. It will request to be notified when the shared library is unloaded, and will remove any breakpoints it has inserted when notified that the shared library is unloaded.

It is the client's responsibility to to actually insert the breakpoint.

client_process_id is the client handle of the process in which the breakpoint is to be added.

address is the global address to add the breakpoint.

breakpoint_id is the handle to identify this breakpoint. Each added breakpoint for a process will have a unique handle, multiple breakpoints for the same process will not be added with the same handle. It must be specified when amd_dbgapi_report_breakpoint_hit is used to report a breakpoint hit, and in the AMD_DBGAPI_EVENT_KIND_BREAKPOINT_RESUME event that may be used to resume the thread.

Return AMD_DBGAPI_STATUS_SUCCESS if successful. The breakpoint is added.

Return AMD_DBGAPI_STATUS_ERROR_INVALID_CLIENT_PROCESS_ID if the client_process_id handle is invalid. No breakpoint is added.

Return AMD_DBGAPI_STATUS_ERROR_INVALID_BREAKPOINT_ID if there is a breakpoint already added with breakpoint_id. No breakpoint is added.

Return AMD_DBGAPI_STATUS_ERROR if another error was encountered. No breakpoint is inserted and the breakpoint_id handle is invalidated.

◆ log_message

void(* amd_dbgapi_callbacks_s::log_message) (amd_dbgapi_log_level_t level, const char *message)

Report a log message.

level is the log level.

message is a NUL terminated string to print that is owned by the library and is only valid while the callback executes.

◆ remove_breakpoint

amd_dbgapi_status_t(* amd_dbgapi_callbacks_s::remove_breakpoint) (amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_breakpoint_id_t breakpoint_id)

Remove a breakpoint previously inserted by amd_dbgapi_callbacks_s::insert_breakpoint.

It is the client's responsibility to to actually remove the breakpoint.

breakpoint_id is invalidated.

client_process_id is the client handle of the process in which the breakpoint is to be removed.

breakpoint_id is the breakpoint handle of the breakpoint to remove.

Return AMD_DBGAPI_STATUS_SUCCESS if successful. The breakpoint is removed.

Return AMD_DBGAPI_STATUS_ERROR_INVALID_CLIENT_PROCESS_ID if the client_process_id handle is invalid. No breakpoint is removed.

Return AMD_DBGAPI_STATUS_ERROR_INVALID_BREAKPOINT_ID if breakpoint_id handle is invalid. No breakpoint is removed.

Return ::AMD_DBGAPI_STATUS_ERROR_LIBRARY_NOT_LOADED if the shared library containing the breakpoint is not currently loaded. The breakpoint will already have been removed.

Return AMD_DBGAPI_STATUS_ERROR if another error was encountered. The breakpoint is considered removed and the breakpoint_id handle is invalidated.

◆ xfer_global_memory

amd_dbgapi_status_t(* amd_dbgapi_callbacks_s::xfer_global_memory) (amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_global_address_t global_address, amd_dbgapi_size_t *value_size, void *read_buffer, const void *write_buffer)

Uncached global memory transfer.

client_process_id is the client handle of the process for which the memory transfer is being requested.

global_address is the global address space address of the start of the memory transfer being requested.

value_size is the number of bytes of the memory transfer being requested.

read_buffer if not NULL then a read transfer is being requested. On return, contains the read bytes and value_size is set to the number of bytes actually read.

write_buffer if not NULL then a write transfer is being requested. Contains the bytes to be written. On return value_size is set to the number of bytes actually written.

Return AMD_DBGAPI_STATUS_SUCCESS if successful.