AMD_DBGAPI: Processes

AMD_DBGAPI 0.64.0

Data Structures | Macros | Typedefs | Enumerations | Functions
Processes

Operations related to establishing AMD GPU debug control of a process. More...

## Data Structures
struct | amd_dbgapi_process_id_t
| Opaque process handle. More...

## Macros
#define | AMD_DBGAPI_PROCESS_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_process_id_t, 0)
| The NULL process handle. More...

## Typedefs
typedef struct amd_dbgapi_client_process_s * | amd_dbgapi_client_process_id_t
| Opaque client process handle. More...

## Enumerations
enum | amd_dbgapi_process_info_t { AMD_DBGAPI_PROCESS_INFO_NOTIFIER = 1, AMD_DBGAPI_PROCESS_INFO_WATCHPOINT_COUNT = 2, AMD_DBGAPI_PROCESS_INFO_WATCHPOINT_SHARE = 3, AMD_DBGAPI_PROCESS_INFO_PRECISE_MEMORY_SUPPORTED = 4, AMD_DBGAPI_PROCESS_INFO_OS_ID = 5 }
| Process queries that are supported by amd_dbgapi_process_get_info. More...
enum | amd_dbgapi_progress_t { AMD_DBGAPI_PROGRESS_NORMAL = 0, AMD_DBGAPI_PROGRESS_NO_FORWARD = 1 }
| The kinds of progress supported by the library. More...
enum | amd_dbgapi_wave_creation_t { AMD_DBGAPI_WAVE_CREATION_NORMAL = 0, AMD_DBGAPI_WAVE_CREATION_STOP = 1 }
| The kinds of wave creation supported by the hardware. More...

## Functions
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_process_get_info (amd_dbgapi_process_id_t process_id, amd_dbgapi_process_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_56
| Query information about a process. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_process_attach (amd_dbgapi_client_process_id_t client_process_id, amd_dbgapi_process_id_t *process_id) AMD_DBGAPI_VERSION_0_56
| Attach to a process in order to provide debug control of the AMD GPUs it uses. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_process_detach (amd_dbgapi_process_id_t process_id) AMD_DBGAPI_VERSION_0_54
| Detach from a process and no longer have debug control of the AMD GPU devices it uses. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_process_set_progress (amd_dbgapi_process_id_t process_id, amd_dbgapi_progress_t progress) AMD_DBGAPI_VERSION_0_54
| Set the progress required for a process. More...
amd_dbgapi_status_t AMD_DBGAPI | amd_dbgapi_process_set_wave_creation (amd_dbgapi_process_id_t process_id, amd_dbgapi_wave_creation_t creation) AMD_DBGAPI_VERSION_0_54
| Set the wave creation mode for a process. More...

## Detailed Description

Operations related to establishing AMD GPU debug control of a process.

The library supports AMD GPU debug control of multiple operating system processes. Each process can have access to multiple AMD GPU devices, but each process uses the AMD GPU devices independently of other processes.

## Macro Definition Documentation

## ◆ AMD_DBGAPI_PROCESS_NONE

#define AMD_DBGAPI_PROCESS_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_process_id_t, 0)

The NULL process handle.

## Typedef Documentation

## ◆ amd_dbgapi_client_process_id_t

typedef struct amd_dbgapi_client_process_s* amd_dbgapi_client_process_id_t

Opaque client process handle.

A pointer to client data associated with a process. This pointer is passed to the process specific callbacks (see Callbacks) to allow the client of the library to identify the process. Each process must have a single unique value.

## Enumeration Type Documentation

## ◆ amd_dbgapi_process_info_t

enum amd_dbgapi_process_info_t

Process queries that are supported by amd_dbgapi_process_get_info.

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

Enumerator
AMD_DBGAPI_PROCESS_INFO_NOTIFIER | The notifier for the process that indicates if pending events are available. The type of this attributes is amd_dbgapi_notifier_t.
AMD_DBGAPI_PROCESS_INFO_WATCHPOINT_COUNT | Return the number of data watchpoints supported by the process. Zero is returned if data watchpoints are not supported. The type of this attribute is `size_t`.
AMD_DBGAPI_PROCESS_INFO_WATCHPOINT_SHARE | Return how watchpoints are shared between processes. The type of this attribute is `uint32_t` with the values defined by amd_dbgapi_watchpoint_share_kind_t.
AMD_DBGAPI_PROCESS_INFO_PRECISE_MEMORY_SUPPORTED | Return if the architectures of all the agents of a process support controlling memory precision. The type of this attribute is `uint32_t` with the values defined by amd_dbgapi_memory_precision_t.
AMD_DBGAPI_PROCESS_INFO_OS_ID | Native operating system process ID. The type of this attribute is amd_dbgapi_os_process_id_t. If the native operating system process was exited when amd_dbgapi_process_attach attached to the process, then amd_dbgapi_process_get_info returns the AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE error.

## ◆ amd_dbgapi_progress_t

enum amd_dbgapi_progress_t

The kinds of progress supported by the library.

In performing operations, the library may make both waves it needs to access, as well as other waves, unavailable for hardware execution. After completing the operation, it will make all waves available for hardware execution. This is termed pausing and unpausing wave execution respectively. Pausing and unpausing waves for each command separately works but can result in longer latency than if several commands could be performed while the waves are paused. Debugging the very large number of waves that can exist on an AMD GPU can involve many operations, making batching commands even more beneficial. The progress setting allows controlling this behavior.

Enumerator
AMD_DBGAPI_PROGRESS_NORMAL | Normal progress is needed. Commands are issued immediately. After completing each command all non-stopped waves will be unpaused. Switching from another progress mode to this will unpause any waves that are paused.
AMD_DBGAPI_PROGRESS_NO_FORWARD | No forward progress is needed. Commands are issued immediately. After completing each command, non-stopped waves may be left paused. The waves left paused may include both the wave(s) the command operates on, as well as other waves. While in AMD_DBGAPI_PROGRESS_NO_FORWARD mode, paused waves may remain paused, or may be unpaused at any point. Only by leaving AMD_DBGAPI_PROGRESS_NO_FORWARD mode will the library not leave any waves paused after completing a command. Note that the events that amd_dbgapi_wave_stop causes to be reported will occur when in AMD_DBGAPI_PROGRESS_NO_FORWARD mode. It is not necessary to change the progress mode to AMD_DBGAPI_PROGRESS_NORMAL for those events to be reported. This can result in a series of commands completing far faster than in AMD_DBGAPI_PROGRESS_NORMAL mode. Also, any queries for lists such as amd_dbgapi_process_wave_list may return `unchanged` as true more often, reducing the work needed to parse the lists to determine what has changed. With large lists this can be significant. If the client needs a wave to complete a single step resume, then it must leave AMD_DBGAPI_PROGRESS_NO_FORWARD mode in order to prevent that wave from remaining paused.

## ◆ amd_dbgapi_wave_creation_t

enum amd_dbgapi_wave_creation_t

The kinds of wave creation supported by the hardware.

The hardware creates new waves asynchronously as it executes dispatch packets. If the client requires that all waves are stopped, it needs to first request that the hardware stops creating new waves, followed by halting all already created waves. The wave creation setting allows controlling how the hardware creates new waves for dispatch packets on queues associated with agents belonging to a specific process. It has no affect on waves that have already been created.

Enumerator
AMD_DBGAPI_WAVE_CREATION_NORMAL | Normal wave creation allows new waves to be created.
AMD_DBGAPI_WAVE_CREATION_STOP | Stop wave creation prevents new waves from being created.

## Function Documentation

## ◆ amd_dbgapi_process_attach()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_attach | ( | amd_dbgapi_client_process_id_t | client_process_id,
|  | amd_dbgapi_process_id_t * | process_id
| ) |  |

Attach to a process in order to provide debug control of the AMD GPUs it uses.

Attaching can be performed on processes that have not started executing, as well as those that are already executing.

The process progress is initialized to AMD_DBGAPI_PROGRESS_NORMAL. All agents accessed by the process are configured to AMD_DBGAPI_MEMORY_PRECISION_NONE.

The client process handle must have been associated with a native operating system process, and the amd_dbgapi_callbacks_s::get_os_pid callback is used to obtain it.

It is the client's responsibility to fetch the current code object list using amd_dbgapi_process_code_object_list as the AMD_DBGAPI_EVENT_KIND_CODE_OBJECT_LIST_UPDATED event is only reported when a thread is in the process of changing the code object list.

The AMD_DBGAPI_EVENT_KIND_RUNTIME event will be reported if the inferior's runtime support is already enabled.

If the associated native operating system process exits while the library is attached to it, appropriate actions are taken to reflect that the inferior process no longer has any state. For example, pending events are created for wave command termination if there are pending wave stop or wave single step requests; a pending code object list updated event is created if there were codes objects previously loaded; a pending runtime event is created to indicate the inferior's runtime support has been unloaded if previously loaded; and queries on agents, queues, dispatches, waves, and code objects will report none exist. The process handle remains valid until amd_dbgapi_process_detach is used to detach from the client process.

If the associated native operating system process has already exited when attaching, then the attach is still successful, but any queries on agents, queues, dispatches, waves, and code objects will report none exist.

If the associated native operating system process exits while a library operation is being executed, then the operation behaves as if the process exited before it was invoked. For example, a wave operation will report an invalid wave handle, a list query will report an empty list, and so forth.

It is undefined to use any library operation except amd_dbgapi_process_detach on a process that has its virtual address space replaced. After detach, the same process can be attached again to continue accessing the process if desired. For example, in Linux an `exec` system call replaces the virtual address space which causes all information about agents, queues, dispatches, and waves to become invalid, and the ability to read and write memory may also no longer be allowed by the operating system.

If after attaching to a process it spawns another process, the library continues to be attached to the parent process. If desired, the client can always use amd_dbgapi_process_attach to attach to the child process and amd_dbgapi_process_detach to detach from the parent process.

Parameters

  [in] | client_process_id | The client handle for the process. It is passed as an argument to any callbacks performed to indicate the process being requested.
  [out] | process_id | The process handle to use for all operations related to this process.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the process is now attached returning `process_id`.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized and `process_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized and `process_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_ALREADY_ATTACHED | The process is already attached. The process remains attached and `process_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_RESTRICTION | There is a restriction error that prevents debugging process `client_process_id`. See AMD_DBGAPI_STATUS_ERROR_RESTRICTION for possible reasons. The process is not attached and `process_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `client_process_id` or `process_id` are NULL. The process is not attached and `process_id` is unaltered.
  AMD_DBGAPI_STATUS_ERROR | Encountered some other error while attaching to the process. The process is not attached and `process_id` is unaltered.

## ◆ amd_dbgapi_process_detach()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_detach | ( | amd_dbgapi_process_id_t | process_id | ) |

Detach from a process and no longer have debug control of the AMD GPU devices it uses.

If the associated native operating system process has already exited, or exits while being detached, then the process is trivially detached.

Otherwise, detaching causes execution of the associated native operating system process to continue unaffected by the library. Any waves with a displaced stepping buffer are stopped and the displaced stepping buffer completed. Any data watchpoints are removed. All agents are configured to AMD_DBGAPI_MEMORY_PRECISION_NONE. Any waves in the stopped or single step state are resumed in non-single step mode. Any pending events for the process are discarded, and no further events will be generated for the process.

After detaching, the process handle, and all handles associated with entities relating to the process, become invalid.

A native operating system process can be attached and detached multiple times. Each attach returns a unique process handle even for the same native operating system process.

The client is responsible for removing any inserted breakpoints before detaching. Failing to do so will cause execution of a breakpoint instruction to put the queue into an error state, aborting any executing waves for dispatches on that queue.

Parameters

  process_id | The process handle that is being detached.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the process has been detached from the associated native operating system process, or the associated native operating system process has already exited.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized.
  AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | The `process_id` is invalid. No process is detached.

## ◆ amd_dbgapi_process_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_get_info | ( | amd_dbgapi_process_id_t | process_id,
|  | amd_dbgapi_process_info_t | query,
|  | size_t | value_size,
|  | void * | value
| ) |  |

Query information about a process.

amd_dbgapi_process_info_t specifies the queries supported and the type returned using the `value` argument.

Parameters

  [in] | process_id | The process 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_PROCESS_ID | `process_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_NOT_AVAILABLE | `The` requested information is not available. See amd_dbgapi_process_info_t for queries that can produce this error. `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_set_progress()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_set_progress | ( | amd_dbgapi_process_id_t | process_id,
|  | amd_dbgapi_progress_t | progress
| ) |  |

Set the progress required for a process.

Parameters

  [in] | process_id | If AMD_DBGAPI_PROCESS_NONE then set the progress for all processes currently attached. Otherwise, set the progress for the process `process_id`.
  [in] | progress | The progress being set.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the progress has been set.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized.
  AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | `process_id` is invalid. The progress setting is not changed.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `progress` is invalid. The progress setting is not changed.

## ◆ amd_dbgapi_process_set_wave_creation()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_set_wave_creation | ( | amd_dbgapi_process_id_t | process_id,
|  | amd_dbgapi_wave_creation_t | creation
| ) |  |

Set the wave creation mode for a process.

The setting applies to all agents of the specified process.

Parameters

  [in] | process_id | The process being controlled.
  [in] | creation | The wave creation mode being set.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the wave creation mode has been set.
  AMD_DBGAPI_STATUS_FATAL | A fatal error occurred. The library is left uninitialized.
  AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED | The library is not initialized. The library is left uninitialized.
  AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | `process_id` is invalid. The wave creation mode setting is not changed.
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT | `creation` is invalid. The wave creation setting is not changed.