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 valueis unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and valueis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID architecture_idis invalid.valueis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT valueis NULL orqueryis invalid.valueis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY value_sizedoes not match the size of thequeryresult.valueis unaltered.AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate valuereturns NULL.valueis 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 memorywhich 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 sizebytes. The AMD_DBGAPI_ARCHITECTURE_INFO_LARGEST_INSTRUCTION_SIZE query forarchitecture_idcan be used to determine the number of bytes of the largest instruction. By makingsizeat least this size ensures that the instruction can be decoded if legal. However,sizemay need to be smaller if no memory exists at the address ofaddressplussize.[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_informationare unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized; and size,instruction_kind,instruction_properties, andinstruction_informationare unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID architecture_idis invalid.size,instruction_kind,instruction_properties, andinstruction_informationare unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT size,memory, orinstruction_kindare NULL,sizeis 0, oraddressis not aligned on the value returned by the AMD_DBGAPI_ARCHITECTURE_INFO_MINIMUM_INSTRUCTION_ALIGNMENT query.size,instruction_kind,instruction_properties, andinstruction_informationare 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_informationare unaltered.AMD_DBGAPI_STATUS_ERROR_ILLEGAL_INSTRUCTION The bytes starting at address, when up tosizebytes are available, are not a legal instruction for the architecture.size,instruction_kind,instruction_properties, andinstruction_informationare unaltered.AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate instruction_textandaddress_operandsreturns NULL.size,instruction_kind,instruction_properties, andinstruction_informationare 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 memorywhich 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 sizebytes. The AMD_DBGAPI_ARCHITECTURE_INFO_LARGEST_INSTRUCTION_SIZE query forarchitecture_idcan be used to determine the number of bytes of the largest instruction. By makingsizeat least this size ensures that the instruction can be decoded if legal. However,sizemay need to be smaller if no memory exists at the address ofaddressplussize.[out] instruction_text If NULL then only the instruction sizeis 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 symbolizercallback 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 sizeandinstruction_text.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized and sizeandinstruction_textare unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and sizeandinstruction_textare unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID architecture_idis invalid.sizeandinstruction_textare unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT sizeormemoryare NULL,*sizeis 0, oraddressis not aligned on the value returned by the AMD_DBGAPI_ARCHITECTURE_INFO_MINIMUM_INSTRUCTION_ALIGNMENT query.sizeand*instruction_text are unaltered.AMD_DBGAPI_STATUS_ERROR Encountered an error disassembling the instruction, a symbolizercallback returned AMD_DBGAPI_STATUS_SUCCESS with a NULL or emptysymbol_textstring. The bytes may or may not be a legal instruction.sizeandinstruction_textare unaltered.AMD_DBGAPI_STATUS_ERROR_ILLEGAL_INSTRUCTION The bytes starting at address, when up tosizebytes are available, are not a legal instruction for the architecture.sizeandinstruction_textare unaltered.AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate instruction_textreturns NULL, or asymbolizercallback returns a status other than AMD_DBGAPI_STATUS_SUCCESS and AMD_DBGAPI_STATUS_ERROR_SYMBOL_NOT_FOUND.sizeandinstruction_textare 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_MACHvalue.[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_idis unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and architecture_idis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ELF_AMDGPU_MACHINE elf_amdgpu_machineis invalid or unsupported.architecture_idis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT architecture_idis NULL.architecture_idis unaltered.