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

Workgroup

Workgroup#

AMD DBG API: Workgroup

Operations related to AMD GPU workgroups. More...

Data Structures

struct  amd_dbgapi_workgroup_id_t
 Opaque workgroup handle. More...
 

Macros

#define AMD_DBGAPI_WORKGROUP_NONE    AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_workgroup_id_t, 0)
 The NULL workgroup handle. More...
 

Enumerations

enum  amd_dbgapi_workgroup_info_t {
  AMD_DBGAPI_WORKGROUP_INFO_DISPATCH = 1 , AMD_DBGAPI_WORKGROUP_INFO_QUEUE = 2 , AMD_DBGAPI_WORKGROUP_INFO_AGENT = 3 , AMD_DBGAPI_WORKGROUP_INFO_PROCESS = 4 ,
  AMD_DBGAPI_WORKGROUP_INFO_ARCHITECTURE = 5 , AMD_DBGAPI_WORKGROUP_INFO_WORKGROUP_COORD = 6
}
 Workgroup queries that are supported by amd_dbgapi_workgroup_get_info. More...
 

Functions

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_workgroup_get_info (amd_dbgapi_workgroup_id_t workgroup_id, amd_dbgapi_workgroup_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_64
 Query information about a workgroup. More...
 
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_workgroup_list (amd_dbgapi_process_id_t process_id, size_t *workgroup_count, amd_dbgapi_workgroup_id_t **workgroups, amd_dbgapi_changed_t *changed) AMD_DBGAPI_VERSION_0_64
 Return the list of existing workgroups. More...
 

Detailed Description

Operations related to AMD GPU workgroups.

Macro Definition Documentation

◆ AMD_DBGAPI_WORKGROUP_NONE

#define AMD_DBGAPI_WORKGROUP_NONE    AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_workgroup_id_t, 0)

The NULL workgroup handle.

Enumeration Type Documentation

◆ amd_dbgapi_workgroup_info_t

Workgroup queries that are supported by amd_dbgapi_workgroup_get_info.

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

Enumerator
AMD_DBGAPI_WORKGROUP_INFO_DISPATCH 

Return the dispatch to which this workgroup belongs.

The type of this attribute is amd_dbgapi_dispatch_id_t.

If the dispatch associated with a workgroup is not available then amd_dbgapi_workgroup_get_info returns the AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE error. See the Known Limitations and Restrictions section.

AMD_DBGAPI_WORKGROUP_INFO_QUEUE 

Return the queue to which this workgroup belongs.

The type of this attribute is amd_dbgapi_queue_id_t.

AMD_DBGAPI_WORKGROUP_INFO_AGENT 

Return the agent to which this workgroup belongs.

The type of this attribute is amd_dbgapi_agent_id_t.

AMD_DBGAPI_WORKGROUP_INFO_PROCESS 

Return the process to which this workgroup belongs.

The type of this attribute is amd_dbgapi_process_id_t.

AMD_DBGAPI_WORKGROUP_INFO_ARCHITECTURE 

Return the architecture of this workgroup.

The type of this attribute is amd_dbgapi_architecture_id_t.

AMD_DBGAPI_WORKGROUP_INFO_WORKGROUP_COORD 

The workgroup workgroup coordinate in the dispatch grid dimensions.

The type of this attribute is uint32_t[3] with elements 1, 2, and 3 corresponding to the X, Y, and Z coordinates respectively.

If the dispatch associated with a workgroup is not available then amd_dbgapi_workgroup_get_info returns AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE. See the Known Limitations and Restrictions section.

Function Documentation

◆ amd_dbgapi_process_workgroup_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_workgroup_list ( amd_dbgapi_process_id_t  process_id,
size_t *  workgroup_count,
amd_dbgapi_workgroup_id_t **  workgroups,
amd_dbgapi_changed_t changed 
)

Return the list of existing workgroups.

The order of the workgroup handles in the list is unspecified and can vary between calls.

Parameters
[in]process_idIf AMD_DBGAPI_PROCESS_NONE then the workgroup list for all processes is requested. Otherwise, the workgroup list of process process_id is requested.
[out]workgroup_countThe number of workgroups executing in the process.
[out]workgroupsIf changed is not NULL and the workgroup list of all of the processes requested have not changed since the last call(s) to amd_dbgapi_process_workgroup_list for each of them, then return NULL. Otherwise, return a pointer to an array of amd_dbgapi_workgroup_id_t with workgroup_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 workgroups for each requested process is the same as when amd_dbgapi_process_workgroup_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, workgroup_count, and workgroups.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and changed, workgroup_count, and workgroups are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and workgroup_count, workgroups, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. workgroup_count, workgroups, and unchanged are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTworkgroup_count or workgroups are NULL, or changed is invalid. workgroup_count, workgroups, 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 workgroups returns NULL. workgroup_count, workgroups, and changed are unaltered.

◆ amd_dbgapi_workgroup_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_workgroup_get_info ( amd_dbgapi_workgroup_id_t  workgroup_id,
amd_dbgapi_workgroup_info_t  query,
size_t  value_size,
void *  value 
)

Query information about a workgroup.

amd_dbgapi_workgroup_info_t specifies the queries supported and the type returned using the value argument.

Parameters
[in]workgroup_idThe handle of the workgroup 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_WORKGROUP_IDworkgroup_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_workgroup_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.