AMD_DBGAPI: Memory

AMD_DBGAPI 0.77.4

Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions
Memory

Operations related to AMD GPU memory access. More...

## Data Structures
struct | amd_dbgapi_address_class_id_t
| Opaque source language address class handle. More...
struct | amd_dbgapi_address_space_id_t
| Opaque address space handle. More...

## Macros
#define | AMD_DBGAPI_LANE_NONE ((amd_dbgapi_lane_id_t) (-1))
| The NULL lane handle.
#define | AMD_DBGAPI_ADDRESS_CLASS_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_class_id_t, 0)
| The NULL address class handle.
#define | AMD_DBGAPI_ADDRESS_SPACE_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_space_id_t, 0)
| The NULL address space handle.
#define | AMD_DBGAPI_ADDRESS_SPACE_GLOBAL AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_space_id_t, 1)
| The global address space handle.

## Typedefs
typedef uint32_t | amd_dbgapi_lane_id_t
| A wave lane handle.
typedef uint64_t | amd_dbgapi_segment_address_t
| Each address space has its own linear address to access it termed a segment address.

## Enumerations
enum | amd_dbgapi_address_class_info_t { AMD_DBGAPI_ADDRESS_CLASS_INFO_NAME = 1 , AMD_DBGAPI_ADDRESS_CLASS_INFO_ADDRESS_SPACE = 2 , AMD_DBGAPI_ADDRESS_CLASS_INFO_DWARF = 3 }
| Source language address class queries that are supported by amd_dbgapi_address_class_get_info. More...
enum | amd_dbgapi_address_space_access_t { AMD_DBGAPI_ADDRESS_SPACE_ACCESS_ALL = 1 , AMD_DBGAPI_ADDRESS_SPACE_ACCESS_PROGRAM_CONSTANT = 2 , AMD_DBGAPI_ADDRESS_SPACE_ACCESS_DISPATCH_CONSTANT = 3 }
| Indication of how the address space is accessed. More...
enum | amd_dbgapi_address_space_info_t { AMD_DBGAPI_ADDRESS_SPACE_INFO_NAME = 1 , AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE = 2 , AMD_DBGAPI_ADDRESS_SPACE_INFO_NULL_ADDRESS = 3 , AMD_DBGAPI_ADDRESS_SPACE_INFO_ACCESS = 4 , AMD_DBGAPI_ADDRESS_SPACE_INFO_DWARF = 5 }
| Address space queries that are supported by amd_dbgapi_address_space_get_info. More...
enum | amd_dbgapi_segment_address_dependency_t { AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_NONE = 0 , AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_LANE = 1 , AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_WAVE = 2 , AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_WORKGROUP = 3 , AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_AGENT = 4 , AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_PROCESS = 5 }
| The dependency when reading or writing a specific segment address of an address space using the amd_dbgapi_read_memory and amd_dbgapi_write_memory operations. More...
enum | amd_dbgapi_address_class_state_t { AMD_DBGAPI_ADDRESS_CLASS_STATE_NOT_MEMBER = 0 , AMD_DBGAPI_ADDRESS_CLASS_STATE_MEMBER = 1 }
| Indication of whether a segment address in an address space is a member of an source language address class. More...
enum | amd_dbgapi_memory_precision_t { AMD_DBGAPI_MEMORY_PRECISION_NONE = 0 , AMD_DBGAPI_MEMORY_PRECISION_PRECISE = 1 }
| Memory access precision. More...
enum | amd_dbgapi_alu_exceptions_precision_t { AMD_DBGAPI_ALU_EXCEPTIONS_PRECISION_NONE = 0 , AMD_DBGAPI_ALU_EXCEPTIONS_PRECISION_PRECISE = 1 }
| ALU exceptions reporting precision. More...

## Functions
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_address_class_get_info (amd_dbgapi_address_class_id_t address_class_id, amd_dbgapi_address_class_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_62
| Query information about a source language address class of an architecture.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_architecture_address_class_list (amd_dbgapi_architecture_id_t architecture_id, size_t *address_class_count, amd_dbgapi_address_class_id_t **address_classes) AMD_DBGAPI_VERSION_0_54
| Report the list of source language address classes supported by the architecture.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_dwarf_address_class_to_address_class (amd_dbgapi_architecture_id_t architecture_id, uint64_t dwarf_address_class, amd_dbgapi_address_class_id_t *address_class_id) AMD_DBGAPI_VERSION_0_54
| Return the architecture source language address class from a DWARF address class number for an architecture.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_address_space_get_info (amd_dbgapi_address_space_id_t address_space_id, amd_dbgapi_address_space_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_62
| Query information about an address space.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_architecture_address_space_list (amd_dbgapi_architecture_id_t architecture_id, size_t *address_space_count, amd_dbgapi_address_space_id_t **address_spaces) AMD_DBGAPI_VERSION_0_54
| Report the list of address spaces supported by the architecture.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_dwarf_address_space_to_address_space (amd_dbgapi_architecture_id_t architecture_id, uint64_t dwarf_address_space, amd_dbgapi_address_space_id_t *address_space_id) AMD_DBGAPI_VERSION_0_54
| Return the address space from an AMD GPU DWARF address space number for an architecture.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_convert_address_space (amd_dbgapi_wave_id_t wave_id, amd_dbgapi_lane_id_t lane_id, amd_dbgapi_address_space_id_t source_address_space_id, amd_dbgapi_segment_address_t source_segment_address, amd_dbgapi_address_space_id_t destination_address_space_id, amd_dbgapi_segment_address_t *destination_segment_address, amd_dbgapi_size_t *destination_contiguous_bytes) AMD_DBGAPI_VERSION_0_62
| Convert a source segment address in the source address space into a destination segment address in the destination address space.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_address_dependency (amd_dbgapi_address_space_id_t address_space_id, amd_dbgapi_segment_address_t segment_address, amd_dbgapi_segment_address_dependency_t *segment_address_dependency) AMD_DBGAPI_VERSION_0_64
| Determine the dependency of a segment address value in a particular address space.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_address_is_in_address_class (amd_dbgapi_wave_id_t wave_id, amd_dbgapi_lane_id_t lane_id, amd_dbgapi_address_space_id_t address_space_id, amd_dbgapi_segment_address_t segment_address, amd_dbgapi_address_class_id_t address_class_id, amd_dbgapi_address_class_state_t *address_class_state) AMD_DBGAPI_VERSION_0_54
| Determine if a segment address in an address space is a member of a source language address class.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_read_memory (amd_dbgapi_process_id_t process_id, amd_dbgapi_wave_id_t wave_id, amd_dbgapi_lane_id_t lane_id, amd_dbgapi_address_space_id_t address_space_id, amd_dbgapi_segment_address_t segment_address, amd_dbgapi_size_t *value_size, void *value) AMD_DBGAPI_VERSION_0_54
| Read memory.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_write_memory (amd_dbgapi_process_id_t process_id, amd_dbgapi_wave_id_t wave_id, amd_dbgapi_lane_id_t lane_id, amd_dbgapi_address_space_id_t address_space_id, amd_dbgapi_segment_address_t segment_address, amd_dbgapi_size_t *value_size, const void *value) AMD_DBGAPI_VERSION_0_76
| Write memory.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_set_memory_precision (amd_dbgapi_process_id_t process_id, amd_dbgapi_memory_precision_t memory_precision) AMD_DBGAPI_VERSION_0_54
| Control precision of memory access reporting.
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_set_alu_exceptions_precision (amd_dbgapi_process_id_t process_id, amd_dbgapi_alu_exceptions_precision_t alu_exceptions_precision) AMD_DBGAPI_VERSION_0_77
| Control precision of ALU exceptions reporting.

## Detailed Description

Operations related to AMD GPU memory access.

The AMD GPU supports allocating memory in different address spaces. See [User Guide for AMDGPU Backend - LLVM - Address Spaces] (https://llvm.org/docs/AMDGPUUsage.html#address-spaces).

## Macro Definition Documentation

## ◆ AMD_DBGAPI_ADDRESS_CLASS_NONE

#define AMD_DBGAPI_ADDRESS_CLASS_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_class_id_t, 0)

The NULL address class handle.

## ◆ AMD_DBGAPI_ADDRESS_SPACE_GLOBAL

#define AMD_DBGAPI_ADDRESS_SPACE_GLOBAL AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_space_id_t, 1)

The global address space handle.

Every architecture supports a global address space that uses the same address space ID.

## ◆ AMD_DBGAPI_ADDRESS_SPACE_NONE

#define AMD_DBGAPI_ADDRESS_SPACE_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_space_id_t, 0)

The NULL address space handle.

## ◆ AMD_DBGAPI_LANE_NONE

#define AMD_DBGAPI_LANE_NONE ((amd_dbgapi_lane_id_t) (-1))

The NULL lane handle.

## Typedef Documentation

## ◆ amd_dbgapi_lane_id_t

typedef uint32_t amd_dbgapi_lane_id_t

A wave lane handle.

A wave can have one or more lanes controlled by an execution mask. Vector instructions will be performed for each lane of the wave that the execution mask has enabled. Vector instructions can access registers that are vector registers. A vector register has a separate value for each lane, and vector instructions will access the corresponding component for each lane's evaluation of the instruction.

The number of lanes of a wave can be obtained with the AMD_DBGAPI_WAVE_INFO_LANE_COUNT query. Different waves of the same architecture can have different lane counts.

The AMD GPU compiler may map source language threads of execution to lanes of a wave. The DWARF debug information which maps such source languages to the generated architecture specific code must include information about the lane mapping.

The `DW_ASPACE_AMDGPU_private_lane` DWARF address space supports memory allocated independently for each lane of a wave.

Lanes are numbered from 0 to AMD_DBGAPI_WAVE_INFO_LANE_COUNT minus 1.

Only unique for a single wave of a single process.

## ◆ amd_dbgapi_segment_address_t

typedef uint64_t amd_dbgapi_segment_address_t

Each address space has its own linear address to access it termed a segment address.

Different address spaces may have memory locations that alias each other, but the segment address for such memory locations may be different in each address space. Consequently a segment address is specific to an address space.

Some address spaces may access memory that is allocated independently for each workgroup, for each wave, or for each lane of of a wave. Consequently a segment address may be specific to a wave or lane of a wave.

See [User Guide for AMDGPU Backend - LLVM - Address Spaces] (https://llvm.org/docs/AMDGPUUsage.html#address-spaces).

## Enumeration Type Documentation

## ◆ amd_dbgapi_address_class_info_t

enum amd_dbgapi_address_class_info_t

Source language address class queries that are supported by amd_dbgapi_address_class_get_info.

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

Enumerator
AMD_DBGAPI_ADDRESS_CLASS_INFO_NAME | Return the source language address class name. The type of this attribute is a pointer to a NUL terminated `char`. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.
AMD_DBGAPI_ADDRESS_CLASS_INFO_ADDRESS_SPACE | Return the architecture specific address space that is used to implement a pointer or reference to the source language address class. The type of this attribute is amd_dbgapi_address_class_id_t. See [User Guide for AMDGPU Backend - Code Object - DWARF - Address Class Mapping] (https://llvm.org/docs/AMDGPUUsage.html#address-class-mapping).
AMD_DBGAPI_ADDRESS_CLASS_INFO_DWARF | Return the AMD GPU DWARF address class number for the address class' architecture. The type of this attribute is `uint64_t`.

## ◆ amd_dbgapi_address_class_state_t

enum amd_dbgapi_address_class_state_t

Indication of whether a segment address in an address space is a member of an source language address class.

Enumerator
AMD_DBGAPI_ADDRESS_CLASS_STATE_NOT_MEMBER | The segment address in the address space is not a member of the source language address class.
AMD_DBGAPI_ADDRESS_CLASS_STATE_MEMBER | The segment address in the address space is a member of the source language address class.

## ◆ amd_dbgapi_address_space_access_t

enum amd_dbgapi_address_space_access_t

Indication of how the address space is accessed.

Enumerator
AMD_DBGAPI_ADDRESS_SPACE_ACCESS_ALL | The address space supports all accesses. Values accessed can change during the lifetime of the program.
AMD_DBGAPI_ADDRESS_SPACE_ACCESS_PROGRAM_CONSTANT | The address space is read only. Values accessed are always the same value for the lifetime of the program execution.
AMD_DBGAPI_ADDRESS_SPACE_ACCESS_DISPATCH_CONSTANT | The address space is only read the waves of a kernel dispatch. Values accessed are always the same value for the lifetime of the dispatch.

## ◆ amd_dbgapi_address_space_info_t

enum amd_dbgapi_address_space_info_t

Address space queries that are supported by amd_dbgapi_address_space_get_info.

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

Enumerator
AMD_DBGAPI_ADDRESS_SPACE_INFO_NAME | Return the address space name. The type of this attribute is a pointer to a NUL terminated `char*`. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.
AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE | Return the byte size of an address in the address space. The type of this attribute is amd_dbgapi_size_t.
AMD_DBGAPI_ADDRESS_SPACE_INFO_NULL_ADDRESS | Return the NULL segment address value in the address space. The type of this attribute is `amd_dbgapi_segment_address_t`.
AMD_DBGAPI_ADDRESS_SPACE_INFO_ACCESS | Return the address space access. The type of this attribute is `uint32_t` with values defined by amd_dbgapi_address_space_access_t.
AMD_DBGAPI_ADDRESS_SPACE_INFO_DWARF | Return the AMD GPU DWARF address space number for the address space's architecture. The type of this attribute is `uint64_t`.

## ◆ amd_dbgapi_alu_exceptions_precision_t

enum amd_dbgapi_alu_exceptions_precision_t

ALU exceptions reporting precision.

Waves may issue multiple instructions and advance the program counter before a previous ALU instruction has executed and reported exceptions. This can result in a wave stopping due to an ALU exception beyond the instruction that caused the wave to stop.

Some architectures allow hardware to be configured to always wait for ALU instructions to complete before issuing to the next instruction. If an exception is raised by the instruction, the wave will stop at the instruction immediately following it. Enabling this mode can make execution of waves slower.

The AMD_DBGAPI_PROCESS_INFO_PRECISE_ALU_EXCEPTIONS_SUPPORTED query can be used to determine if the architectures of all the agents of a process support controlling precise ALU exceptions reporting.

Enumerator
AMD_DBGAPI_ALU_EXCEPTIONS_PRECISION_NONE | ALU exceptions delivery might be reported at any time after the instructions causing them have executed.
AMD_DBGAPI_ALU_EXCEPTIONS_PRECISION_PRECISE | When an ALU exception is delivered to the waves, the wave's PC is at the instruction following the one causing the exception to be raised. This can cause waves to execute slower.

## ◆ amd_dbgapi_memory_precision_t

enum amd_dbgapi_memory_precision_t

Memory access precision.

The AMD GPU can overlap the execution of memory instructions with other instructions. This can result in a wave stopping due to a memory violation or hardware data watchpoint hit with a program counter beyond the instruction that caused the wave to stop.

Some architectures allow the hardware to be configured to always wait for memory operations to complete before continuing. This will result in the wave stopping at the instruction immediately after the one that caused the stop event. Enabling this mode can make execution of waves significantly slower.

The AMD_DBGAPI_PROCESS_INFO_PRECISE_MEMORY_SUPPORTED query can be used to determine if the architectures of all the agents of a process support controlling precise memory accesses.

Enumerator
AMD_DBGAPI_MEMORY_PRECISION_NONE | Memory instructions execute normally and a wave does not wait for the memory access to complete.
AMD_DBGAPI_MEMORY_PRECISION_PRECISE | A wave waits for memory instructions to complete before executing further instructions. This can cause a wave to execute significantly slower.

## ◆ amd_dbgapi_segment_address_dependency_t

enum amd_dbgapi_segment_address_dependency_t

The dependency when reading or writing a specific segment address of an address space using the amd_dbgapi_read_memory and amd_dbgapi_write_memory operations.

Enumerator
AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_NONE | No dependence is available.
AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_LANE | Reading or writing the segment address depends on the lane.
AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_WAVE | Reading or writing the segment address depends on the wavefront.
AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_WORKGROUP | Reading or writing the segment address depends on the workgroup.
AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_AGENT | Reading or writing the segment address depends on the agent.
AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_PROCESS | Reading or writing the segment address depends on the process.

## Function Documentation

## ◆ amd_dbgapi_address_class_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_address_class_get_info | ( | amd_dbgapi_address_class_id_t | address_class_id,
|  | amd_dbgapi_address_class_info_t | query,
|  | size_t | value_size,
|  | void * | value
| ) |  |

Query information about a source language address class of an architecture.

amd_dbgapi_address_class_info_t specifies the queries supported and the type returned using the `value` argument.

Parameters

  [in] | address_class_id | The handle of the source language address class 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_ADDRESS_CLASS_ID | `address_class_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_address_dependency()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_address_dependency | ( | amd_dbgapi_address_space_id_t | address_space_id,
|  | amd_dbgapi_segment_address_t | segment_address,
|  | amd_dbgapi_segment_address_dependency_t * | segment_address_dependency
| ) |  |

Determine the dependency of a segment address value in a particular address space.

This indicates which arguments amd_dbgapi_read_memory and amd_dbgapi_write_memory require when reading and writing memory when given a specific segment address in an address space.

Parameters

  [in] | address_space_id | The address space of the `segment_address`.
  [in] | segment_address | The integral value of the segment address. Only the bits corresponding to the address size for the `address_space_id` requested are used. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.
  [out] | segment_address_dependency | The dependency of the `segment_address` value in `address_space_id`. Will be a value of amd_dbgapi_segment_address_dependency_t other than AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_NONE.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in `segment_address_dependencies`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized and `segment_address_dependencies` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized and `destination_segment_address` and `segment_address_dependencies` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID | `address_space_id` is invalid. `segment_address_dependencies` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `segment_address_dependencies` is NULL. `segment_address_dependencies` is unaltered.

## ◆ amd_dbgapi_address_is_in_address_class()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_address_is_in_address_class | ( | amd_dbgapi_wave_id_t | wave_id,
|  | amd_dbgapi_lane_id_t | lane_id,
|  | amd_dbgapi_address_space_id_t | address_space_id,
|  | amd_dbgapi_segment_address_t | segment_address,
|  | amd_dbgapi_address_class_id_t | address_class_id,
|  | amd_dbgapi_address_class_state_t * | address_class_state
| ) |  |

Determine if a segment address in an address space is a member of a source language address class.

The address space and source language address class must both belong to the same architecture.

The address space, source language address class, and wave must all belong to the same architecture.

Parameters

  [in] | wave_id | The wave that is using the address. If the `address_space` is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL then `wave_id` may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which case `process_id` is used.
  [in] | lane_id | The lane of the `wave_id` that is using the address. If the `address_space` does not depend on the active lane then this may be AMD_DBGAPI_LANE_NONE. For example, the AMD_DBGAPI_ADDRESS_SPACE_GLOBAL address space does not depend on the lane.
  [in] | address_space_id | The address space of the `segment_address`. If the address space is dependent on: the active lane then the `lane_id` with in the `wave_id` is used; the active workgroup then the workgroup of `wave_id` is used; or the active wave then the `wave_id` is used.
  [in] | segment_address | The integral value of the segment address. Only the bits corresponding to the address size for the `address_space` requested are used. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.
  [in] | address_class_id | The handle of the source language address class.
  [out] | address_class_state | AMD_DBGAPI_ADDRESS_CLASS_STATE_NOT_MEMBER if the address is not in the address class. AMD_DBGAPI_ADDRESS_CLASS_STATE_MEMBER if the address is in the address class.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in `address_class_state`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized and `address_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized and `address_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID | `wave_id` is invalid, or `wave_id` is AMD_DBGAPI_WAVE_NONE and `address_space` is not AMD_DBGAPI_ADDRESS_SPACE_GLOBAL. `address_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_ID | `wave_id` is AMD_DBGAPI_WAVE_NONE and `lane_id` is not AMD_DBGAPI_LANE_NONE. `wave_id` is not AMD_DBGAPI_WAVE_NONE and `lane_id` is not AMD_DBGAPI_LANE_NONE and is not valid for `wave_id`. `lane_id` is AMD_DBGAPI_LANE_NONE and `address_space_id` depends on the active lane. `address_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID | `address_space_id` is invalid. `address_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_CLASS_ID | `address_class_id` is invalid. `address_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `address_class_state` is NULL. `address_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | The architectures of `wave_id`, `address_space_id`, and `address_class_id` are not the same. `address_class_state` is unaltered.

## ◆ amd_dbgapi_address_space_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_address_space_get_info | ( | amd_dbgapi_address_space_id_t | address_space_id,
|  | amd_dbgapi_address_space_info_t | query,
|  | size_t | value_size,
|  | void * | value
| ) |  |

Query information about an address space.

amd_dbgapi_address_space_info_t specifies the queries supported and the type returned using the `value` argument.

Parameters

  [in] | address_space_id | The address space.
  [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_ADDRESS_SPACE_ID | `address_space_id` is invalid. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `query` is invalid or `value` is NULL. `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_architecture_address_class_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_architecture_address_class_list | ( | amd_dbgapi_architecture_id_t | architecture_id,
|  | size_t * | address_class_count,
|  | amd_dbgapi_address_class_id_t ** | address_classes
| ) |  |

Report the list of source language address classes supported by the architecture.

The order of the source language address class handles in the list is stable between calls.

Parameters

  [in] | architecture_id | The architecture being queried.
  [out] | address_class_count | The number of architecture source language address classes.
  [out] | address_classes | A pointer to an array of amd_dbgapi_address_class_id_t with `address_class_count` elements. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in `address_class_count` and `address_classes`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized; and `address_class_count` and `address_classes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized; and `address_class_count` and `address_classes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID | `architecture_id` is invalid. `address_class_count` and `address_classes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `address_class_count` or `address_classes` are NULL. `address_class_count` and `address_classes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK | This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate `address_classes` returns NULL. `address_class_count` and `address_classes` are unaltered.

## ◆ amd_dbgapi_architecture_address_space_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_architecture_address_space_list | ( | amd_dbgapi_architecture_id_t | architecture_id,
|  | size_t * | address_space_count,
|  | amd_dbgapi_address_space_id_t ** | address_spaces
| ) |  |

Report the list of address spaces supported by the architecture.

The order of the address space handles in the list is stable between calls.

Parameters

  [in] | architecture_id | The architecture being queried.
  [out] | address_space_count | The number of architecture address spaces.
  [out] | address_spaces | A pointer to an array of amd_dbgapi_address_space_id_t with `address_space_count` elements. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in `address_space_count` and `address_spaces`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized; and `address_space_count` and `address_spaces` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized; and `address_space_count` and `address_spaces` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID | `architecture_id` is invalid. `address_space_count` and `address_spaces` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `address_space_count` and `address_spaces` are NULL. `address_space_count` and `address_spaces` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK | This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate `address_spaces` returns NULL. `address_space_count` and `address_spaces` are unaltered.

## ◆ amd_dbgapi_convert_address_space()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_convert_address_space | ( | amd_dbgapi_wave_id_t | wave_id,
|  | amd_dbgapi_lane_id_t | lane_id,
|  | amd_dbgapi_address_space_id_t | source_address_space_id,
|  | amd_dbgapi_segment_address_t | source_segment_address,
|  | amd_dbgapi_address_space_id_t | destination_address_space_id,
|  | amd_dbgapi_segment_address_t * | destination_segment_address,
|  | amd_dbgapi_size_t * | destination_contiguous_bytes
| ) |  |

Convert a source segment address in the source address space into a destination segment address in the destination address space.

If the source segment address is the NULL value in the source address space then it is converted to the NULL value in the destination address space. The NULL address is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_NULL_ADDRESS query.

An error is returned if the source segment address has no corresponding segment address in the destination address space.

The source and destination address spaces do not have to have the same linear ordering. For example, for AMD GPU the `private_swizzled` address space is implemented as `global` address space memory that interleaves the dwords of the wave's lanes. So converting a `private_swizzled` address to a `global` address will result in the corresponding scratch backing memory address. The `destination_contiguous_bytes` will indicate how many bytes, starting at the `destination_segment_address`, before the scratch backing memory corresponds to a dword of the adjacent lane. To get the scratch backing memory address of the byte after `destination_contiguous_bytes` bytes requires amd_dbgapi_convert_address_space to be called again with the address `source_segment_address` plus `destination_contiguous_bytes`.

A client can use this operation to help manage caching the bytes of different address spaces. An address in an address space that is being accessed can attempt to be converted to the various address spaces being cached to see if it aliases with bytes being cached under a different address space. For example, an address in the AMD GPU `generic` address space may alias with an address in the `global`, `private_swizzled`, or `local` address spaces.

Parameters

  [in] | wave_id | The wave that is using the address. If the `address_space` is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL then `wave_id` may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which case `process_id` is used.
  [in] | lane_id | The lane of the `wave_id` that is using the address. If the `address_space` does not depend on the active lane then this may be AMD_DBGAPI_LANE_NONE. For example, the AMD_DBGAPI_ADDRESS_SPACE_GLOBAL address space does not depend on the lane.
  [in] | source_address_space_id | The address space of the `source_segment_address`.
  [in] | source_segment_address | The integral value of the source segment address. Only the bits corresponding to the address size for the `source_address_space_id` requested are used. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.
  [in] | destination_address_space_id | The address space to which to convert `source_segment_address` that is in `source_address_space_id`.
  [out] | destination_segment_address | The integral value of the segment address in `destination_address_space_id` that corresponds to `source_segment_address` in `source_address_space_id`. The bits corresponding to the address size for the `destination_address_space_id` are updated, and any remaining bits are set to zero. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.
  [out] | destination_contiguous_bytes | The number of contiguous bytes for which the converted `destination_segment_address` continues to correspond to the `source_segment_address`.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in `destination_segment_address` and `destination_contiguous_bytes`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized and `destination_segment_address` and `destination_contiguous_bytes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized and `destination_segment_address` and `destination_contiguous_bytes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID | `wave_id` is invalid, or `wave_id` is AMD_DBGAPI_WAVE_NONE and `source_address_space_id` or `destination_address_space_id` depends on the active wave. `destination_segment_address` and `destination_contiguous_bytes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_ID | `wave_id` is AMD_DBGAPI_WAVE_NONE and `lane_id` is not AMD_DBGAPI_LANE_NONE. `wave_id` is not AMD_DBGAPI_WAVE_NONE and `lane_id` is not AMD_DBGAPI_LANE_NONE and is not valid for `wave_id`. `lane_id` is AMD_DBGAPI_LANE_NONE and `source_address_space_id` or `destination_address_space_id` depends on the active lane. `destination_segment_address` and `destination_contiguous_bytes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID | `source_address_space_id` or `destination_address_space_id` are invalid. `destination_segment_address` and `destination_contiguous_bytes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_CONVERSION | The `source_segment_address` in the `source_address_space_id` is not an address that can be represented in the `destination_address_space_id`. `destination_segment_address` and `destination_contiguous_bytes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `destination_segment_address` or `destination_contiguous_bytes` are NULL. `destination_segment_address` and `destination_contiguous_bytes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | `source_address_space_id` or `destination_address_space_id` address spaces are not supported by the architecture of `wave_id` (if not AMD_DBGAPI_WAVE_NONE). `destination_segment_address` and `destination_contiguous_bytes` are unaltered.

## ◆ amd_dbgapi_dwarf_address_class_to_address_class()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_dwarf_address_class_to_address_class | ( | amd_dbgapi_architecture_id_t | architecture_id,
|  | uint64_t | dwarf_address_class,
|  | amd_dbgapi_address_class_id_t * | address_class_id
| ) |  |

Return the architecture source language address class from a DWARF address class number for an architecture.

The AMD GPU DWARF address class number must be valid for the architecture.

See [User Guide for AMDGPU Backend - Code Object - DWARF - Address Class Mapping] (https://llvm.org/docs/AMDGPUUsage.html#address-class-mapping).

Parameters

  [in] | architecture_id | The architecture of the source language address class.
  [in] | dwarf_address_class | The DWARF source language address class.
  [out] | address_class_id | The source language address class that corresponds to the DWARF address class for the architecture.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in `address_class_id`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized and `address_class_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized and `address_class_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID | `architecture_id` is invalid. `address_class_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `address_class_id` is NULL. `address_class_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | `dwarf_address_class` is not valid for the `architecture_id`. `address_class_id` is unaltered.

## ◆ amd_dbgapi_dwarf_address_space_to_address_space()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_dwarf_address_space_to_address_space | ( | amd_dbgapi_architecture_id_t | architecture_id,
|  | uint64_t | dwarf_address_space,
|  | amd_dbgapi_address_space_id_t * | address_space_id
| ) |  |

Return the address space from an AMD GPU DWARF address space number for an architecture.

A DWARF address space describes the architecture specific address spaces. It is used in DWARF location expressions that calculate addresses. See [User Guide for AMDGPU Backend - Code Object - DWARF - Address Space Mapping] (https://llvm.org/docs/AMDGPUUsage.html#address-space-mapping).

The AMD GPU DWARF address space number must be valid for the architecture.

Parameters

  [in] | architecture_id | The architecture of the address space.
  [in] | dwarf_address_space | The AMD GPU DWARF address space.
  [out] | address_space_id | The address space that corresponds to the DWARF address space for the architecture `architecture_id`.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in `address_space_id`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized and `address_space_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized and `address_space_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID | `architecture_id` is invalid. `address_space_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `address_space_id` is NULL. `address_space_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | `dwarf_address_space` is not valid for `architecture_id`. `address_class_id` is unaltered.

## ◆ amd_dbgapi_read_memory()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_read_memory | ( | amd_dbgapi_process_id_t | process_id,
|  | amd_dbgapi_wave_id_t | wave_id,
|  | amd_dbgapi_lane_id_t | lane_id,
|  | amd_dbgapi_address_space_id_t | address_space_id,
|  | amd_dbgapi_segment_address_t | segment_address,
|  | amd_dbgapi_size_t * | value_size,
|  | void * | value
| ) |  |

Read memory.

The memory bytes in `address_space` are read for `lane_id` of `wave_id` starting at `segment_address` sequentially into `value` until `value_size` bytes have been read or an invalid memory address is reached. `value_size` is set to the number of bytes read successfully.

If `wave_id` is not AMD_DBGAPI_WAVE_NONE then it must be stopped, must belong to `process_id`, and its architecture must be the same as that of the address space.

The library performs all necessary hardware cache management so that the memory values read are coherent with the `wave_id` if not AMD_DBGAPI_WAVE_NONE. In order for the memory values read to be coherent with other waves, the waves must be stopped when invoking this operation. Stopping wave creation, stopping all waves, performing this operation, resuming any stopped waves, and then allowing wave creation can achieve this requirement. This requirement also applies if memory is read by other operating system supported means.

Parameters

  [in] | process_id | The process to read memory from if `wave_id` is AMD_DBGAPI_WAVE_NONE the `address_space` is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL.
  [in] | wave_id | The wave that is accessing the memory. If the `address_space` is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL then `wave_id` may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which case `process_id` is used.
  [in] | lane_id | The lane of `wave_id` that is accessing the memory. If the `address_space` does not depend on the active lane then this may be AMD_DBGAPI_LANE_NONE. For example, the AMD_DBGAPI_ADDRESS_SPACE_GLOBAL address space does not depend on the lane.
  [in] | address_space_id | The address space of the `segment_address`. If the address space is dependent on: the active lane then the `lane_id` with in the `wave_id` is used; the active workgroup then the workgroup of `wave_id` is used; or the active wave then the `wave_id` is used.
  [in] | segment_address | The integral value of the segment address. Only the bits corresponding to the address size for the `address_space` requested are used. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.
  [in,out] | value_size | Pass in the number of bytes to read from memory. Return the number of bytes successfully read from memory.
  [out] | value | Pointer to memory where the result is stored. Must be an array of at least input `value_size` bytes.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | Either the input `value_size` was 0, or the input `value_size` was greater than 0 and one or more bytes have been read successfully. The output `value_size` is set to the number of bytes successfully read, which will be 0 if the input `value_size` was 0. The first output `value_size` bytes of `value` are set to the bytes successfully read, all other bytes in `value` are unaltered.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized; and `value_size` and `value` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized; and `value_size` and `value` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | `process_id` is invalid. `value_size` and `value` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID | `wave_id` is invalid, or `wave_id` is AMD_DBGAPI_WAVE_NONE and `address_space` is not AMD_DBGAPI_ADDRESS_SPACE_GLOBAL. `value_size` and `value` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_ID | `wave_id` is AMD_DBGAPI_WAVE_NONE and `lane_id` is not AMD_DBGAPI_LANE_NONE. `wave_id` is not AMD_DBGAPI_WAVE_NONE and `lane_id` is not AMD_DBGAPI_LANE_NONE and is not valid for `wave_id`. `lane_id` is AMD_DBGAPI_LANE_NONE and `address_space_id` depends on the active lane. `value_size` and `value` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID | `address_space_id` is invalid. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED | `wave_id` is not stopped. `value_size` and `value` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `value` or `value_size` are NULL. `value_size` and `value` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | `wave_id` in not AMD_DBGAPI_WAVE_NONE and does not belong to `process_id` or have the same the architecture as `address_space_id`. `value_size` and `value` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_MEMORY_ACCESS | The input `value_size` was greater than 0 and no bytes were successfully read. The output `value_size` is set to 0. `value` is unaltered.

## ◆ amd_dbgapi_set_alu_exceptions_precision()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_set_alu_exceptions_precision | ( | amd_dbgapi_process_id_t | process_id,
|  | amd_dbgapi_alu_exceptions_precision_t | alu_exceptions_precision
| ) |  |

Control precision of ALU exceptions reporting.

A process can set AMD_DBGAPI_ALU_EXCEPTIONS_PRECISION_NONE to disable precise ALU exception reporting. Use the AMD_DBGAPI_PROCESS_INFO_PRECISE_ALU_EXCEPTIONS_SUPPORTED query to determine if the architecture of all agents of the process support another ALU precision mode.

The ALU exceptions precision is set independently for each process, and only affects the waves executing on the agents of that process. The setting may be changed at any time, including when waves are executing, and takes effect immediately.

Parameters

  [in] | process_id | The process being configured.
  [in] | alu_exceptions_precision | The ALU exception precision mode to set.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the agents of the process have been configured.
  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 configuration is changed.
  AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | `process_id` is invalid. No configuration is changed.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `alu_exceptions_precision` is an invalid value. No configuration is changed.
  AMD_DBGAPI_STATUS_ERROR_NOT_SUPPORTED | The requested `alu_exceptions_precision` is not supported by the architecture of all the agents of `process_id`. No configuration is changed.

## ◆ amd_dbgapi_set_memory_precision()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_set_memory_precision | ( | amd_dbgapi_process_id_t | process_id,
|  | amd_dbgapi_memory_precision_t | memory_precision
| ) |  |

Control precision of memory access reporting.

A process can be set to AMD_DBGAPI_MEMORY_PRECISION_NONE to disable precise memory reporting. Use the AMD_DBGAPI_PROCESS_INFO_PRECISE_MEMORY_SUPPORTED query to determine if the architectures of all the agents of a process support another memory precision.

The memory precision is set independently for each process, and only affects the waves executing on the agents of that process. The setting may be changed at any time, including when waves are executing, and takes effect immediately.

Parameters

  [in] | process_id | The process being configured.
  [in] | memory_precision | The memory precision to set.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the agents of the process have been configured.
  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 configuration is changed.
  AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | `process_id` is invalid. No configuration is changed.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `memory_precision` is an invalid value. No configuration is changed.
  AMD_DBGAPI_STATUS_ERROR_NOT_SUPPORTED | The requested `memory_precision` is not supported by the architecture of all the agents of `process_id`. No configuration is changed.

## ◆ amd_dbgapi_write_memory()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_write_memory | ( | amd_dbgapi_process_id_t | process_id,
|  | amd_dbgapi_wave_id_t | wave_id,
|  | amd_dbgapi_lane_id_t | lane_id,
|  | amd_dbgapi_address_space_id_t | address_space_id,
|  | amd_dbgapi_segment_address_t | segment_address,
|  | amd_dbgapi_size_t * | value_size,
|  | const void * | value
| ) |  |

Write memory.

The memory bytes in `address_space` are written for `lane_id` of `wave_id` starting at `segment_address` sequentially from `value` until `value_size` bytes have been written or an invalid memory address is reached. `value_size` is set to the number of bytes written successfully.

If `wave_id` is not AMD_DBGAPI_WAVE_NONE then it must be stopped, must belong to `process_id`, and its architecture must be the same as that of the address space.

The library performs all necessary hardware cache management so that the memory values written are coherent with the `wave_id` if not AMD_DBGAPI_WAVE_NONE. In order for the memory values written to be coherent with other waves, the waves must be stopped when invoking this operation. Stopping wave creation, stopping all waves, performing this operation, resuming any stopped waves, and then allowing wave creation can achieve this requirement. This requirement also applies if memory is written by other operating system supported means.

Parameters

  [in] | process_id | The process to write memory to if `wave_id` is AMD_DBGAPI_WAVE_NONE the `address_space` is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL.
  [in] | wave_id | The wave that is accessing the memory. If the `address_space` is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL then `wave_id` may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which case `process_id` is used.
  [in] | lane_id | The lane of `wave_id` that is accessing the memory. If the `address_space` does not depend on the active lane then this may be AMD_DBGAPI_LANE_NONE. For example, the AMD_DBGAPI_ADDRESS_SPACE_GLOBAL address space does not depend on the lane.
  [in] | address_space_id | The address space of the `segment_address`. If the address space is dependent on: the active lane then the `lane_id` with in the `wave_id` is used; the active workgroup then the workgroup of `wave_id` is used; or the active wave then the `wave_id` is used.
  [in] | segment_address | The integral value of the segment address. Only the bits corresponding to the address size for the `address_space` requested are used. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.
  [in,out] | value_size | Pass in the number of bytes to write to memory. Return the number of bytes successfully written to memory.
  [in] | value | The bytes to write to memory. Must point to an array of at least input `value_size` bytes.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | Either the input `value_size` was 0, or the input `value_size` was greater than 0 and one or more bytes have been written successfully. The output `value_size` is set to the number of bytes successfully written, which will be 0 if the input `value_size` was 0. The first output `value_size` bytes of memory starting at `segment_address` are updated, all other memory is unaltered.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized; and the memory and `value_size` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized; the memory and `value_size` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | `process_id` is invalid. The memory and `value_size` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID | `wave_id` is invalid, or `wave_id` is AMD_DBGAPI_WAVE_NONE and `address_space` is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL. The memory and `value_size` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_ID | `wave_id` is AMD_DBGAPI_WAVE_NONE and `lane_id` is not AMD_DBGAPI_LANE_NONE. `wave_id` is not AMD_DBGAPI_WAVE_NONE and `lane_id` is not AMD_DBGAPI_LANE_NONE and is not valid for `wave_id`. `lane_id` is AMD_DBGAPI_LANE_NONE and `address_space_id` depends on the active lane. The memory and `value_size` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID | `address_space_id` is invalid. The memory and `value_size` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED | `wave_id` is not stopped. The memory and `value_size` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `value` or `value_size` are NULL. The memory and `value_size` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | `wave_id` in not AMD_DBGAPI_WAVE_NONE and does not belong to `process_id` or have the same the architecture as `address_space_id`. The memory and `value_size` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_MEMORY_ACCESS | The input `value_size` was greater than 0 and no bytes were successfully written. The output `value_size` is set to 0. The memory and `value_size` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_PROCESS_FROZEN | This operation is not permitted because the process is frozen. The memory and `value_size` are unaltered.