Ctrl+K
This page contains changes for a test release of ROCm. Read the latest Linux release of ROCm documentation for your production environments.

Registers

Registers#

AMD DBG API: Registers
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_70
 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_76
 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.

If the requested register has no associated DWARF register number, then amd_dbgapi_register_get_info returns the AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE error.

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_idThe handle of the register class being queried.
[in]queryThe query being requested.
[in]value_sizeSize of the memory pointed to by value. Must be equal to the byte size of the query result.
[out]valuePointer to memory where the query result is stored.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in value.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_CLASS_IDregister_class_id is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTvalue is NULL or query is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYvalue_size does not match the size of the query result. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis 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_idThe architecture being queried.
[out]register_class_countThe number of architecture register classes.
[out]register_classesA 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_SUCCESSThe function has been executed successfully and the result is stored in register_class_count and register_classes.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and register_class_count and register_classes are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and register_class_count and register_classes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_IDarchitecture_id is invalid. register_class_count and register_classes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTregister_class_count or register_classes are NULL. register_class_count and register_classes are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis 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_idThe architecture being queried.
[out]register_countThe number of architecture registers.
[out]registersA 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_SUCCESSThe function has been executed successfully and the result is stored in register_count and registers.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and register_count and registers are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and register_count and registers are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_IDarchitecture_id is invalid. register_count and registers are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTregister_count or registers are NULL. register_count and registers are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis 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_idThe architecture of the DWARF register.
[in]dwarf_registerThe AMD GPU DWARF register number.
[out]register_idThe register handle that corresponds to the DWARF register ID.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in register_id.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and register_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and register_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_IDarchitecture_id is invalid. register_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTregister_id is NULL. register_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYdwarf_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_idThe wave being queried for the register.
[in]register_idThe first register being requested.
[in]register_countThe number of registers being requested.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully. Registers may be prefetched.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_IDwave_id is invalid. No registers are prefetched.
AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_IDregister_id is invalid. No registers are prefetched.
AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPEDwave_id is not stopped. No registers are prefetched.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYThe architectures of wave_id and register_id are not the same. No registers are prefetched.
AMD_DBGAPI_STATUS_ERROR_REGISTER_NOT_AVAILABLEregister_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_idThe wave to being queried for the register.
[in]register_idThe register being requested.
[in]offsetThe first byte to start reading the register. The offset is zero based starting from the least significant byte of the register.
[in]value_sizeThe 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]valueThe bytes read from the register. Must point to an array of at least value_size bytes.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe 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_FATALA fatal error occurred. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_IDwave_id is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_IDregister_id is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPEDwave_id is not stopped. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTvalue is NULL or value_size is 0. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYvalue_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_AVAILABLEregister_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_idThe handle of the register being queried.
[in]queryThe query being requested.
[in]value_sizeSize of the memory pointed to by value. Must be equal to the byte size of the query result.
[out]valuePointer to memory where the query result is stored.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in value.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_IDregister_id is invalid for architecture_id. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTvalue is NULL, or query is invalid or not supported for an architecture. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYvalue_size does not match the size of the query result. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLEThe requested information is not available. See amd_dbgapi_register_info_t for queries that can produce this error. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis 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_idThe handle of the register class being queried.
[in]register_idThe handle of the register being queried.
[out]register_class_stateAMD_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_SUCCESSThe function has been executed successfully and the result is stored in register_class_state.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and register_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and register_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_IDregister_id is invalid. register_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_CLASS_IDregister_class_id is invalid. register_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTregister_class_state is NULL. register_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYThe 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_idThe wave being queried.
[in]register_idThe register being queried.
[out]existsIndication of whether wave_id has register_id.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in exists.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and exists is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and exists is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_IDwave_id is invalid. exists is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_IDregister_id is invalid. exists is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTexists is NULL. exists is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYThe 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_idThe wave being queried.
[out]register_countThe number of wave registers.
[out]registersA 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_SUCCESSThe function has been executed successfully and the result is stored in register_count and registers.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and register_count and registers are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and register_count and registers are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_IDwave_id is invalid. register_count and registers are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTregister_count or registers are NULL. register_count and registers are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis 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_idThe wave to being queried for the register.
[in]register_idThe register being requested.
[in]offsetThe first byte to start writing the register. The offset is zero based starting from the least significant byte of the register.
[in]value_sizeThe 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]valueThe bytes to write to the register. Must point to an array of at least value_size bytes.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and value_size bytes have been written to the contents of the register starting at offset.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and the register is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized. The register is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_IDwave_id is invalid. The register is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_IDregister_id is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPEDwave_id is not stopped. The register is unaltered.
AMD_DBGAPI_STATUS_ERROR_DISPLACED_STEPPING_ACTIVEwave_id has an active displaced stepping buffer.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTvalue is NULL or value_size is 0. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYvalue_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_AVAILABLEregister_id is not allocated for wave_id. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_PROCESS_FROZENthe process the wave belongs to is frozen. value is unaltered.