AMD_DBGAPI: Registers

AMD_DBGAPI 0.64.0

Data Structures | Macros | Enumerations | Functions
Registers

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

## Data Structures
struct | amd_dbgapi_register_class_id_t
| Opaque register class handle. More...
struct | amd_dbgapi_register_id_t
| Opaque register handle. More...
struct | amd_dbgapi_direct_call_register_pair_information_t
| Instruction information for direct call instructions. More...

## Macros
#define | AMD_DBGAPI_REGISTER_CLASS_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_register_class_id_t, 0)
| The NULL register class handle. More...
#define | AMD_DBGAPI_REGISTER_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_register_id_t, 0)
| The NULL register handle. More...

## Enumerations
enum | amd_dbgapi_register_class_info_t { AMD_DBGAPI_REGISTER_CLASS_INFO_ARCHITECTURE = 1, AMD_DBGAPI_REGISTER_CLASS_INFO_NAME = 2 }
| Register class queries that are supported by amd_dbgapi_architecture_register_class_get_info. More...
enum | amd_dbgapi_register_properties_t { AMD_DBGAPI_REGISTER_PROPERTY_NONE = 0, AMD_DBGAPI_REGISTER_PROPERTY_READONLY_BITS = (1 << 0), AMD_DBGAPI_REGISTER_PROPERTY_VOLATILE = (1 << 1), AMD_DBGAPI_REGISTER_PROPERTY_INVALIDATE_VOLATILE = (1 << 2) }
| A bit mask on register properties. More...
enum | amd_dbgapi_register_info_t { AMD_DBGAPI_REGISTER_INFO_ARCHITECTURE = 1, AMD_DBGAPI_REGISTER_INFO_NAME = 2, AMD_DBGAPI_REGISTER_INFO_SIZE = 3, AMD_DBGAPI_REGISTER_INFO_TYPE = 4, AMD_DBGAPI_REGISTER_INFO_DWARF = 5, AMD_DBGAPI_REGISTER_INFO_PROPERTIES = 6 }
| Register queries that are supported by amd_dbgapi_register_get_info. More...
enum | amd_dbgapi_register_exists_t { AMD_DBGAPI_REGISTER_ABSENT = 0, AMD_DBGAPI_REGISTER_PRESENT = 1 }
| Indication of if a wave has a register. More...
enum | amd_dbgapi_register_class_state_t { AMD_DBGAPI_REGISTER_CLASS_STATE_NOT_MEMBER = 0, AMD_DBGAPI_REGISTER_CLASS_STATE_MEMBER = 1 }
| Indication of whether a register is a member of a register class. More...

## Functions
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_architecture_register_class_get_info (amd_dbgapi_register_class_id_t register_class_id, amd_dbgapi_register_class_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_54
| Query information about a register class of an architecture. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_architecture_register_class_list (amd_dbgapi_architecture_id_t architecture_id, size_t *register_class_count, amd_dbgapi_register_class_id_t **register_classes) AMD_DBGAPI_VERSION_0_54
| Report the list of register classes supported by the architecture. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_register_get_info (amd_dbgapi_register_id_t register_id, amd_dbgapi_register_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_58
| Query information about a register. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_wave_register_exists (amd_dbgapi_wave_id_t wave_id, amd_dbgapi_register_id_t register_id, amd_dbgapi_register_exists_t *exists) AMD_DBGAPI_VERSION_0_54
| Query if a register exists for a wave. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_architecture_register_list (amd_dbgapi_architecture_id_t architecture_id, size_t *register_count, amd_dbgapi_register_id_t **registers) AMD_DBGAPI_VERSION_0_54
| Report the list of registers supported by the architecture. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_wave_register_list (amd_dbgapi_wave_id_t wave_id, size_t *register_count, amd_dbgapi_register_id_t **registers) AMD_DBGAPI_VERSION_0_54
| Report the list of registers supported by a wave. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_dwarf_register_to_register (amd_dbgapi_architecture_id_t architecture_id, uint64_t dwarf_register, amd_dbgapi_register_id_t *register_id) AMD_DBGAPI_VERSION_0_54
| Return a register handle from an AMD GPU DWARF register number for an architecture. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_register_is_in_register_class (amd_dbgapi_register_class_id_t register_class_id, amd_dbgapi_register_id_t register_id, amd_dbgapi_register_class_state_t *register_class_state) AMD_DBGAPI_VERSION_0_54
| Determine if a register is a member of a register class. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_read_register (amd_dbgapi_wave_id_t wave_id, amd_dbgapi_register_id_t register_id, amd_dbgapi_size_t offset, amd_dbgapi_size_t value_size, void *value) AMD_DBGAPI_VERSION_0_62
| Read a register. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_write_register (amd_dbgapi_wave_id_t wave_id, amd_dbgapi_register_id_t register_id, amd_dbgapi_size_t offset, amd_dbgapi_size_t value_size, const void *value) AMD_DBGAPI_VERSION_0_62
| Write a register. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_prefetch_register (amd_dbgapi_wave_id_t wave_id, amd_dbgapi_register_id_t register_id, amd_dbgapi_size_t register_count) AMD_DBGAPI_VERSION_0_62
| Prefetch register values. More...

## Detailed Description

Operations related to AMD GPU register access.

## Macro Definition Documentation

## ◆ AMD_DBGAPI_REGISTER_CLASS_NONE

#define AMD_DBGAPI_REGISTER_CLASS_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_register_class_id_t, 0)

The NULL register class handle.

## ◆ AMD_DBGAPI_REGISTER_NONE

#define AMD_DBGAPI_REGISTER_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_register_id_t, 0)

The NULL register handle.

## Enumeration Type Documentation

## ◆ amd_dbgapi_register_class_info_t

enum amd_dbgapi_register_class_info_t

Register class queries that are supported by amd_dbgapi_architecture_register_class_get_info.

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

Enumerator
AMD_DBGAPI_REGISTER_CLASS_INFO_ARCHITECTURE | Return the architecture to which this register class belongs. The type of this attribute is amd_dbgapi_architecture_id_t.
AMD_DBGAPI_REGISTER_CLASS_INFO_NAME | Return the register 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_register_class_state_t

enum amd_dbgapi_register_class_state_t

Indication of whether a register is a member of a register class.

Enumerator
AMD_DBGAPI_REGISTER_CLASS_STATE_NOT_MEMBER | The register is not a member of the register class.
AMD_DBGAPI_REGISTER_CLASS_STATE_MEMBER | The register is a member of the register class.

## ◆ amd_dbgapi_register_exists_t

enum amd_dbgapi_register_exists_t

Indication of if a wave has a register.

Enumerator
AMD_DBGAPI_REGISTER_ABSENT | The wave does not have the register.
AMD_DBGAPI_REGISTER_PRESENT | The wave has the register.

## ◆ amd_dbgapi_register_info_t

enum amd_dbgapi_register_info_t

Register queries that are supported by amd_dbgapi_register_get_info.

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

Enumerator
AMD_DBGAPI_REGISTER_INFO_ARCHITECTURE | Return the architecture to which this register belongs. The type of this attribute is amd_dbgapi_architecture_id_t.
AMD_DBGAPI_REGISTER_INFO_NAME | Return the register 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_REGISTER_INFO_SIZE | Return the size of the register in bytes. The type of this attribute is amd_dbgapi_size_t.
AMD_DBGAPI_REGISTER_INFO_TYPE | Return the register type as a C style type string. This can be used as the default type to use when displaying values of the register. The type string syntax is defined by the following BNF syntax:
    type          ::= integer_type
                    | float_type
                    | function_type
                    | flag_type
                    | array_type
    array_type    ::= ( integer_type
                      | float_type
                      | function_type
                      | flag_type
                      ) "[" element_count "]"
    element_count ::= DECIMAL_NUMBER
    integer_type  ::= "uint32_t"
                    | "uint64_t"
    float_type    ::= "float"
                    | "double"
    function_type ::= "void(void)"
    flag_type     ::= ( "flags32_t"
                      | "flags64_t"
                      )
                      type_name
                      [ "{" [ fields ] "}" ]
    fields        ::= field ";" [ fields ]
    field         ::= "bool" field_name
                      "@" bit_position
                    | ( integer_type
                      | enum_type
                      )
                      field_name
                      "@" bit_position
                      "-" bit_position
    field_name    ::= IDENTIFIER
    enum_type     ::= "enum" type_name
                      [ "{" [ enum_values ] "}" ]
    enum_values   ::= enum_value [ "," enum_values ]
    enum_value    ::= enum_name "=" enum_ordinal
    enum_name     ::= IDENTIFIER
    enum_ordinal  ::= DECIMAL_NUMBER
    type_name     ::= IDENTIFIER
    bit_position  ::= DECIMAL_NUMBER
`IDENTIFIER` is string starting with an alphabetic character followed by zero or more alphabetic, numeric, "_", or "." characters. `DECIMAL_NUMBER` is a decimal C integral literal. Whitespace is allowed between lexical tokens. The type size matches the size of the register. `uint32`, `float`, and `flag32` types are 4 bytes. `unit64`, `double`, and `flag64` types are 8 bytes. `void(void)` is the size of a global address. 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_REGISTER_INFO_DWARF | Return the AMD GPU DWARF register number for the register's architecture. The type of this attribute is `uint64_t`.
AMD_DBGAPI_REGISTER_INFO_PROPERTIES | Return the register's properties. The type of this attribute is `uint32_t` with values defined by amd_dbgapi_register_properties_t.

## ◆ amd_dbgapi_register_properties_t

enum amd_dbgapi_register_properties_t

A bit mask on register properties.

The properties of a register are available using the AMD_DBGAPI_REGISTER_INFO_PROPERTIES query.

Enumerator
AMD_DBGAPI_REGISTER_PROPERTY_NONE | There are no properties.
AMD_DBGAPI_REGISTER_PROPERTY_READONLY_BITS | At least one bit of the register value is readonly. It is advisable for the client to read the register after writing it to determine the value of the readonly bits.
AMD_DBGAPI_REGISTER_PROPERTY_VOLATILE | The register value may change as a consequence of changing a register of the same wavefront with the AMD_DBGAPI_REGISTER_PROPERTY_INVALIDATE_VOLATILE property. It is advisable for the client to not cache the value of the register.
AMD_DBGAPI_REGISTER_PROPERTY_INVALIDATE_VOLATILE | Changing the value of the register may change a register of the same wavefront with the AMD_DBGAPI_REGISTER_PROPERTY_VOLATILE property. It is advisable to invalidate any cached registers with the AMD_DBGAPI_REGISTER_PROPERTY_VOLATILE property.

## Function Documentation

## ◆ amd_dbgapi_architecture_register_class_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_architecture_register_class_get_info | ( | amd_dbgapi_register_class_id_t | register_class_id,
|  | amd_dbgapi_register_class_info_t | query,
|  | size_t | value_size,
|  | void * | value
| ) |  |

Query information about a register class of an architecture.

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

Parameters

  [in] | register_class_id | The handle of the register 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_REGISTER_CLASS_ID | `register_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_architecture_register_class_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_architecture_register_class_list | ( | amd_dbgapi_architecture_id_t | architecture_id,
|  | size_t * | register_class_count,
|  | amd_dbgapi_register_class_id_t ** | register_classes
| ) |  |

Report the list of register classes supported by the architecture.

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

Parameters

  [in] | architecture_id | The architecture being queried.
  [out] | register_class_count | The number of architecture register classes.
  [out] | register_classes | A pointer to an array of amd_dbgapi_register_class_id_t with `register_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 `register_class_count` and `register_classes`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized; and `register_class_count` and `register_classes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized; and `register_class_count` and `register_classes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID | `architecture_id` is invalid. `register_class_count` and `register_classes` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `register_class_count` or `register_classes` are NULL. `register_class_count` and `register_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 `register_classes` returns NULL. `register_class_count` and `register_classes` are unaltered.

## ◆ amd_dbgapi_architecture_register_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_architecture_register_list | ( | amd_dbgapi_architecture_id_t | architecture_id,
|  | size_t * | register_count,
|  | amd_dbgapi_register_id_t ** | registers
| ) |  |

Report the list of registers supported by the architecture.

This list is all the registers the architecture can support, but a specific wave may not have all these registers. For example, AMD GPU architectures can specify the number of vector and scalar registers when a wave is created. Use the amd_dbgapi_wave_register_list operation to determine the registers supported by a specific wave.

The order of the register handles in the list is stable between calls and registers on the same major class are contiguous in ascending hardware number order.

Parameters

  [in] | architecture_id | The architecture being queried.
  [out] | register_count | The number of architecture registers.
  [out] | registers | A pointer to an array of amd_dbgapi_register_id_t with `register_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 `register_count` and `registers`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized; and `register_count` and `registers` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized; and `register_count` and `registers` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID | `architecture_id` is invalid. `register_count` and `registers` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `register_count` or `registers` are NULL. `register_count` and `registers` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK | This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate `registers` returns NULL. `register_count` and `registers` are unaltered.

## ◆ amd_dbgapi_dwarf_register_to_register()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_dwarf_register_to_register | ( | amd_dbgapi_architecture_id_t | architecture_id,
|  | uint64_t | dwarf_register,
|  | amd_dbgapi_register_id_t * | register_id
| ) |  |

Return a register handle from an AMD GPU DWARF register number for an architecture.

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

See User Guide for AMDGPU Backend - Code Object - DWARF - Register Identifier.

Parameters

  [in] | architecture_id | The architecture of the DWARF register.
  [in] | dwarf_register | The AMD GPU DWARF register number.
  [out] | register_id | The register handle that corresponds to the DWARF register ID.

Return values

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

## ◆ amd_dbgapi_prefetch_register()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_prefetch_register | ( | amd_dbgapi_wave_id_t | wave_id,
|  | amd_dbgapi_register_id_t | register_id,
|  | amd_dbgapi_size_t | register_count
| ) |  |

Prefetch register values.

A hint to indicate that a range of registers may be read using amd_dbgapi_read_register in the future. This can improve the performance of reading registers as the library may be able to batch the prefetch requests into one request.

The wave must be stopped. The register and wave must both belong to the same architecture, and the wave must have allocated that register.

If the wave is resumed, then any prefetch requests for registers that were not subsequently read may be discarded and so provide no performance benefit. Prefetch requests for registers that are never subsequently read may in fact reduce performance.

The registers to prefetch are specified as the first register and the number of registers. The first register can be any register supported by the wave. The number of registers is in terms of the wave register order returned by amd_dbgapi_wave_register_list. If the number exceeds the number of wave registers, then only up to the last wave register is prefetched.

Parameters

  [in] | wave_id | The wave being queried for the register.
  [in] | register_id | The first register being requested.
  [in] | register_count | The number of registers being requested.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully. Registers may be prefetched.
  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_WAVE_ID | `wave_id` is invalid. No registers are prefetched.
  AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_ID | `register_id` is invalid. No registers are prefetched.
  AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED | `wave_id` is not stopped. No registers are prefetched.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | The architectures of `wave_id` and `register_id` are not the same. No registers are prefetched.
  AMD_DBGAPI_STATUS_ERROR_REGISTER_NOT_AVAILABLE | `register_id` is not allocated for `wave_id`. No registers are prefetched.

## ◆ amd_dbgapi_read_register()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_read_register | ( | amd_dbgapi_wave_id_t | wave_id,
|  | amd_dbgapi_register_id_t | register_id,
|  | amd_dbgapi_size_t | offset,
|  | amd_dbgapi_size_t | value_size,
|  | void * | value
| ) |  |

Read a register.

`value_size` bytes are read from the register starting at `offset` into `value`.

The wave must be stopped. The register and wave must both belong to the same architecture, and the wave must have allocated that register.

The register size can be obtained using amd_dbgapi_register_get_info with the AMD_DBGAPI_REGISTER_INFO_SIZE query.

Parameters

  [in] | wave_id | The wave to being queried for the register.
  [in] | register_id | The register being requested.
  [in] | offset | The first byte to start reading the register. The offset is zero based starting from the least significant byte of the register.
  [in] | value_size | The number of bytes to read from the register which must be greater than 0 and less than the size of the register minus `offset`.
  [out] | value | The bytes read from the register. Must point to an array of at least `value_size` bytes.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and `value` is set to `value_size` bytes starting at `offset` from the contents of the register.
  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_WAVE_ID | `wave_id` is invalid. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_ID | `register_id` is invalid. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED | `wave_id` is not stopped. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `value` is NULL or `value_size` is 0. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | `value_size` is greater than the size of the `register_id` minus `offset` or the architectures of `wave_id` and `register_id` are not the same. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_REGISTER_NOT_AVAILABLE | `register_id` is not allocated for `wave_id`. `value` is unaltered.

## ◆ amd_dbgapi_register_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_register_get_info | ( | amd_dbgapi_register_id_t | register_id,
|  | amd_dbgapi_register_info_t | query,
|  | size_t | value_size,
|  | void * | value
| ) |  |

Query information about a register.

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

Parameters

  [in] | register_id | The handle of the register 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_REGISTER_ID | `register_id` is invalid for `architecture_id`. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `value` is NULL, or `query` is invalid or not supported for an architecture. `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_register_is_in_register_class()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_register_is_in_register_class | ( | amd_dbgapi_register_class_id_t | register_class_id,
|  | amd_dbgapi_register_id_t | register_id,
|  | amd_dbgapi_register_class_state_t * | register_class_state
| ) |  |

Determine if a register is a member of a register class.

The register and register class must both belong to the same architecture.

Parameters

  [in] | register_class_id | The handle of the register class being queried.
  [in] | register_id | The handle of the register being queried.
  [out] | register_class_state | AMD_DBGAPI_REGISTER_CLASS_STATE_NOT_MEMBER if the register is not in the register class. AMD_DBGAPI_REGISTER_CLASS_STATE_MEMBER if the register is in the register class.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in `register_class_state`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized and `register_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized and `register_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_ID | `register_id` is invalid. `register_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_CLASS_ID | `register_class_id` is invalid. `register_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `register_class_state` is NULL. `register_class_state` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | The architectures of `register_class_id` and `register_id` are not the same. `register_class_state` is unaltered.

## ◆ amd_dbgapi_wave_register_exists()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_wave_register_exists | ( | amd_dbgapi_wave_id_t | wave_id,
|  | amd_dbgapi_register_id_t | register_id,
|  | amd_dbgapi_register_exists_t * | exists
| ) |  |

Query if a register exists for a wave.

The register and wave must both belong to the same architecture.

Parameters

  [in] | wave_id | The wave being queried.
  [in] | register_id | The register being queried.
  [out] | exists | Indication of whether `wave_id` has `register_id`.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in `exists`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized and `exists` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized and `exists` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID | `wave_id` is invalid. `exists` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_ID | `register_id` is invalid. `exists` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `exists` is NULL. `exists` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | The architectures of `wave_id` and `register_id` are not the same. `exists` is unaltered.

## ◆ amd_dbgapi_wave_register_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_wave_register_list | ( | amd_dbgapi_wave_id_t | wave_id,
|  | size_t * | register_count,
|  | amd_dbgapi_register_id_t ** | registers
| ) |  |

Report the list of registers supported by a wave.

This list is the registers allocated for a specific wave and may not be all the registers supported by the architecture. For example, AMD GPU architectures can specify the number of vector and scalar registers when a wave is created. Use the amd_dbgapi_architecture_register_list operation to determine the full set of registers supported by the architecture.

The order of the register handles in the list is stable between calls. It is equal to, or a subset of, those returned by amd_dbgapi_architecture_register_list and in the same order.

Parameters

  [in] | wave_id | The wave being queried.
  [out] | register_count | The number of wave registers.
  [out] | registers | A pointer to an array of amd_dbgapi_register_id_t with `register_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 `register_count` and `registers`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized; and `register_count` and `registers` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized; and `register_count` and `registers` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID | `wave_id` is invalid. `register_count` and `registers` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `register_count` or `registers` are NULL. `register_count` and `registers` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK | This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate `registers` returns NULL. `register_count` and `registers` are unaltered.

## ◆ amd_dbgapi_write_register()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_write_register | ( | amd_dbgapi_wave_id_t | wave_id,
|  | amd_dbgapi_register_id_t | register_id,
|  | amd_dbgapi_size_t | offset,
|  | amd_dbgapi_size_t | value_size,
|  | const void * | value
| ) |  |

Write a register.

`value_size` bytes are written into the register starting at `offset`.

The wave must be stopped. The register and wave must both belong to the same architecture, and the wave must have allocated that register. The wave must not have an active displaced stepping buffer (see amd_dbgapi_displaced_stepping_start) as the program counter and other registers may be changed as part of creating the displaced stepping buffer.

The register size can be obtained using amd_dbgapi_register_get_info with the AMD_DBGAPI_REGISTER_INFO_SIZE query.

Parameters

  [in] | wave_id | The wave to being queried for the register.
  [in] | register_id | The register being requested.
  [in] | offset | The first byte to start writing the register. The offset is zero based starting from the least significant byte of the register.
  [in] | value_size | The number of bytes to write to the register which must be greater than 0 and less than the size of the register minus `offset`.
  [in] | value | The bytes to write to the register. Must point to an array of at least `value_size` bytes.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and `value_size` bytes have been written to the contents of the register starting at `offset`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized and the register is unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized. The register is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID | `wave_id` is invalid. The register is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_ID | `register_id` is invalid. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED | `wave_id` is not stopped. The register is unaltered.
  AMD_DBGAPI_STATUS_ERROR_DISPLACED_STEPPING_ACTIVE | `wave_id` has an active displaced stepping buffer.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `value` is NULL or `value_size` is 0. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY | `value_size` is greater than the size of the `register_id` minus `offset` or the architectures of `wave_id` and `register_id` are not the same. `value` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_REGISTER_NOT_AVAILABLE | `register_id` is not allocated for `wave_id`. `value` is unaltered.