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(*	get_os_pid )(amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_os_process_id_t *os_pid)
	Return the native operating system process handle for the process identified by the client process handle. 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...

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.

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

◆ get_os_pid

amd_dbgapi_status_t(* amd_dbgapi_callbacks_s::get_os_pid) (amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_os_process_id_t *os_pid)

Return the native operating system process handle for the process identified by the client 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 is required to have already been ptrace enabled.

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

os_pid must be set to the native operating system process handle.

Return AMD_DBGAPI_STATUS_SUCCESS if successful and os_pid 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 os_pid is NULL.

Return AMD_DBGAPI_STATUS_ERROR if an error was encountered.

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

The documentation for this struct was generated from the following file:

/home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-rocdbgapi-docs/checkouts/latest/include/amd-dbgapi.h

amd_dbgapi_callbacks_s Struct Reference

amd_dbgapi_callbacks_s Struct Reference#

Data Fields