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

Architectures

Architectures#

AMD DBG API: Architectures

Operations related to AMD GPU architectures. More...

Data Structures

struct  amd_dbgapi_architecture_id_t
 Opaque architecture handle. More...
 

Macros

#define AMD_DBGAPI_ARCHITECTURE_NONE    AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_architecture_id_t, 0)
 The NULL architecture handle. More...
 

Typedefs

typedef struct amd_dbgapi_symbolizer_id_s * amd_dbgapi_symbolizer_id_t
 Opaque client symbolizer handle. More...
 

Enumerations

enum  amd_dbgapi_architecture_info_t {
  AMD_DBGAPI_ARCHITECTURE_INFO_NAME = 1 , AMD_DBGAPI_ARCHITECTURE_INFO_ELF_AMDGPU_MACHINE = 2 , AMD_DBGAPI_ARCHITECTURE_INFO_LARGEST_INSTRUCTION_SIZE = 3 , AMD_DBGAPI_ARCHITECTURE_INFO_MINIMUM_INSTRUCTION_ALIGNMENT = 4 ,
  AMD_DBGAPI_ARCHITECTURE_INFO_BREAKPOINT_INSTRUCTION_SIZE = 5 , AMD_DBGAPI_ARCHITECTURE_INFO_BREAKPOINT_INSTRUCTION = 6 , AMD_DBGAPI_ARCHITECTURE_INFO_BREAKPOINT_INSTRUCTION_PC_ADJUST = 7 , AMD_DBGAPI_ARCHITECTURE_INFO_PC_REGISTER = 8
}
 Architecture queries that are supported by amd_dbgapi_architecture_get_info. More...
 
enum  amd_dbgapi_instruction_kind_t {
  AMD_DBGAPI_INSTRUCTION_KIND_UNKNOWN = 0 , AMD_DBGAPI_INSTRUCTION_KIND_SEQUENTIAL = 1 , AMD_DBGAPI_INSTRUCTION_KIND_DIRECT_BRANCH = 2 , AMD_DBGAPI_INSTRUCTION_KIND_DIRECT_BRANCH_CONDITIONAL = 3 ,
  AMD_DBGAPI_INSTRUCTION_KIND_INDIRECT_BRANCH_REGISTER_PAIR = 4 , AMD_DBGAPI_INSTRUCTION_KIND_INDIRECT_BRANCH_CONDITIONAL_REGISTER_PAIR = 5 , AMD_DBGAPI_INSTRUCTION_KIND_DIRECT_CALL_REGISTER_PAIR = 6 , AMD_DBGAPI_INSTRUCTION_KIND_INDIRECT_CALL_REGISTER_PAIRS = 7 ,
  AMD_DBGAPI_INSTRUCTION_KIND_TERMINATE = 8 , AMD_DBGAPI_INSTRUCTION_KIND_TRAP = 9 , AMD_DBGAPI_INSTRUCTION_KIND_HALT = 10 , AMD_DBGAPI_INSTRUCTION_KIND_BARRIER = 11 ,
  AMD_DBGAPI_INSTRUCTION_KIND_SLEEP = 12 , AMD_DBGAPI_INSTRUCTION_KIND_SPECIAL = 13
}
 The kinds of instruction classifications. More...
 
enum  amd_dbgapi_instruction_properties_t { AMD_DBGAPI_INSTRUCTION_PROPERTY_NONE = 0 }
 A bit mask of the properties of an instruction. More...
 

Functions

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_architecture_get_info (amd_dbgapi_architecture_id_t architecture_id, amd_dbgapi_architecture_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_54
 Query information about an architecture. More...
 
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_get_architecture (uint32_t elf_amdgpu_machine, amd_dbgapi_architecture_id_t *architecture_id) AMD_DBGAPI_VERSION_0_54
 Get an architecture from the AMD GPU ELF EF_AMDGPU_MACH value corresponding to the architecture. More...
 
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_disassemble_instruction (amd_dbgapi_architecture_id_t architecture_id, amd_dbgapi_global_address_t address, amd_dbgapi_size_t *size, const void *memory, char **instruction_text, amd_dbgapi_symbolizer_id_t symbolizer_id, amd_dbgapi_status_t(*symbolizer)(amd_dbgapi_symbolizer_id_t symbolizer_id, amd_dbgapi_global_address_t address, char **symbol_text)) AMD_DBGAPI_VERSION_0_54
 Disassemble a single instruction. More...
 
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_classify_instruction (amd_dbgapi_architecture_id_t architecture_id, amd_dbgapi_global_address_t address, amd_dbgapi_size_t *size, const void *memory, amd_dbgapi_instruction_kind_t *instruction_kind, amd_dbgapi_instruction_properties_t *instruction_properties, void **instruction_information) AMD_DBGAPI_VERSION_0_58
 Classify a single instruction. More...
 

Detailed Description

Operations related to AMD GPU architectures.

The library supports a family of AMD GPU devices. Each device has its own architectural properties. The operations in this section provide information about the supported architectures.

Macro Definition Documentation

◆ AMD_DBGAPI_ARCHITECTURE_NONE

#define AMD_DBGAPI_ARCHITECTURE_NONE    AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_architecture_id_t, 0)

The NULL architecture handle.

Typedef Documentation

◆ amd_dbgapi_symbolizer_id_t

typedef struct amd_dbgapi_symbolizer_id_s* amd_dbgapi_symbolizer_id_t

Opaque client symbolizer handle.

A pointer to client data associated with a symbolizer. This pointer is passed to the amd_dbgapi_disassemble_instruction symbolizer callback.

Enumeration Type Documentation

◆ amd_dbgapi_architecture_info_t

Architecture queries that are supported by amd_dbgapi_architecture_get_info.

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

Enumerator
AMD_DBGAPI_ARCHITECTURE_INFO_NAME 

Return the architecture 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_ARCHITECTURE_INFO_ELF_AMDGPU_MACHINE 

Return the AMD GPU ELF EF_AMDGPU_MACH value corresponding to the architecture.

This is defined as a bit field in the e_flags AMD GPU ELF header. See User Guide for AMDGPU Backend - Code Object - Header. The type of this attribute is uint32_t.

AMD_DBGAPI_ARCHITECTURE_INFO_LARGEST_INSTRUCTION_SIZE 

Return the largest instruction size in bytes for the architecture.

The type of this attribute is amd_dbgapi_size_t.

AMD_DBGAPI_ARCHITECTURE_INFO_MINIMUM_INSTRUCTION_ALIGNMENT 

Return the minimum instruction alignment in bytes for the architecture.

The returned value will be a power of two. The type of this attribute is amd_dbgapi_size_t.

AMD_DBGAPI_ARCHITECTURE_INFO_BREAKPOINT_INSTRUCTION_SIZE 

Return the breakpoint instruction size in bytes for the architecture.

The type of this attribute is amd_dbgapi_size_t.

AMD_DBGAPI_ARCHITECTURE_INFO_BREAKPOINT_INSTRUCTION 

Return the breakpoint instruction for the architecture.

The type of this attribute is pointer to N bytes where N is the value returned by the AMD_DBGAPI_ARCHITECTURE_INFO_BREAKPOINT_INSTRUCTION_SIZE query. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.

AMD_DBGAPI_ARCHITECTURE_INFO_BREAKPOINT_INSTRUCTION_PC_ADJUST 

Return the number of bytes to subtract from the PC after stopping due to a breakpoint instruction to get the address of the breakpoint instruction for the architecture.

The type of this attribute is amd_dbgapi_size_t.

AMD_DBGAPI_ARCHITECTURE_INFO_PC_REGISTER 

Return the register handle for the PC for the architecture.

The type of this attribute is amd_dbgapi_register_id_t.

◆ amd_dbgapi_instruction_kind_t

The kinds of instruction classifications.

Enumerator
AMD_DBGAPI_INSTRUCTION_KIND_UNKNOWN 

The instruction classification is unknown.

The instruction has no information.

AMD_DBGAPI_INSTRUCTION_KIND_SEQUENTIAL 

The instruction executes sequentially.

It performs no control flow and the next instruction executed is the following one. The instruction has no information.

AMD_DBGAPI_INSTRUCTION_KIND_DIRECT_BRANCH 

The instruction unconditionally branches to a literal address.

The instruction information is of type amd_dbgapi_global_address_t with the value of the target address of the branch.

AMD_DBGAPI_INSTRUCTION_KIND_DIRECT_BRANCH_CONDITIONAL 

The instruction conditionally branches to a literal address.

If the condition is not satisfied then the next instruction is the following one. The instruction information is of type amd_dbgapi_global_address_t with the value of the target address of the branch if taken.

AMD_DBGAPI_INSTRUCTION_KIND_INDIRECT_BRANCH_REGISTER_PAIR 

The instruction unconditionally branches to an address held in a pair of registers.

The instruction information is of type amd_dbgapi_register_id_t[2] with the value of the register IDs for the registers. The first register holds the least significant address bits, and the second register holds the most significant address bits.

AMD_DBGAPI_INSTRUCTION_KIND_INDIRECT_BRANCH_CONDITIONAL_REGISTER_PAIR 

The instruction conditionally branches to an address held in a pair of registers.

If the condition is not satisfied then the next instruction is the following one. The instruction information is of type amd_dbgapi_register_id_t[2] with the value of the register IDs for the registers holding the value of the target address of the branch if taken. The register with index 0 holds the least significant address bits, and the register with index 1 holds the most significant address bits.

AMD_DBGAPI_INSTRUCTION_KIND_DIRECT_CALL_REGISTER_PAIR 

The instruction unconditionally branches to a literal address and the address of the following instruction is saved in a pair of registers.

The instruction information is of type amd_dbgapi_direct_call_register_pair_information_t with the value of the target address of the call followed by the value of the saved return address register IDs. The saved return address register with index 0 holds the least significant address bits, and the register with index 1 holds the most significant address bits.

AMD_DBGAPI_INSTRUCTION_KIND_INDIRECT_CALL_REGISTER_PAIRS 

The instruction unconditionally branches to an address held in a pair of source registers and the address of the following instruction is saved in a pair of destination registers.

The instruction information is of type amd_dbgapi_register_id_t[4] with the source register IDs in indices 0 and 1, and the destination register IDs in indices 2 and 3. The registers with indices 0 and 2 hold the least significant address bits, and the registers with indices 1 and 3 hold the most significant address bits.

AMD_DBGAPI_INSTRUCTION_KIND_TERMINATE 

The instruction terminates the wave execution.

The instruction has no information.

AMD_DBGAPI_INSTRUCTION_KIND_TRAP 

The instruction enters the trap handler.

The trap handler may return to resume execution, may put the wave into the halt state and create an event for amd_dbgapi_process_next_pending_event to report, or may terminate the wave. The library cannot report execution in the trap handler. If single stepping the trap instruction reports the AMD_DBGAPI_WAVE_STOP_REASON_SINGLE_STEP reason, then the program counter will be at the instruction following the trap instruction, it will not be at the first instruction of the trap handler. It is undefined to set a breakpoint in the trap handler, and will likely cause the inferior to report errors and stop executing correctly. The instruction information is of type uint64_t with the value of the trap code.

AMD_DBGAPI_INSTRUCTION_KIND_HALT 

The instruction unconditionally halts the wave.

The instruction has no information.

AMD_DBGAPI_INSTRUCTION_KIND_BARRIER 

The instruction performs some kind of execution barrier which may result in the wave being halted until other waves allow it to continue.

Such instructions include wave execution barriers, wave synchronization barriers, and wave semaphores. The instruction has no information.

AMD_DBGAPI_INSTRUCTION_KIND_SLEEP 

The instruction causes the wave to stop executing for some period of time, before continuing execution with the next instruction.

The instruction has no information.

AMD_DBGAPI_INSTRUCTION_KIND_SPECIAL 

The instruction has some form of special behavior not covered by any of the other instruction kinds.

This likely makes it unsuitable to assume it will execute sequentially. This may include instructions that can affect the execution of other waves waiting at wave synchronization barriers, that may send interrupts, and so forth. The instruction has no information.

◆ amd_dbgapi_instruction_properties_t

A bit mask of the properties of an instruction.

Enumerator
AMD_DBGAPI_INSTRUCTION_PROPERTY_NONE 

The instruction has no properties.

Function Documentation

◆ amd_dbgapi_architecture_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_architecture_get_info ( amd_dbgapi_architecture_id_t  architecture_id,
amd_dbgapi_architecture_info_t  query,
size_t  value_size,
void *  value 
)

Query information about an architecture.

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

Parameters
[in]architecture_idThe architecture 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_ARCHITECTURE_IDarchitecture_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_classify_instruction()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_classify_instruction ( amd_dbgapi_architecture_id_t  architecture_id,
amd_dbgapi_global_address_t  address,
amd_dbgapi_size_t size,
const void *  memory,
amd_dbgapi_instruction_kind_t instruction_kind,
amd_dbgapi_instruction_properties_t instruction_properties,
void **  instruction_information 
)

Classify a single instruction.

Parameters
[in]architecture_idThe architecture to use to perform the classification.
[in]addressThe address of the first byte of the instruction.
[in,out]sizePass in the number of bytes available in memory which must be greater than 0. Return the number of bytes consumed to decode the instruction.
[in]memoryThe bytes to decode as an instruction. Must point to an array of at least size bytes. The AMD_DBGAPI_ARCHITECTURE_INFO_LARGEST_INSTRUCTION_SIZE query for architecture_id can be used to determine the number of bytes of the largest instruction. By making size at least this size ensures that the instruction can be decoded if legal. However, size may need to be smaller if no memory exists at the address of address plus size.
[out]instruction_kindThe classification kind of the instruction.
[out]instruction_propertiesPointer to the instruction properties. amd_dbgapi_instruction_properties_t defines the type of the instruction properties. If NULL, no value is returned.
[out]instruction_informationPointer to the instruction information that corresponds to the value of instruction_kind. amd_dbgapi_instruction_kind_t defines the type of the instruction information for each instruction kind value. If the instruction has no information then NULL is returned. The memory is allocated using the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client. If NULL, no value is returned.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully; and the result is stored in instruction_kind, instruction_properties, and instruction_information.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and size, instruction_kind, instruction_properties, and instruction_information are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and size, instruction_kind, instruction_properties, and instruction_information are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_IDarchitecture_id is invalid. size, instruction_kind, instruction_properties, and instruction_information are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTsize, memory, or instruction_kind are NULL, size is 0, or address is not aligned on the value returned by the AMD_DBGAPI_ARCHITECTURE_INFO_MINIMUM_INSTRUCTION_ALIGNMENT query. size, instruction_kind, instruction_properties, and instruction_information are unaltered.
AMD_DBGAPI_STATUS_ERROREncountered an error disassembling the instruction. The bytes may or may not be a legal instruction. size, instruction_kind, instruction_properties, and instruction_information are unaltered.
AMD_DBGAPI_STATUS_ERROR_ILLEGAL_INSTRUCTIONThe bytes starting at address, when up to size bytes are available, are not a legal instruction for the architecture. size, instruction_kind, instruction_properties, and instruction_information are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate instruction_text and address_operands returns NULL. size, instruction_kind, instruction_properties, and instruction_information are unaltered.

◆ amd_dbgapi_disassemble_instruction()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_disassemble_instruction ( amd_dbgapi_architecture_id_t  architecture_id,
amd_dbgapi_global_address_t  address,
amd_dbgapi_size_t size,
const void *  memory,
char **  instruction_text,
amd_dbgapi_symbolizer_id_t  symbolizer_id,
amd_dbgapi_status_t(*)(amd_dbgapi_symbolizer_id_t symbolizer_id, amd_dbgapi_global_address_t address, char **symbol_text)  symbolizer 
)

Disassemble a single instruction.

Parameters
[in]architecture_idThe architecture to use to perform the disassembly.
[in]addressThe address of the first byte of the instruction.
[in,out]sizePass in the number of bytes available in memory which must be greater than 0. Return the number of bytes consumed to decode the instruction.
[in]memoryThe bytes to decode as an instruction. Must point to an array of at least size bytes. The AMD_DBGAPI_ARCHITECTURE_INFO_LARGEST_INSTRUCTION_SIZE query for architecture_id can be used to determine the number of bytes of the largest instruction. By making size at least this size ensures that the instruction can be decoded if legal. However, size may need to be smaller if no memory exists at the address of address plus size.
[out]instruction_textIf NULL then only the instruction size is returned.

If non-NULL then set to a pointer to a NUL terminated string that contains the disassembled textual representation of the instruction. The memory is allocated using the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.

Parameters
[in]symbolizer_idThe client handle that is passed to any invocation of the symbolizer callback made while disassembling the instruction.
[in]symbolizerA callback that is invoked for any operand of the disassembled instruction that is a memory address. It allows the client to provide a symbolic representation of the address as a textual symbol that will be used in the returned instruction_text.

If symbolizer is NULL, then no symbolization will be performed and any memory addresses will be shown as their numeric address.

If symbolizer is non-NULL, the symbolizer function will be called with symbolizer_id having the value of the above symbolizer_id operand, and with address having the value of the address of the disassembled instruction's operand.

If the symbolizer callback wishes to report a symbol text it must allocate and assign memory for a non-empty NUL terminated char* string using a memory allocator that can be deallocated using the amd_dbgapi_callbacks_s::deallocate_memory callback. If must assign the pointer to symbol_text, and return AMD_DBGAPI_STATUS_SUCCESS.

If the symbolizer callback does not wish to report a symbol it must return AMD_DBGAPI_STATUS_ERROR_SYMBOL_NOT_FOUND.

Any symbol_text strings returned by the symbolizer callbacks reporting AMD_DBGAPI_STATUS_SUCCESS are deallocated using the amd_dbgapi_callbacks_s::deallocate_memory callback before amd_dbgapi_disassemble_instruction returns.

Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in size and instruction_text.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and size and instruction_text are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and size and instruction_text are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_IDarchitecture_id is invalid. size and instruction_text are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTsize or memory are NULL, *size is 0, or address is not aligned on the value returned by the AMD_DBGAPI_ARCHITECTURE_INFO_MINIMUM_INSTRUCTION_ALIGNMENT query. size and * instruction_text are unaltered.
AMD_DBGAPI_STATUS_ERROREncountered an error disassembling the instruction, a symbolizer callback returned AMD_DBGAPI_STATUS_SUCCESS with a NULL or empty symbol_text string. The bytes may or may not be a legal instruction. size and instruction_text are unaltered.
AMD_DBGAPI_STATUS_ERROR_ILLEGAL_INSTRUCTIONThe bytes starting at address, when up to size bytes are available, are not a legal instruction for the architecture. size and instruction_text are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate instruction_text returns NULL, or a symbolizer callback returns a status other than AMD_DBGAPI_STATUS_SUCCESS and AMD_DBGAPI_STATUS_ERROR_SYMBOL_NOT_FOUND. size and instruction_text are unaltered.

◆ amd_dbgapi_get_architecture()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_get_architecture ( uint32_t  elf_amdgpu_machine,
amd_dbgapi_architecture_id_t architecture_id 
)

Get an architecture from the AMD GPU ELF EF_AMDGPU_MACH value corresponding to the architecture.

This is defined as a bit field in the e_flags AMD GPU ELF header. See [User Guide for AMDGPU Backend - Code Object

Parameters
[in]elf_amdgpu_machineThe AMD GPU ELF EF_AMDGPU_MACH value.
[out]architecture_idThe corresponding architecture.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in architecture_id.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and architecture_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and architecture_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ELF_AMDGPU_MACHINEelf_amdgpu_machine is invalid or unsupported. architecture_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTarchitecture_id is NULL. architecture_id is unaltered.