AMD_DBGAPI
0.31.0
|
Operations related to AMD GPU hardware data watchpoints. More...
Data Structures | |
struct | amd_dbgapi_watchpoint_id_t |
Opaque hardware data watchpoint handle. More... | |
struct | amd_dbgapi_watchpoint_list_t |
A set of watchpoints. More... | |
Macros | |
#define | AMD_DBGAPI_WATCHPOINT_NONE (amd_dbgapi_watchpoint_id_t{ 0 }) |
The NULL hardware data watchpoint handle. More... | |
Enumerations | |
enum | amd_dbgapi_watchpoint_share_kind_t { AMD_DBGAPI_WATCHPOINT_SHARE_KIND_UNSUPPORTED = 0, AMD_DBGAPI_WATCHPOINT_SHARE_KIND_UNSHARED = 1, AMD_DBGAPI_WATCHPOINT_SHARE_KIND_SHARED = 2 } |
The way watchpoints are shared between processes. More... | |
enum | amd_dbgapi_watchpoint_kind_t { AMD_DBGAPI_WATCHPOINT_KIND_LOAD = 1, AMD_DBGAPI_WATCHPOINT_KIND_STORE_AND_RMW = 2, AMD_DBGAPI_WATCHPOINT_KIND_RMW = 3, AMD_DBGAPI_WATCHPOINT_KIND_ALL = 4 } |
Watchpoint memory access kinds. More... | |
Functions | |
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_set_watchpoint (amd_dbgapi_process_id_t process_id, amd_dbgapi_global_address_t address, amd_dbgapi_size_t size, amd_dbgapi_watchpoint_kind_t kind, amd_dbgapi_watchpoint_id_t *watchpoint_id, amd_dbgapi_global_address_t *watchpoint_address, amd_dbgapi_size_t *watchpoint_size) AMD_DBGAPI_VERSION_0_31 |
Set a hardware data watchpoint. More... | |
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_remove_watchpoint (amd_dbgapi_process_id_t process_id, amd_dbgapi_watchpoint_id_t watchpoint_id) AMD_DBGAPI_VERSION_0_24 |
Remove a hardware data watchpoint previously set by amd_dbgapi_set_watchpoint. More... | |
Operations related to AMD GPU hardware data watchpoints.
A data watchpoint is a hardware supported mechanism to generate wave stop events after a wave accesses memory in a certain way in a certain address range. The memory access will have been completed before the event is reported.
The number of watchpoints, the granularity of base address, and the address range is process specific. If a process has multiple agents, then the values are the lowest common denominator of the capabilities of the architectures of all the agents of a process.
The number of watchpoints supported by a process is available using the AMD_DBGAPI_PROCESS_INFO_WATCHPOINT_COUNT query and may be 0. The AMD_DBGAPI_PROCESS_INFO_WATCHPOINT_SHARE query can be used to determine if watchpoints are shared between processes.
When a wave stops due to a data watchpoint the stop reason will include AMD_DBGAPI_WAVE_STOP_REASON_WATCHPOINT. The set of watchpoints triggered can be queried using AMD_DBGAPI_WAVE_INFO_WATCHPOINTS.
#define AMD_DBGAPI_WATCHPOINT_NONE (amd_dbgapi_watchpoint_id_t{ 0 }) |
The NULL hardware data watchpoint handle.
Watchpoint memory access kinds.
The watchpoint is triggered only when the memory instruction is of the specified kind.
The way watchpoints are shared between processes.
The ::AMD_DBGAPI_ARCHITECTURE_INFO_WATCHPOINT_SHARE query can be used to determine the watchpoint sharing for an architecture.
Enumerator | |
---|---|
AMD_DBGAPI_WATCHPOINT_SHARE_KIND_UNSUPPORTED | Watchpoints are not supported. |
AMD_DBGAPI_WATCHPOINT_SHARE_KIND_UNSHARED | The watchpoints are not shared across processes. Every process can use all AMD_DBGAPI_PROCESS_INFO_WATCHPOINT_COUNT watchpoints. |
AMD_DBGAPI_WATCHPOINT_SHARE_KIND_SHARED | The watchpoints of a process are shared between all processes. The number of watchpoints available to a process may be reduced if watchpoints are used by another process. |
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_remove_watchpoint | ( | amd_dbgapi_process_id_t | process_id, |
amd_dbgapi_watchpoint_id_t | watchpoint_id | ||
) |
Remove a hardware data watchpoint previously set by amd_dbgapi_set_watchpoint.
[in] | process_id | The process that owns the watchpoint. |
[in] | watchpoint_id | The watchpoint to remove. |
AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the watchpoint has been removed. |
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 and no watchpoint is removed. |
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | process_id is invalid. No watchpoint is removed. |
AMD_DBGAPI_STATUS_ERROR_INVALID_WATCHPOINT_ID | watchpoint_id is invalid. No watchpoint is removed. |
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_set_watchpoint | ( | amd_dbgapi_process_id_t | process_id, |
amd_dbgapi_global_address_t | address, | ||
amd_dbgapi_size_t | size, | ||
amd_dbgapi_watchpoint_kind_t | kind, | ||
amd_dbgapi_watchpoint_id_t * | watchpoint_id, | ||
amd_dbgapi_global_address_t * | watchpoint_address, | ||
amd_dbgapi_size_t * | watchpoint_size | ||
) |
Set a hardware data watchpoint.
The AMD GPU has limitations on the base address and size of hardware data watchpoints that can be set, and the limitations may vary by architecture. A watchpoint is created with the smallest range, supported by the architectures of all the agents of a process, that covers the requested range specified by address
and size
.
If the requested range is larger than is supported by the architectures of all the agents of a process, then a watchpoint is created with the smallest range that includes address
and covers as much of the requested range as possible.
The range of the created watchpoint is returned in watchpoint_address
and watchpoint_size
. The client is responsible for determining if the created watchpoint completely covers the requested range. If it does not, the client can attempt to create additional watchpoints for the uncovered portion of the requested range.
When a watchpoint is triggered, the client is responsible for determining if the access was to the requested range. For example, for writes the client can compare the original value with the current value to determine if it changed.
Each process has its own set of watchpoints. Only waves executing on the agents of a process will trigger the watchpoints set on that process.
[in] | process_id | The process on which to set the watchpoint. |
[in] | address | The base address of memory area to set a watchpoint. |
[in] | size | The non-zero number of bytes that the watchpoint should cover. |
[in] | kind | The kind of memory access that should trigger the watchpoint. |
[out] | watchpoint_id | The watchpoint created. |
[out] | watchpoint_address | The base address of the created watchpoint. |
[out] | watchpoint_size | The byte size of the created watchpoint. |
AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the watchpoint has been created with handle watchpoint_id that covers the range specified by watchpoint_address and watchpoint_size . |
AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized; and watchpoint_id , watchpoint_address , and watchpoint_size are unaltered. |
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized; and watchpoint_id , watchpoint_address , and watchpoint_size are unaltered. |
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | process_id is invalid. No watchpoint is set and watchpoint_id , watchpoint_address , and watchpoint_size are unaltered. |
AMD_DBGAPI_STATUS_ERROR_NO_WATCHPOINT_AVAILABLE | No more watchpoints are available. No watchpoint is set and watchpoint_id , watchpoint_address , and watchpoint_size are unaltered. |
AMD_DBGAPI_STATUS_ERROR_NOT_SUPPORTED | Watchpoints are not supported for the architectures of all the agents. No watchpoint is set and watchpoint_id , watchpoint_address , and watchpoint_size are unaltered. |
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | kind is invalid; size is 0; or watchpoint_id , watchpoint_address , or watchpoint_size are NULL. No watchpoint is set and watchpoint_id , watchpoint_address , and watchpoint_size are unaltered. |