AMD_DBGAPI
0.70.1
|
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... | |
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.
#define AMD_DBGAPI_ARCHITECTURE_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_architecture_id_t, 0) |
The NULL architecture handle.
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.
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. |
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_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.
[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. |
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 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_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.
[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 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_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. |
AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully; and the result is stored in instruction_kind , instruction_properties , and instruction_information . |
AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized; and size , instruction_kind , instruction_properties , and instruction_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 , and instruction_information are unaltered. |
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID | architecture_id is invalid. size , instruction_kind , instruction_properties , and instruction_information are unaltered. |
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | size , 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_ERROR | Encountered 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_INSTRUCTION | The 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_CALLBACK | This 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_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.
[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 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_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.
[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.
AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the result is stored in size and instruction_text . |
AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized and size and instruction_text are unaltered. |
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized and size and instruction_text are unaltered. |
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID | architecture_id is invalid. size and instruction_text are unaltered. |
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | size 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_ERROR | Encountered 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_INSTRUCTION | The 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_CALLBACK | This 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_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
[in] | elf_amdgpu_machine | The AMD GPU ELF EF_AMDGPU_MACH value. |
[out] | architecture_id | The corresponding architecture. |
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. |