AMD_DBGAPI
0.30.0
|
Asynchronous event management. More...
Data Structures | |
struct | amd_dbgapi_event_id_t |
Opaque event handle. More... | |
Macros | |
#define | AMD_DBGAPI_EVENT_NONE (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 runtime state. More... | |
enum | amd_dbgapi_event_info_t { AMD_DBGAPI_EVENT_INFO_KIND = 1, AMD_DBGAPI_EVENT_INFO_WAVE = 2, AMD_DBGAPI_EVENT_INFO_BREAKPOINT = 3, AMD_DBGAPI_EVENT_INFO_CLIENT_THREAD = 4, AMD_DBGAPI_EVENT_INFO_RUNTIME_STATE = 5 } |
Event queries that are supported by amd_dbgapi_event_get_info. More... | |
Functions | |
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_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_24 |
Obtain the next pending event for a process. More... | |
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_event_get_info (amd_dbgapi_process_id_t process_id, amd_dbgapi_event_id_t event_id, amd_dbgapi_event_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_30 |
Query information about an event. More... | |
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_event_processed (amd_dbgapi_process_id_t process_id, amd_dbgapi_event_id_t event_id) AMD_DBGAPI_VERSION_0_24 |
Report that an event has been processed. More... | |
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_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.
#define AMD_DBGAPI_EVENT_NONE (amd_dbgapi_event_id_t{ 0 }) |
The NULL event handle.
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_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 |
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. 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 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 |
AMD_DBGAPI_EVENT_KIND_RUNTIME | The runtime support in the inferior has been loaded or unloaded. Until it has been successfully loaded no code objects will be loaded and no waves will be created. The client can use this event to determine when to activate and deactivate AMD GPU debugging functionality. This event reports the load status, the version, and if it is compatible with this library. If it is not compatible, then no code objects or waves will be reported to exist. |
AMD_DBGAPI_EVENT_KIND_QUEUE_ERROR | An event has occurred that is causing the queue to enter the error state. All non-stopped waves executing on the queue will have been stopped and a AMD_DBGAPI_EVENT_KIND_WAVE_STOP event will proceed this event. All waves on the queue will include the AMD_DBGAPI_WAVE_STOP_REASON_QUEUE_ERROR stop reason. No further waves will be started on the queue. The AMD_DBGAPI_QUEUE_INFO_ERROR_REASON query will include the union of the reasons 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 reasons 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 all the waves in the queue are stopped. 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. The queue error will not be reported to the inferior runtime until this event is reported as complete by calling amd_dbgapi_event_processed. Once reported to the inferior runtime, it may cause the application to be notified which 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 user from determining if a wave caused the error. Therefore, the client may choose to stop inferior threads before reporting the event as complete. This would prevent the queue error from causing the queue to be deleted, allowing the user to inspect all the waves in the queue. Alternatively, the client may not report the event as complete until the user explicitly requests the queue error to be passed on to the inferior runtime. |
Inferior runtime state.
Enumerator | |
---|---|
AMD_DBGAPI_RUNTIME_STATE_LOADED_SUCCESS | The runtime has been loaded and debugging is supported by the library. |
AMD_DBGAPI_RUNTIME_STATE_UNLOADED | The runtime has been unloaded. |
AMD_DBGAPI_RUNTIME_STATE_LOADED_ERROR_RESTRICTION | The runtime has been loaded but there is a restriction error that prevents debugging the process. See AMD_DBGAPI_STATUS_ERROR_RESTRICTION for possible reasons. |
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_event_get_info | ( | amd_dbgapi_process_id_t | process_id, |
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.
[in] | process_id | The process to which event_id belongs. |
[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. |
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_PROCESS_ID | The process_id is invalid. 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_SIZE | value_size does not match the size of the 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_status_t AMD_DBGAPI amd_dbgapi_event_processed | ( | amd_dbgapi_process_id_t | process_id, |
amd_dbgapi_event_id_t | event_id | ||
) |
Report that an event has been processed.
Every event returned by amd_dbgapi_next_pending_event must be reported as processed exactly once.
[in] | process_id | The process to which event_id belongs. |
[in] | event_id | The event that has been processed. |
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_PROCESS_ID | The process_id is invalid. No event is marked as processed. |
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_status_t AMD_DBGAPI amd_dbgapi_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 for a process.
[in] | process_id | The process from which to retrieve pending events. |
[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. |
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. |