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_HANDLE_LITERAL (amd_dbgapi_watchpoint_id_t, 0)
	The NULL hardware data watchpoint handle. More...

Enumerations
enum	amd_dbgapi_watchpoint_info_t { AMD_DBGAPI_WATCHPOINT_INFO_PROCESS = 1 , AMD_DBGAPI_WATCHPOINT_INFO_ADDRESS = 2 , AMD_DBGAPI_WATCHPOINT_INFO_SIZE = 3 }
	Watchpoint queries that are supported by amd_dbgapi_watchpoint_get_info. More...

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_watchpoint_get_info (amd_dbgapi_watchpoint_id_t watchpoint_id, amd_dbgapi_watchpoint_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_54
	Query information about a watchpoint. More...

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_VERSION_0_76
	Set a hardware data watchpoint. More...

amd_dbgapi_status_t AMD_DBGAPI	amd_dbgapi_remove_watchpoint (amd_dbgapi_watchpoint_id_t watchpoint_id) AMD_DBGAPI_VERSION_0_76
	Remove a hardware data watchpoint previously set by amd_dbgapi_set_watchpoint. More...

Detailed Description

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.

Macro Definition Documentation

◆ AMD_DBGAPI_WATCHPOINT_NONE

#define AMD_DBGAPI_WATCHPOINT_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_watchpoint_id_t, 0)

The NULL hardware data watchpoint handle.

Enumeration Type Documentation

◆ amd_dbgapi_watchpoint_info_t

enum amd_dbgapi_watchpoint_info_t

Watchpoint queries that are supported by amd_dbgapi_watchpoint_get_info.

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

Enumerator

AMD_DBGAPI_WATCHPOINT_INFO_PROCESS

Return the process to which this watchpoint belongs.

The type of this attribute is amd_dbgapi_process_id_t.

AMD_DBGAPI_WATCHPOINT_INFO_ADDRESS

The base address of the created watchpoint.

The type of this attribute is amd_dbgapi_global_address_t.

AMD_DBGAPI_WATCHPOINT_INFO_SIZE

The byte size of the created watchpoint.

The type of this attribute is amd_dbgapi_size_t.

◆ amd_dbgapi_watchpoint_kind_t

enum amd_dbgapi_watchpoint_kind_t

Watchpoint memory access kinds.

The watchpoint is triggered only when the memory instruction is of the specified kind.

Enumerator
AMD_DBGAPI_WATCHPOINT_KIND_LOAD	Read access by load instructions.
AMD_DBGAPI_WATCHPOINT_KIND_STORE_AND_RMW	Write access by store instructions or read-modify-write access by atomic instructions.
AMD_DBGAPI_WATCHPOINT_KIND_RMW	Read-modify-write access by atomic instructions.
AMD_DBGAPI_WATCHPOINT_KIND_ALL	Read, write, or read-modify-write access by load, store, or atomic instructions.

◆ amd_dbgapi_watchpoint_share_kind_t

enum amd_dbgapi_watchpoint_share_kind_t

The way watchpoints are shared between processes.

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

Function Documentation

◆ amd_dbgapi_remove_watchpoint()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_remove_watchpoint ( amd_dbgapi_watchpoint_id_t watchpoint_id )

Remove a hardware data watchpoint previously set by amd_dbgapi_set_watchpoint.

Parameters

[in] watchpoint_id The watchpoint to remove.

Return values

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_WATCHPOINT_ID	`watchpoint_id` is invalid. No watchpoint is removed.
AMD_DBGAPI_STATUS_ERROR_PROCESS_FROZEN	This operation is not allowed when the process is frozen. No watchpoint is removed.

◆ amd_dbgapi_set_watchpoint()

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
	)

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 can be queried using AMD_DBGAPI_WATCHPOINT_INFO_PROCESS and AMD_DBGAPI_WATCHPOINT_INFO_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.

Parameters

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

Return values

AMD_DBGAPI_STATUS_SUCCESS	The function has been executed successfully and the watchpoint has been created with handle `watchpoint_id`.
AMD_DBGAPI_STATUS_FATAL	A fatal error occurred. The library is left uninitialized; and `watchpoint_id` is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED	The library is not initialized. The library is left uninitialized; and `watchpoint_id` is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID	`process_id` is invalid. No watchpoint is set and `watchpoint_id` is unaltered.
AMD_DBGAPI_STATUS_ERROR_NO_WATCHPOINT_AVAILABLE	No more watchpoints are available. No watchpoint is set and `watchpoint_id` is 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` is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT	`kind` is invalid; `size` is 0 or `watchpoint_id` is NULL. No watchpoint is set and `watchpoint_id` is unaltered.
AMD_DBGAPI_STATUS_ERROR_PROCESS_FROZEN	This operation is not permitted when the process frozen. No watchpoint is set and `watchpoint_id` is unaltered.

◆ amd_dbgapi_watchpoint_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_watchpoint_get_info	(	amd_dbgapi_watchpoint_id_t	watchpoint_id,
		amd_dbgapi_watchpoint_info_t	query,
		size_t	value_size,
		void *	value
	)

Query information about a watchpoint.

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

Parameters

[in]	watchpoint_id	The handle of the watchpoint 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_WATCHPOINT_ID	`watchpoint_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.

Watchpoints

Watchpoints#

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AMD_DBGAPI_WATCHPOINT_NONE

Enumeration Type Documentation

◆ amd_dbgapi_watchpoint_info_t

◆ amd_dbgapi_watchpoint_kind_t

◆ amd_dbgapi_watchpoint_share_kind_t

Function Documentation

◆ amd_dbgapi_remove_watchpoint()

◆ amd_dbgapi_set_watchpoint()

◆ amd_dbgapi_watchpoint_get_info()