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... | |
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 |
AMD_DBGAPI_ARCHITECTURE_INFO_ELF_AMDGPU_MACHINE | Return the AMD GPU ELF This is defined as a bit field in the |
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 |
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 |
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
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_id The architecture 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_ARCHITECTURE_ID architecture_id
is invalid.value
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT value
is NULL orquery
is invalid.value
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY value_size
does not match the size of thequery
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_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_id The architecture to use to perform the classification. [in] address The address of the first byte of the instruction. [in,out] size Pass 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] memory The 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 forarchitecture_id
can be used to determine the number of bytes of the largest instruction. By makingsize
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 ofaddress
plussize
.[out] instruction_kind The classification kind of the instruction. [out] instruction_properties Pointer to the instruction properties. amd_dbgapi_instruction_properties_t defines the type of the instruction properties. If NULL, no value is returned. [out] instruction_information Pointer 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_SUCCESS The function has been executed successfully; and the result is stored in instruction_kind
,instruction_properties
, andinstruction_information
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized; and size
,instruction_kind
,instruction_properties
, andinstruction_information
are unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized; and size
,instruction_kind
,instruction_properties
, andinstruction_information
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID architecture_id
is invalid.size
,instruction_kind
,instruction_properties
, andinstruction_information
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT size
,memory
, orinstruction_kind
are NULL,size
is 0, oraddress
is not aligned on the value returned by the AMD_DBGAPI_ARCHITECTURE_INFO_MINIMUM_INSTRUCTION_ALIGNMENT query.size
,instruction_kind
,instruction_properties
, andinstruction_information
are unaltered.AMD_DBGAPI_STATUS_ERROR Encountered an error disassembling the instruction. The bytes may or may not be a legal instruction. size
,instruction_kind
,instruction_properties
, andinstruction_information
are unaltered.AMD_DBGAPI_STATUS_ERROR_ILLEGAL_INSTRUCTION The bytes starting at address
, when up tosize
bytes are available, are not a legal instruction for the architecture.size
,instruction_kind
,instruction_properties
, andinstruction_information
are unaltered.AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate instruction_text
andaddress_operands
returns NULL.size
,instruction_kind
,instruction_properties
, andinstruction_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_id The architecture to use to perform the disassembly. [in] address The address of the first byte of the instruction. [in,out] size Pass 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] memory The 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 forarchitecture_id
can be used to determine the number of bytes of the largest instruction. By makingsize
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 ofaddress
plussize
.[out] instruction_text If 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_id The client handle that is passed to any invocation of the symbolizer
callback made while disassembling the instruction.[in] symbolizer A 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_SUCCESS The function has been executed successfully and the result is stored in size
andinstruction_text
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized and size
andinstruction_text
are unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and size
andinstruction_text
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID architecture_id
is invalid.size
andinstruction_text
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT size
ormemory
are NULL,*size
is 0, oraddress
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_ERROR Encountered an error disassembling the instruction, a symbolizer
callback returned AMD_DBGAPI_STATUS_SUCCESS with a NULL or emptysymbol_text
string. The bytes may or may not be a legal instruction.size
andinstruction_text
are unaltered.AMD_DBGAPI_STATUS_ERROR_ILLEGAL_INSTRUCTION The bytes starting at address
, when up tosize
bytes are available, are not a legal instruction for the architecture.size
andinstruction_text
are unaltered.AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate instruction_text
returns NULL, or asymbolizer
callback returns a status other than AMD_DBGAPI_STATUS_SUCCESS and AMD_DBGAPI_STATUS_ERROR_SYMBOL_NOT_FOUND.size
andinstruction_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_machine The AMD GPU ELF EF_AMDGPU_MACH
value.[out] architecture_id The corresponding architecture.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and the result is stored in architecture_id
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized and architecture_id
is unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and architecture_id
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ELF_AMDGPU_MACHINE elf_amdgpu_machine
is invalid or unsupported.architecture_id
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT architecture_id
is NULL.architecture_id
is unaltered.