Events

Events#

AMD DBG API: Events

Asynchronous event management. More...

Data Structures
struct	amd_dbgapi_event_id_t
	Opaque event handle. More...

Macros
#define	AMD_DBGAPI_EVENT_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_event_id_t, 0)
	The NULL event handle. More...

Enumerations
enum	amd_dbgapi_event_kind_t { AMD_DBGAPI_EVENT_KIND_NONE = 0 , AMD_DBGAPI_EVENT_KIND_WAVE_STOP = 1 , AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED = 2 , AMD_DBGAPI_EVENT_KIND_CODE_OBJECT_LIST_UPDATED = 3 , AMD_DBGAPI_EVENT_KIND_BREAKPOINT_RESUME = 4 , AMD_DBGAPI_EVENT_KIND_RUNTIME = 5 , AMD_DBGAPI_EVENT_KIND_QUEUE_ERROR = 6 }
	The event kinds. More...

enum	amd_dbgapi_runtime_state_t { AMD_DBGAPI_RUNTIME_STATE_LOADED_SUCCESS = 1 , AMD_DBGAPI_RUNTIME_STATE_UNLOADED = 2 , AMD_DBGAPI_RUNTIME_STATE_LOADED_ERROR_RESTRICTION = 3 }
	Inferior's runtime state. More...

enum	amd_dbgapi_event_info_t { AMD_DBGAPI_EVENT_INFO_PROCESS = 1 , AMD_DBGAPI_EVENT_INFO_KIND = 2 , AMD_DBGAPI_EVENT_INFO_WAVE = 3 , AMD_DBGAPI_EVENT_INFO_BREAKPOINT = 4 , AMD_DBGAPI_EVENT_INFO_CLIENT_THREAD = 5 , AMD_DBGAPI_EVENT_INFO_RUNTIME_STATE = 6 , AMD_DBGAPI_EVENT_INFO_QUEUE = 7 }
	Event queries that are supported by amd_dbgapi_event_get_info. More...

Functions
amd_dbgapi_status_t AMD_DBGAPI	amd_dbgapi_process_next_pending_event (amd_dbgapi_process_id_t process_id, amd_dbgapi_event_id_t event_id, amd_dbgapi_event_kind_t kind) AMD_DBGAPI_VERSION_0_54
	Obtain the next pending event. More...

amd_dbgapi_status_t AMD_DBGAPI	amd_dbgapi_event_get_info (amd_dbgapi_event_id_t event_id, amd_dbgapi_event_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_54
	Query information about an event. More...

amd_dbgapi_status_t AMD_DBGAPI	amd_dbgapi_event_processed (amd_dbgapi_event_id_t event_id) AMD_DBGAPI_VERSION_0_54
	Report that an event has been processed. More...

Detailed Description

Asynchronous event management.

Events can occur asynchronously. The library maintains a list of pending events that have happened but not yet been reported to the client. Events are maintained independently for each process.

When amd_dbgapi_process_attach successfully attaches to a process a amd_dbgapi_notifier_t notifier is created that is available using the AMD_DBGAPI_PROCESS_INFO_NOTIFIER query. When this indicates there may be pending events for the process, amd_dbgapi_process_next_pending_event can be used to retrieve the pending events.

The notifier must be reset before retrieving pending events so that the notifier will always conservatively indicate there may be pending events. After the client has processed an event it must report completion using amd_dbgapi_event_processed.

See also: amd_dbgapi_notifier_t

Macro Definition Documentation

◆ AMD_DBGAPI_EVENT_NONE

#define AMD_DBGAPI_EVENT_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_event_id_t, 0)

The NULL event handle.

Enumeration Type Documentation

◆ amd_dbgapi_event_info_t

enum amd_dbgapi_event_info_t

Event queries that are supported by amd_dbgapi_event_get_info.

Each query specifies the type of data returned in the value argument to amd_dbgapi_event_get_info.

Enumerator
AMD_DBGAPI_EVENT_INFO_PROCESS	Return the process to which this event belongs. The type of this attribute is amd_dbgapi_process_id_t.
AMD_DBGAPI_EVENT_INFO_KIND	Return the event kind. The type of this attribute is amd_dbgapi_event_kind_t.
AMD_DBGAPI_EVENT_INFO_WAVE	Return the wave of a AMD_DBGAPI_EVENT_KIND_WAVE_STOP or AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED event. The type of this attribute is a amd_dbgapi_wave_id_t.
AMD_DBGAPI_EVENT_INFO_BREAKPOINT	Return the breakpoint of a AMD_DBGAPI_EVENT_KIND_BREAKPOINT_RESUME event. The type of this attribute is a amd_dbgapi_breakpoint_id_t.
AMD_DBGAPI_EVENT_INFO_CLIENT_THREAD	Return the client thread of a AMD_DBGAPI_EVENT_KIND_BREAKPOINT_RESUME event. The type of this attribute is a amd_dbgapi_client_thread_id_t.
AMD_DBGAPI_EVENT_INFO_RUNTIME_STATE	Return if the runtime loaded in the inferior is supported by the library for a AMD_DBGAPI_EVENT_KIND_RUNTIME event. The type of this attribute is `uint32_t` with a value defined by amd_dbgapi_runtime_state_t.
AMD_DBGAPI_EVENT_INFO_QUEUE	Return the queue of a AMD_DBGAPI_EVENT_KIND_QUEUE_ERROR event. The type of this attribute is a amd_dbgapi_queue_id_t.

◆ amd_dbgapi_event_kind_t

enum amd_dbgapi_event_kind_t

The event kinds.

Enumerator
AMD_DBGAPI_EVENT_KIND_NONE	No event.
AMD_DBGAPI_EVENT_KIND_WAVE_STOP	A wave has stopped.
AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED	A command for a wave was not able to complete because the wave has terminated. Commands that can result in this event are amd_dbgapi_wave_stop and amd_dbgapi_wave_resume in single step mode. Since the wave terminated before stopping, this event will be reported instead of AMD_DBGAPI_EVENT_KIND_WAVE_STOP. The wave that terminated is available by the AMD_DBGAPI_EVENT_INFO_WAVE query. However, the wave will be invalid since it has already terminated. It is the client's responsibility to know what command was being performed and was unable to complete due to the wave terminating.
AMD_DBGAPI_EVENT_KIND_CODE_OBJECT_LIST_UPDATED	The list of code objects has changed. This event is only reported when a thread is in the process of loading or unloading a code object. It is not reported when attaching to a process even if there are loaded code objects. It is the client's responsibility to fetch the current code object list using amd_dbgapi_process_code_object_list. The thread that caused the code object list to change will be stopped until the event is reported as processed. Before reporting the event has been processed, the client must set any pending breakpoints for newly loaded code objects so that breakpoints will be set before any code in the code object is executed. When the event is reported as complete, a AMD_DBGAPI_EVENT_KIND_BREAKPOINT_RESUME event may be created which must be processed to resume the thread that caused the code object list to change. Leaving the thread stopped may prevent the inferior's runtime from servicing requests from other threads.
AMD_DBGAPI_EVENT_KIND_BREAKPOINT_RESUME	Request to resume a host breakpoint. If amd_dbgapi_report_breakpoint_hit returns with `resume` as false then it indicates that events must be processed before the thread hitting the breakpoint can be resumed. When the necessary event(s) are reported as processed, this event will be added to the pending events. The breakpoint and client thread can then be queried by amd_dbgapi_event_get_info using AMD_DBGAPI_EVENT_INFO_BREAKPOINT and AMD_DBGAPI_EVENT_INFO_CLIENT_THREAD respectively. The client must then resume execution of the thread.
AMD_DBGAPI_EVENT_KIND_RUNTIME	The runtime support in the inferior is enabled or disabled. The client can use this event to determine when to activate and deactivate AMD GPU debugging functionality. The status of the inferior's runtime support can be queried by amd_dbgapi_event_get_info using AMD_DBGAPI_EVENT_INFO_RUNTIME_STATE. If not enabled (AMD_DBGAPI_RUNTIME_STATE_UNLOADED), or enabled but not compatible (AMD_DBGAPI_RUNTIME_STATE_LOADED_ERROR_RESTRICTION), then no code objects, queues, or waves will be reported to exist, and the only event that will be reported is AMD_DBGAPI_EVENT_KIND_RUNTIME. If enabled successfully (AMD_DBGAPI_RUNTIME_STATE_LOADED_SUCCESS) full debugging is supported by the library.
AMD_DBGAPI_EVENT_KIND_QUEUE_ERROR	The inferior's runtime has put a queue into the queue error state due to exceptions being reported for the queue. No further waves will be started on the queue. All waves that belong to the queue are inhibited from executing further instructions regardless of whether they are in the halt state. See AMD_DBGAPI_QUEUE_STATE_ERROR. The AMD_DBGAPI_QUEUE_INFO_ERROR_REASON query will include the union of the exceptions that were reported. Some waves may be stopped before they were able to report a queue error condition. The wave stop reason will only include the exceptions that were reported. For example, if many waves encounter a memory violation at the same time, only some of the waves may report it before execution of all the waves in the queue is inhibited. Only the waves that were able to report the memory violation before all the waves were stopped will include the AMD_DBGAPI_WAVE_STOP_REASON_MEMORY_VIOLATION stop reason. Any waves that have a pending single step will report a AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED event to indicate that the single step has been cancelled. Waves in such queues are inhibited from executing any further instructions. The application can delete the queue, which will result in all the waves to also be deleted, and then create a new queue. The inferior's runtime will not notify the application of the queue error until this event is reported as complete by calling amd_dbgapi_event_processed. Once the application is notified, it may abort, or it may delete and re-create the queue in order to continue submitting dispatches to the AMD GPU. If the application deletes a queue then all information about the waves executing on the queue will be lost, preventing the client from determining if a wave caused the error.

◆ amd_dbgapi_runtime_state_t

enum amd_dbgapi_runtime_state_t

Inferior's runtime state.

Enumerator

AMD_DBGAPI_RUNTIME_STATE_LOADED_SUCCESS

The inferior's runtime has been loaded and debugging is supported by the library.

AMD_DBGAPI_RUNTIME_STATE_UNLOADED

The inferior's runtime has been unloaded.

AMD_DBGAPI_RUNTIME_STATE_LOADED_ERROR_RESTRICTION

The inferior's runtime has been loaded but there is a restriction error that prevents debugging the process.

See AMD_DBGAPI_STATUS_ERROR_RESTRICTION for possible reasons.

Function Documentation

◆ amd_dbgapi_event_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_event_get_info	(	amd_dbgapi_event_id_t	event_id,
		amd_dbgapi_event_info_t	query,
		size_t	value_size,
		void *	value
	)

Query information about an event.

amd_dbgapi_event_info_t specifies the queries supported and the type returned using the value argument.

Parameters

[in]	event_id	The event 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_EVENT_ID	`event_id` is invalid or the NULL event. `value` is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT	`value` is NULL or `query` is for an attribute not present for the kind of the event. `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_event_processed()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_event_processed ( amd_dbgapi_event_id_t event_id )

Report that an event has been processed.

Every event returned by amd_dbgapi_process_next_pending_event must be reported as processed exactly once. Events do not have to be reported completed in the same order they are retrieved.

Parameters

[in] event_id The event that has been processed.

Return values

AMD_DBGAPI_STATUS_SUCCESS	The function has been executed successfully and the event has been reported as processed. The `event_id` is invalidated.
AMD_DBGAPI_STATUS_FATAL	A fatal error occurred. The library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED	The library is not initialized. The library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_INVALID_EVENT_ID	The `event_id` is invalid or the NULL event. No event is marked as processed.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT	`event_id` or `kind` are NULL. No event is marked as processed.

◆ amd_dbgapi_process_next_pending_event()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_next_pending_event	(	amd_dbgapi_process_id_t	process_id,
		amd_dbgapi_event_id_t *	event_id,
		amd_dbgapi_event_kind_t *	kind
	)

Obtain the next pending event.

The order events are returned is unspecified. If the client requires fairness then it can retrieve all pending events and randomize the order of processing.

Parameters

[in]	process_id	If AMD_DBGAPI_PROCESS_NONE then retrieve a pending event from any processes. Otherwise, retrieve a pending event from process `process_id`.
[out]	event_id	The event handle of the next pending event. Each event is only returned once. If there are no pending events the AMD_DBGAPI_EVENT_NONE handle is returned.
[out]	kind	The kind of the returned event. If there are no pending events, then AMD_DBGAPI_EVENT_KIND_NONE is returned.

Return values

AMD_DBGAPI_STATUS_SUCCESS	The function has been executed successfully and an event or the NULL event has been returned.
AMD_DBGAPI_STATUS_FATAL	A fatal error occurred. The library is left uninitialized; and `event_id` and `kind` are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED	The library is not initialized. The library is left uninitialized; and `event_id` and `kind` are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID	The `process_id` is invalid. No event is retrieved and `event_id` and `kind` are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT	`event_id` or `kind` are NULL. No event is retrieved and `event_id` and `kind` are unaltered.

Events

Events#

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AMD_DBGAPI_EVENT_NONE

Enumeration Type Documentation

◆ amd_dbgapi_event_info_t

◆ amd_dbgapi_event_kind_t

◆ amd_dbgapi_runtime_state_t

Function Documentation

◆ amd_dbgapi_event_get_info()

◆ amd_dbgapi_event_processed()

◆ amd_dbgapi_process_next_pending_event()