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... | |
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
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 |
| AMD_DBGAPI_PROCESS_INFO_WATCHPOINT_SHARE | Return how watchpoints are shared between processes. The type of this attribute is |
| 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 |
| 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
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 |
◆ 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_idis unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and process_idis unaltered.AMD_DBGAPI_STATUS_ERROR_ALREADY_ATTACHED The process is already attached. The process remains attached and process_idis 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 andprocess_idis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT client_process_idorprocess_idare NULL. The process is not attached andprocess_idis unaltered.AMD_DBGAPI_STATUS_ERROR Encountered some other error while attaching to the process. The process is not attached and process_idis 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_idis 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 valueis unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and valueis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID process_idis invalid.valueis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT valueis NULL orqueryis invalid.valueis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY value_sizedoes not match the size of thequeryresult.valueis unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE Therequested information is not available. See amd_dbgapi_process_info_t for queries that can produce this error.valueis unaltered.AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate valuereturns NULL.valueis 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_idis invalid. The progress setting is not changed.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT progressis 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_idis invalid. The wave creation mode setting is not changed.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT creationis invalid. The wave creation setting is not changed.