AMD_DBGAPI
0.46.0
|
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(* | enable_notify_shared_library )(amd_dbgapi_client_process_id_t client_process_id, const char *shared_library_name, amd_dbgapi_shared_library_id_t shared_library_id, amd_dbgapi_shared_library_state_t *shared_library_state) |
Request to be notified when a shared library is loaded and unloaded. More... | |
amd_dbgapi_status_t(* | disable_notify_shared_library )(amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_shared_library_id_t shared_library_id) |
Request to stop being notified for a shared library previously set by amd_dbgapi_callbacks_s::enable_notify_shared_library. More... | |
amd_dbgapi_status_t(* | get_symbol_address )(amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_shared_library_id_t shared_library_id, const char *symbol_name, amd_dbgapi_global_address_t *address) |
Return the address of a symbol in a shared library. More... | |
amd_dbgapi_status_t(* | insert_breakpoint )(amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_shared_library_id_t shared_library_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... | |
Callbacks that the client of the library must provide.
The client implementation of the callbacks must not invoke any operation of the library.
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
.
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.
amd_dbgapi_status_t(* amd_dbgapi_callbacks_s::disable_notify_shared_library) (amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_shared_library_id_t shared_library_id) |
Request to stop being notified for a shared library previously set by amd_dbgapi_callbacks_s::enable_notify_shared_library.
shared_library_id
is invalidated.
client_process_id
is the client handle of the process in which loading of the shared library is being notified.
shared_library_id
is the handle of the shared library to stop being notified.
Return AMD_DBGAPI_STATUS_SUCCESS if successful.
Return AMD_DBGAPI_STATUS_ERROR_INVALID_CLIENT_PROCESS_ID if the client_process_id
handle is invalid.
Return AMD_DBGAPI_STATUS_ERROR_INVALID_SHARED_LIBRARY_ID if the shared_library_id
handle is invalid.
Return AMD_DBGAPI_STATUS_ERROR if an error was encountered.
amd_dbgapi_status_t(* amd_dbgapi_callbacks_s::enable_notify_shared_library) (amd_dbgapi_client_process_id_t client_process_id, const char *shared_library_name, amd_dbgapi_shared_library_id_t shared_library_id, amd_dbgapi_shared_library_state_t *shared_library_state) |
Request to be notified when a shared library is loaded and unloaded.
If multiple shared libraries match the name, then the client must only associate shared_library_id
with a single shared library, and only invoke amd_dbgapi_report_shared_library for that single shared library.
client_process_id
is the client handle of the process in which loading of the shared library must be notified.
shared_library_name
is the name of the shared library being requested. The memory is owned by the library and is only valid while the callback executes. On Linux this is the SONAME
of the library.
shared_library_id
is the handle to identify this shared library which must be specified when amd_dbgapi_report_shared_library is used to report a shared library load or unload.
shared_library_state
must be set to a value that indicates whether the shared library is already loaded.
Return AMD_DBGAPI_STATUS_SUCCESS if successful.
Return AMD_DBGAPI_STATUS_ERROR_INVALID_CLIENT_PROCESS_ID if the client_process_id
handle is invalid.
Return AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT if shared_library_name
or shared_library_state
are NULL or shared_library_name
is an invalid library name.
Return AMD_DBGAPI_STATUS_ERROR if the shared_library_name
shared library is already enabled for notifications or another error was encountered.
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.
amd_dbgapi_status_t(* amd_dbgapi_callbacks_s::get_symbol_address) (amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_shared_library_id_t shared_library_id, const char *symbol_name, amd_dbgapi_global_address_t *address) |
Return the address of a symbol in a shared library.
client_process_id
is the client handle of the process being queried.
shared_library_id
is the shared library that contains the symbol.
symbol_name
is the name of the symbol being requested. The memory is owned by the library and is only valid while the callback executes.
address
must be updated with the address of the symbol.
Return AMD_DBGAPI_STATUS_SUCCESS if successful.
Return AMD_DBGAPI_STATUS_ERROR_INVALID_CLIENT_PROCESS_ID if the client_process_id
handle is invalid.
Return AMD_DBGAPI_STATUS_ERROR_INVALID_SHARED_LIBRARY_ID if the shared_library_id
handle is invalid.
Return AMD_DBGAPI_STATUS_ERROR_LIBRARY_NOT_LOADED if shared_library_id
shared library is not currently loaded.
Return AMD_DBGAPI_STATUS_ERROR_SYMBOL_NOT_FOUND if shared_library_id
shared library is loaded but does not contain symbol_name
.
Return AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT if symbol_name
or address
are NULL.
Return AMD_DBGAPI_STATUS_ERROR if an error was encountered.
amd_dbgapi_status_t(* amd_dbgapi_callbacks_s::insert_breakpoint) (amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_shared_library_id_t shared_library_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.
shared_library_id
is the shared library that contains the address
.
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_SHARED_LIBRARY_ID if the shared_library_id
handle is invalid. No breakpoint is added.
Return AMD_DBGAPI_STATUS_ERROR_LIBRARY_NOT_LOADED if shared_library_id
shared library is not currently loaded. No breakpoint is added.
Return AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS if address
is not an address in shared library shared_library_id
. 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.
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.
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.