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

Processes

Processes#

AMD DBG API: Processes

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

Modules

 Generating a core dump of a process
 Operations related to generating and using core dumps.
 

Data Structures

struct  amd_dbgapi_process_id_t
 Opaque process handle. More...
 
struct  amd_dbgapi_core_state_data_t
 AMDGPU corefile state data for a process. 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_endianness_t { AMD_DBGAPI_ENDIAN_BIG = 0 , AMD_DBGAPI_ENDIAN_LITTLE = 1 }
 Byte endianness encoding. More...
 
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_PRECISE_ALU_EXCEPTIONS_SUPPORTED = 5 , AMD_DBGAPI_PROCESS_INFO_OS_ID = 6 , AMD_DBGAPI_PROCESS_INFO_CORE_STATE = 7
}
 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_77
 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_76
 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_76
 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_endianness_t

Byte endianness encoding.

Enumerator
AMD_DBGAPI_ENDIAN_BIG 

Encoding is done using big endian.


AMD_DBGAPI_ENDIAN_LITTLE 

Encoding is done using little endian.


◆ 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_PRECISE_ALU_EXCEPTIONS_SUPPORTED 

Return if the architectures of all the agents of a process support controlling ALU exceptions reporting precision.

The type of this attribute is uint32_t with the values defined by amd_dbgapi_alu_exceptions_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.

If the process image was rebuilt using a core dump, then amd_dbgapi_process_get_info returns the AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE error.

AMD_DBGAPI_PROCESS_INFO_CORE_STATE 

Return a blob containing the content to put in the state note when generating a core dump.

The content of the note is allocated using the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.

If allocation fails, then amd_dbgapi_process_get_info returns the AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK 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 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

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 and AMD_DBGAPI_ALU_EXCEPTIONS_PRECISION_NONE.

When attaching to a live process, the client process handle must have been associated with a native operating system process, and the amd_dbgapi_callbacks_s::client_process_get_info callback with the AMD_DBGAPI_CLIENT_PROCESS_INFO_OS_PID request is used to obtain it.

When attaching to a process image (core dump), the client process handle has not been associated with a native operating system, and the amd_dbgapi_callbacks_s::client_process_get_info request must return AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE.

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_idThe client handle for the process. It is passed as an argument to any callbacks performed to indicate the process being requested.
[out]process_idThe process handle to use for all operations related to this process.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the process is now attached returning process_id.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and process_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and process_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_ALREADY_ATTACHEDThe process is already attached. The process remains attached and process_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_RESTRICTIONThere 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_ARGUMENTclient_process_id or process_id are NULL. The process is not attached and process_id is unaltered.
AMD_DBGAPI_STATUS_ERROREncountered 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 and AMD_DBGAPI_ALU_EXCEPTIONS_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. If the process is in the frozen state, it is unfrozen. The wave creation mode is restored to AMD_DBGAPI_WAVE_CREATION_NORMAL.

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_idThe process handle that is being detached.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe 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_FATALA fatal error occurred. The library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDThe 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_idThe process 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_PROCESS_IDprocess_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_NOT_AVAILABLEThe 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_CALLBACKThis will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate value returns NULL. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_PROCESS_NOT_FROZENThe request is AMD_DBGAPI_PROCESS_INFO_CORE_STATE but the process is not frozen.
AMD_DBGAPI_STATUS_ERROR_RESTRICTIONThe request is ::AMDGPU_DBGAPI_PROCESS_INFO_CORE_STATE but the process configuration does not permit the creation of a reliable core dump.

◆ 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_idIf AMD_DBGAPI_PROCESS_NONE then set the progress for all processes currently attached. Otherwise, set the progress for the process process_id.
[in]progressThe progress being set.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the progress has been set.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. The progress setting is not changed.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTprogress is invalid. The progress setting is not changed.
AMD_DBGAPI_STATUS_ERROR_PROCESS_FROZENThe process is frozen. The progress setting cannot be changed and must remain AMD_DBGAPI_PROGRESS_NO_FORWARD.

◆ 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_idThe process being controlled.
[in]creationThe wave creation mode being set.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the wave creation mode has been set.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. The wave creation mode setting is not changed.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTcreation is invalid. The wave creation setting is not changed.
AMD_DBGAPI_STATUS_ERROR_PROCESS_FROZENThe process is frozen. The wave creation mode setting cannot be changed and must remain AMD_DBGAPI_WAVE_CREATION_STOP.