Code Objects

Code Objects#

AMD Debugger API: Code Objects

Operations related to AMD GPU code objects loaded into a process. More...

Data Structures
struct	amd_dbgapi_code_object_id_t
	Opaque code object handle. More...

Macros
#define	AMD_DBGAPI_CODE_OBJECT_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_code_object_id_t, 0)
	The NULL code object handle. More...

Enumerations
enum	amd_dbgapi_code_object_info_t { AMD_DBGAPI_CODE_OBJECT_INFO_PROCESS = 1 , AMD_DBGAPI_CODE_OBJECT_INFO_URI_NAME = 2 , AMD_DBGAPI_CODE_OBJECT_INFO_LOAD_ADDRESS = 3 }
	Code object queries that are supported by amd_dbgapi_code_object_get_info. More...

Functions
amd_dbgapi_status_t AMD_DBGAPI	amd_dbgapi_code_object_get_info (amd_dbgapi_code_object_id_t code_object_id, amd_dbgapi_code_object_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_54
	Query information about a code object. More...

amd_dbgapi_status_t AMD_DBGAPI	amd_dbgapi_process_code_object_list (amd_dbgapi_process_id_t process_id, size_t code_object_count, amd_dbgapi_code_object_id_t code_objects, amd_dbgapi_changed_t changed) AMD_DBGAPI_VERSION_0_54
	Return the list of loaded code objects. More...

Detailed Description

Operations related to AMD GPU code objects loaded into a process.

AMD GPU code objects are standard ELF shared libraries defined in User Guide for AMDGPU Backend - Code Object.

AMD GPU code objects can be embedded in the host executable code object that is loaded into memory or be in a separate file in the file system. The AMD GPU loader supports loading either from memory or from files. The loader selects the segments to put into memory that contain the code and data necessary for AMD GPU code execution. It allocates global memory to map these segments and performs necessary relocations to create the loaded code object.

Macro Definition Documentation

◆ AMD_DBGAPI_CODE_OBJECT_NONE

#define AMD_DBGAPI_CODE_OBJECT_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_code_object_id_t, 0)

The NULL code object handle.

Enumeration Type Documentation

◆ amd_dbgapi_code_object_info_t

enum amd_dbgapi_code_object_info_t

Code object queries that are supported by amd_dbgapi_code_object_get_info.

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

Enumerator

AMD_DBGAPI_CODE_OBJECT_INFO_PROCESS

Return the process to which this code object belongs.

The type of this attribute is amd_dbgapi_process_id_t.

AMD_DBGAPI_CODE_OBJECT_INFO_URI_NAME

The URI name of the ELF shared object from which the code object was loaded.

Note that the code object is the in memory loaded relocated form of the ELF shared object. Multiple code objects may be loaded at different memory addresses in the same process from the same ELF shared object.

The type of this attribute is a NUL terminated char*. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.

The URI name syntax is defined by the following BNF syntax:

code_object_uri ::== file_uri | memory_uri
file_uri        ::== "file://" file_path
                     [ range_specifier ]
memory_uri      ::== "memory://" process_id
                     range_specifier
range_specifier ::== ( "#" | "?" )
                     "offset=" number
                     "&" "size=" number
file_path       ::== URI_ENCODED_OS_FILE_PATH
process_id      ::== DECIMAL_NUMBER
number          ::== HEX_NUMBER
                   | DECIMAL_NUMBER
                   | OCTAL_NUMBER

DECIMAL_NUMBER is a decimal C integral literal, HEX_NUMBER is a hexadecimal C integral literal with a "0x" or "0X" prefix, and OCTAL_NUMBER is an octal C integral literal with a "0" prefix.

URI_ENCODED_OS_FILE_PATH is a file path specified as a URI encoded UTF-8 string. In URI encoding, every character that is not in the regular expression [a-zA-Z0-9/_.~-] is encoded as two uppercase hexadecimal digits proceeded by "%". Directories in the path are separated by "/".

offset is a 0-based byte offset to the start of the code object. For a file URI, it is from the start of the file specified by the file_path, and if omitted defaults to 0. For a memory URI, it is the memory address and is required.

size is the number of bytes in the code object. For a file URI, if omitted it defaults to the size of the file. It is required for a memory URI.

process_id is the identity of the process owning the memory. For Linux it is the C unsigned integral decimal literal for the process ID (PID).

For example:

file:///dir1/dir2/file1
file:///dir3/dir4/file2#offset=0x2000&size=3000
memory://1234#offset=0x20000&size=3000

AMD_DBGAPI_CODE_OBJECT_INFO_LOAD_ADDRESS

The difference between the address in the ELF shared object and the address the code object is loaded in memory.

The type of this attributes is ptrdiff_t.

Function Documentation

◆ amd_dbgapi_code_object_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_code_object_get_info	(	amd_dbgapi_code_object_id_t	code_object_id,
		amd_dbgapi_code_object_info_t	query,
		size_t	value_size,
		void *	value
	)

Query information about a code object.

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

Parameters

[in]	code_object_id	The handle of the code object 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_CODE_OBJECT_ID	`code_object_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_process_code_object_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_code_object_list	(	amd_dbgapi_process_id_t	process_id,
		size_t *	code_object_count,
		amd_dbgapi_code_object_id_t **	code_objects,
		amd_dbgapi_changed_t *	changed
	)

Return the list of loaded code objects.

The order of the code object handles in the list is unspecified and can vary between calls.