Callbacks

Callbacks#

AMD DBG API: Callbacks

The library requires the client to provide a number of services. 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
	Forward declaration of callbacks used to specify services that must be provided by the client. More...

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

enum	amd_dbgapi_client_process_info_t { AMD_DBGAPI_CLIENT_PROCESS_INFO_OS_PID = 1 , AMD_DBGAPI_CLIENT_PROCESS_INFO_CORE_STATE = 2 }
	Client queries that are supported by the client_process_get_info callback. 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.

◆ amd_dbgapi_client_process_info_t

enum amd_dbgapi_client_process_info_t

Client queries that are supported by the client_process_get_info callback.

Each query specifies the type of data returned in the value argument to amd_dbgapi_callbacks_s::client_process_get_info.

Enumerator

AMD_DBGAPI_CLIENT_PROCESS_INFO_OS_PID

Return the native operating system 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 the corresponding process is required to have already been ptrace enabled.

The type of this attribute is amd_dbgapi_os_process_id_t.

AMD_DBGAPI_CLIENT_PROCESS_INFO_CORE_STATE

If the current process is created from a core file, return the content of the AMDGPU state note if present.

If the process image is not created from a core dump or if such state note is not present in the core dump, the client_process_get_info callback returns AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE.

The type of this attribute is ::amd_dbgapi_core_state_note_data_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.