AMD_DBGAPI: Code Objects

AMD_DBGAPI 0.64.0

Data Structures | Macros | Enumerations | Functions
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.

Parameters

  [in] | process_id | If 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_count | The number of code objects currently loaded.
  [out] | code_objects | If `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] | changed | If 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_SUCCESS | The function has been executed successfully and the result is stored in `changed`, `code_object_count`, and `code_objects`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized; and `code_object_count`, `code_objects`, and `changed` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The 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_ID | `process_id` is invalid. `code_object_count`, `code_objects`, and `changed` are unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `code_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_CALLBACK | This 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.