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

Code Objects

Code Objects#

AMD DBG 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

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_idThe handle of the code object 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_CODE_OBJECT_IDcode_object_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_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.

Parameters
[in]process_idIf AMD_DBGAPI_PROCESS_NONE then the code object list for all processes is requested. Otherwise, the code object list for process process_id is requested.
[out]code_object_countThe number of code objects currently loaded.
[out]code_objectsIf changed is not NULL and the code object list of all of the processes requested have not changed since the last call(s) to amd_dbgapi_process_code_object_list for each of them, then return NULL. Otherwise, return a pointer to an array of amd_dbgapi_code_object_id_t with code_object_count elements. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.
[in,out]changedIf NULL then left unaltered. If non-NULL, set to AMD_DBGAPI_CHANGED_NO if the list of code objects for each requested process is the same as when amd_dbgapi_process_code_object_list was last called for them. Otherwise, set to AMD_DBGAPI_CHANGED_YES.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in changed, code_object_count, and code_objects.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and code_object_count, code_objects, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and code_object_count, code_objects, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. code_object_count, code_objects, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTcode_object_count or code_objects are NULL, or changed is invalid. code_object_count, code_objects, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate code_objects returns NULL. code_object_count, code_objects, and changed are unaltered.