Skip to content

Commit f4abdbe

Browse files
EwanCEwanC
committed
Add Native Command support to command-buffer
Enables support for using native commands inside a command-buffer.
1 parent b487b62 commit f4abdbe

32 files changed

+1104
-1
lines changed

‎include/ur_api.h

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -429,6 +429,10 @@ typedef enum ur_function_t {
429429
UR_FUNCTION_ENQUEUE_EVENTS_WAIT_WITH_BARRIER_EXT = 246,
430430
/// Enumerator for ::urPhysicalMemGetInfo
431431
UR_FUNCTION_PHYSICAL_MEM_GET_INFO = 249,
432+
/// Enumerator for ::urCommandBufferAppendNativeCommandExp
433+
UR_FUNCTION_COMMAND_BUFFER_APPEND_NATIVE_COMMAND_EXP = 250,
434+
/// Enumerator for ::urCommandBufferGetNativeHandleExp
435+
UR_FUNCTION_COMMAND_BUFFER_GET_NATIVE_HANDLE_EXP = 252,
432436
/// @cond
433437
UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
434438
/// @endcond
@@ -10985,6 +10989,51 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendUSMAdviseExp(
1098510989
/// [out][optional] Handle to this command.
1098610990
ur_exp_command_buffer_command_handle_t *phCommand);
1098710991

10992+
///////////////////////////////////////////////////////////////////////////////
10993+
/// @brief Function adding work through the native API to be executed
10994+
/// immediately.
10995+
typedef void (*ur_exp_command_buffer_native_command_function_t)(
10996+
/// [in][out] pointer to data to be passed to callback
10997+
void *pUserData);
10998+
10999+
///////////////////////////////////////////////////////////////////////////////
11000+
/// @brief Append nodes through a native backend API
11001+
///
11002+
/// @returns
11003+
/// - ::UR_RESULT_SUCCESS
11004+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
11005+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
11006+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
11007+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
11008+
/// + `NULL == hCommandBuffer`
11009+
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
11010+
/// + `NULL == pfnNativeCommand`
11011+
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
11012+
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
11013+
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP
11014+
/// + `pSyncPointWaitList == NULL && numSyncPointsInWaitList > 0`
11015+
/// + `pSyncPointWaitList != NULL && numSyncPointsInWaitList == 0`
11016+
/// - ::UR_RESULT_ERROR_INVALID_MEM_OBJECT
11017+
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
11018+
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
11019+
UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendNativeCommandExp(
11020+
/// [in] handle of the command-buffer object.
11021+
ur_exp_command_buffer_handle_t hCommandBuffer,
11022+
/// [in] function calling the native underlying API, to be executed
11023+
/// immediately.
11024+
ur_exp_command_buffer_native_command_function_t pfnNativeCommand,
11025+
/// [in][optional] data used by pfnNativeCommand
11026+
void *pData,
11027+
/// [in][optional] TODO
11028+
ur_exp_command_buffer_handle_t hChildCommandBuffer,
11029+
/// [in] The number of sync points in the provided dependency list.
11030+
uint32_t numSyncPointsInWaitList,
11031+
/// [in][optional] A list of sync points that this command depends on. May
11032+
/// be ignored if command-buffer is in-order.
11033+
const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList,
11034+
/// [out][optional] sync point associated with this command.
11035+
ur_exp_command_buffer_sync_point_t *pSyncPoint);
11036+
1098811037
///////////////////////////////////////////////////////////////////////////////
1098911038
/// @brief Submit a command-buffer for execution on a queue.
1099011039
///
@@ -11211,6 +11260,30 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferGetInfoExp(
1121111260
/// [out][optional] bytes returned in command-buffer property
1121211261
size_t *pPropSizeRet);
1121311262

11263+
///////////////////////////////////////////////////////////////////////////////
11264+
/// @brief Return platform native command-buffer handle.
11265+
///
11266+
/// @details
11267+
/// - Retrieved native handle can be used for direct interaction with the
11268+
/// native platform driver.
11269+
///
11270+
/// @returns
11271+
/// - ::UR_RESULT_SUCCESS
11272+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
11273+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
11274+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
11275+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
11276+
/// + `NULL == hCommandBuffer`
11277+
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
11278+
/// + `NULL == phNativeCommandBuffer`
11279+
/// - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
11280+
/// + If the adapter has no underlying equivalent handle.
11281+
UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferGetNativeHandleExp(
11282+
/// [in] handle of the command-buffer.
11283+
ur_exp_command_buffer_handle_t hCommandBuffer,
11284+
/// [out] a pointer to the native handle of the command-buffer.
11285+
ur_native_handle_t *phNativeCommandBuffer);
11286+
1121411287
#if !defined(__GNUC__)
1121511288
#pragma endregion
1121611289
#endif
@@ -14167,6 +14240,20 @@ typedef struct ur_command_buffer_append_usm_advise_exp_params_t {
1416714240
ur_exp_command_buffer_command_handle_t **pphCommand;
1416814241
} ur_command_buffer_append_usm_advise_exp_params_t;
1416914242

14243+
///////////////////////////////////////////////////////////////////////////////
14244+
/// @brief Function parameters for urCommandBufferAppendNativeCommandExp
14245+
/// @details Each entry is a pointer to the parameter passed to the function;
14246+
/// allowing the callback the ability to modify the parameter's value
14247+
typedef struct ur_command_buffer_append_native_command_exp_params_t {
14248+
ur_exp_command_buffer_handle_t *phCommandBuffer;
14249+
ur_exp_command_buffer_native_command_function_t *ppfnNativeCommand;
14250+
void **ppData;
14251+
ur_exp_command_buffer_handle_t *phChildCommandBuffer;
14252+
uint32_t *pnumSyncPointsInWaitList;
14253+
const ur_exp_command_buffer_sync_point_t **ppSyncPointWaitList;
14254+
ur_exp_command_buffer_sync_point_t **ppSyncPoint;
14255+
} ur_command_buffer_append_native_command_exp_params_t;
14256+
1417014257
///////////////////////////////////////////////////////////////////////////////
1417114258
/// @brief Function parameters for urCommandBufferEnqueueExp
1417214259
/// @details Each entry is a pointer to the parameter passed to the function;
@@ -14220,6 +14307,15 @@ typedef struct ur_command_buffer_get_info_exp_params_t {
1422014307
size_t **ppPropSizeRet;
1422114308
} ur_command_buffer_get_info_exp_params_t;
1422214309

14310+
///////////////////////////////////////////////////////////////////////////////
14311+
/// @brief Function parameters for urCommandBufferGetNativeHandleExp
14312+
/// @details Each entry is a pointer to the parameter passed to the function;
14313+
/// allowing the callback the ability to modify the parameter's value
14314+
typedef struct ur_command_buffer_get_native_handle_exp_params_t {
14315+
ur_exp_command_buffer_handle_t *phCommandBuffer;
14316+
ur_native_handle_t **pphNativeCommandBuffer;
14317+
} ur_command_buffer_get_native_handle_exp_params_t;
14318+
1422314319
///////////////////////////////////////////////////////////////////////////////
1422414320
/// @brief Function parameters for urUsmP2PEnablePeerAccessExp
1422514321
/// @details Each entry is a pointer to the parameter passed to the function;

‎include/ur_api_funcs.def

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,11 +181,13 @@ _UR_API(urCommandBufferAppendMemBufferReadRectExp)
181181
_UR_API(urCommandBufferAppendMemBufferFillExp)
182182
_UR_API(urCommandBufferAppendUSMPrefetchExp)
183183
_UR_API(urCommandBufferAppendUSMAdviseExp)
184+
_UR_API(urCommandBufferAppendNativeCommandExp)
184185
_UR_API(urCommandBufferEnqueueExp)
185186
_UR_API(urCommandBufferUpdateKernelLaunchExp)
186187
_UR_API(urCommandBufferUpdateSignalEventExp)
187188
_UR_API(urCommandBufferUpdateWaitEventsExp)
188189
_UR_API(urCommandBufferGetInfoExp)
190+
_UR_API(urCommandBufferGetNativeHandleExp)
189191
_UR_API(urUsmP2PEnablePeerAccessExp)
190192
_UR_API(urUsmP2PDisablePeerAccessExp)
191193
_UR_API(urUsmP2PPeerAccessGetInfoExp)

‎include/ur_ddi.h

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1590,6 +1590,15 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMAdviseExp_t)(
15901590
const ur_event_handle_t *, ur_exp_command_buffer_sync_point_t *,
15911591
ur_event_handle_t *, ur_exp_command_buffer_command_handle_t *);
15921592

1593+
///////////////////////////////////////////////////////////////////////////////
1594+
/// @brief Function-pointer for urCommandBufferAppendNativeCommandExp
1595+
typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendNativeCommandExp_t)(
1596+
ur_exp_command_buffer_handle_t,
1597+
ur_exp_command_buffer_native_command_function_t, void *,
1598+
ur_exp_command_buffer_handle_t, uint32_t,
1599+
const ur_exp_command_buffer_sync_point_t *,
1600+
ur_exp_command_buffer_sync_point_t *);
1601+
15931602
///////////////////////////////////////////////////////////////////////////////
15941603
/// @brief Function-pointer for urCommandBufferEnqueueExp
15951604
typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferEnqueueExp_t)(
@@ -1619,6 +1628,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferGetInfoExp_t)(
16191628
ur_exp_command_buffer_handle_t, ur_exp_command_buffer_info_t, size_t,
16201629
void *, size_t *);
16211630

1631+
///////////////////////////////////////////////////////////////////////////////
1632+
/// @brief Function-pointer for urCommandBufferGetNativeHandleExp
1633+
typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferGetNativeHandleExp_t)(
1634+
ur_exp_command_buffer_handle_t, ur_native_handle_t *);
1635+
16221636
///////////////////////////////////////////////////////////////////////////////
16231637
/// @brief Table of CommandBufferExp functions pointers
16241638
typedef struct ur_command_buffer_exp_dditable_t {
@@ -1639,11 +1653,13 @@ typedef struct ur_command_buffer_exp_dditable_t {
16391653
ur_pfnCommandBufferAppendMemBufferFillExp_t pfnAppendMemBufferFillExp;
16401654
ur_pfnCommandBufferAppendUSMPrefetchExp_t pfnAppendUSMPrefetchExp;
16411655
ur_pfnCommandBufferAppendUSMAdviseExp_t pfnAppendUSMAdviseExp;
1656+
ur_pfnCommandBufferAppendNativeCommandExp_t pfnAppendNativeCommandExp;
16421657
ur_pfnCommandBufferEnqueueExp_t pfnEnqueueExp;
16431658
ur_pfnCommandBufferUpdateKernelLaunchExp_t pfnUpdateKernelLaunchExp;
16441659
ur_pfnCommandBufferUpdateSignalEventExp_t pfnUpdateSignalEventExp;
16451660
ur_pfnCommandBufferUpdateWaitEventsExp_t pfnUpdateWaitEventsExp;
16461661
ur_pfnCommandBufferGetInfoExp_t pfnGetInfoExp;
1662+
ur_pfnCommandBufferGetNativeHandleExp_t pfnGetNativeHandleExp;
16471663
} ur_command_buffer_exp_dditable_t;
16481664

16491665
///////////////////////////////////////////////////////////////////////////////

‎include/ur_print.h

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3161,6 +3161,17 @@ urPrintCommandBufferAppendUsmAdviseExpParams(
31613161
const struct ur_command_buffer_append_usm_advise_exp_params_t *params,
31623162
char *buffer, const size_t buff_size, size_t *out_size);
31633163

3164+
///////////////////////////////////////////////////////////////////////////////
3165+
/// @brief Print ur_command_buffer_append_native_command_exp_params_t struct
3166+
/// @returns
3167+
/// - ::UR_RESULT_SUCCESS
3168+
/// - ::UR_RESULT_ERROR_INVALID_SIZE
3169+
/// - `buff_size < out_size`
3170+
UR_APIEXPORT ur_result_t UR_APICALL
3171+
urPrintCommandBufferAppendNativeCommandExpParams(
3172+
const struct ur_command_buffer_append_native_command_exp_params_t *params,
3173+
char *buffer, const size_t buff_size, size_t *out_size);
3174+
31643175
///////////////////////////////////////////////////////////////////////////////
31653176
/// @brief Print ur_command_buffer_enqueue_exp_params_t struct
31663177
/// @returns
@@ -3214,6 +3225,17 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferGetInfoExpParams(
32143225
const struct ur_command_buffer_get_info_exp_params_t *params, char *buffer,
32153226
const size_t buff_size, size_t *out_size);
32163227

3228+
///////////////////////////////////////////////////////////////////////////////
3229+
/// @brief Print ur_command_buffer_get_native_handle_exp_params_t struct
3230+
/// @returns
3231+
/// - ::UR_RESULT_SUCCESS
3232+
/// - ::UR_RESULT_ERROR_INVALID_SIZE
3233+
/// - `buff_size < out_size`
3234+
UR_APIEXPORT ur_result_t UR_APICALL
3235+
urPrintCommandBufferGetNativeHandleExpParams(
3236+
const struct ur_command_buffer_get_native_handle_exp_params_t *params,
3237+
char *buffer, const size_t buff_size, size_t *out_size);
3238+
32173239
///////////////////////////////////////////////////////////////////////////////
32183240
/// @brief Print ur_usm_p2p_enable_peer_access_exp_params_t struct
32193241
/// @returns

‎include/ur_print.hpp

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1177,6 +1177,12 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
11771177
case UR_FUNCTION_PHYSICAL_MEM_GET_INFO:
11781178
os << "UR_FUNCTION_PHYSICAL_MEM_GET_INFO";
11791179
break;
1180+
case UR_FUNCTION_COMMAND_BUFFER_APPEND_NATIVE_COMMAND_EXP:
1181+
os << "UR_FUNCTION_COMMAND_BUFFER_APPEND_NATIVE_COMMAND_EXP";
1182+
break;
1183+
case UR_FUNCTION_COMMAND_BUFFER_GET_NATIVE_HANDLE_EXP:
1184+
os << "UR_FUNCTION_COMMAND_BUFFER_GET_NATIVE_HANDLE_EXP";
1185+
break;
11801186
default:
11811187
os << "unknown enumerator";
11821188
break;
@@ -18618,6 +18624,52 @@ operator<<(std::ostream &os, [[maybe_unused]] const struct
1861818624
return os;
1861918625
}
1862018626

18627+
///////////////////////////////////////////////////////////////////////////////
18628+
/// @brief Print operator for the
18629+
/// ur_command_buffer_append_native_command_exp_params_t type
18630+
/// @returns
18631+
/// std::ostream &
18632+
inline std::ostream &
18633+
operator<<(std::ostream &os, [[maybe_unused]] const struct
18634+
ur_command_buffer_append_native_command_exp_params_t *params) {
18635+
18636+
os << ".hCommandBuffer = ";
18637+
18638+
ur::details::printPtr(os, *(params->phCommandBuffer));
18639+
18640+
os << ", ";
18641+
os << ".pfnNativeCommand = ";
18642+
18643+
os << reinterpret_cast<void *>(*(params->ppfnNativeCommand));
18644+
18645+
os << ", ";
18646+
os << ".pData = ";
18647+
18648+
ur::details::printPtr(os, *(params->ppData));
18649+
18650+
os << ", ";
18651+
os << ".hChildCommandBuffer = ";
18652+
18653+
ur::details::printPtr(os, *(params->phChildCommandBuffer));
18654+
18655+
os << ", ";
18656+
os << ".numSyncPointsInWaitList = ";
18657+
18658+
os << *(params->pnumSyncPointsInWaitList);
18659+
18660+
os << ", ";
18661+
os << ".pSyncPointWaitList = ";
18662+
18663+
ur::details::printPtr(os, *(params->ppSyncPointWaitList));
18664+
18665+
os << ", ";
18666+
os << ".pSyncPoint = ";
18667+
18668+
ur::details::printPtr(os, *(params->ppSyncPoint));
18669+
18670+
return os;
18671+
}
18672+
1862118673
///////////////////////////////////////////////////////////////////////////////
1862218674
/// @brief Print operator for the ur_command_buffer_enqueue_exp_params_t type
1862318675
/// @returns
@@ -18780,6 +18832,27 @@ operator<<(std::ostream &os,
1878018832
return os;
1878118833
}
1878218834

18835+
///////////////////////////////////////////////////////////////////////////////
18836+
/// @brief Print operator for the
18837+
/// ur_command_buffer_get_native_handle_exp_params_t type
18838+
/// @returns
18839+
/// std::ostream &
18840+
inline std::ostream &
18841+
operator<<(std::ostream &os, [[maybe_unused]] const struct
18842+
ur_command_buffer_get_native_handle_exp_params_t *params) {
18843+
18844+
os << ".hCommandBuffer = ";
18845+
18846+
ur::details::printPtr(os, *(params->phCommandBuffer));
18847+
18848+
os << ", ";
18849+
os << ".phNativeCommandBuffer = ";
18850+
18851+
ur::details::printPtr(os, *(params->pphNativeCommandBuffer));
18852+
18853+
return os;
18854+
}
18855+
1878318856
///////////////////////////////////////////////////////////////////////////////
1878418857
/// @brief Print operator for the ur_usm_p2p_enable_peer_access_exp_params_t
1878518858
/// type
@@ -20047,6 +20120,10 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os,
2004720120
os << (const struct ur_command_buffer_append_usm_advise_exp_params_t *)
2004820121
params;
2004920122
} break;
20123+
case UR_FUNCTION_COMMAND_BUFFER_APPEND_NATIVE_COMMAND_EXP: {
20124+
os << (const struct ur_command_buffer_append_native_command_exp_params_t *)
20125+
params;
20126+
} break;
2005020127
case UR_FUNCTION_COMMAND_BUFFER_ENQUEUE_EXP: {
2005120128
os << (const struct ur_command_buffer_enqueue_exp_params_t *)params;
2005220129
} break;
@@ -20065,6 +20142,10 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os,
2006520142
case UR_FUNCTION_COMMAND_BUFFER_GET_INFO_EXP: {
2006620143
os << (const struct ur_command_buffer_get_info_exp_params_t *)params;
2006720144
} break;
20145+
case UR_FUNCTION_COMMAND_BUFFER_GET_NATIVE_HANDLE_EXP: {
20146+
os << (const struct ur_command_buffer_get_native_handle_exp_params_t *)
20147+
params;
20148+
} break;
2006820149
case UR_FUNCTION_USM_P2P_ENABLE_PEER_ACCESS_EXP: {
2006920150
os << (const struct ur_usm_p2p_enable_peer_access_exp_params_t *)params;
2007020151
} break;

‎scripts/core/EXP-COMMAND-BUFFER.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,7 @@ Currently only the following commands are supported:
119119
* ${x}CommandBufferAppendMemBufferFillExp
120120
* ${x}CommandBufferAppendUSMPrefetchExp
121121
* ${x}CommandBufferAppendUSMAdviseExp
122+
* ${x}CommandBufferAppendNativeCommandExp
122123

123124
It is planned to eventually support any command type from the Core API which can
124125
actually be appended to the equivalent adapter native constructs.
@@ -209,6 +210,13 @@ command-buffer, before the code path returns to user code for the user to
209210
enqueue the second command-buffer. Resulting in the first command-buffer's
210211
wait node completing too early for the intended overall executing ordering.
211212

213+
Native Commands
214+
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
215+
216+
.. todo::
217+
Document ${x}CommandBufferGetNativeHandleExp and
218+
${x}CommandBufferAppendNativeCommandExp
219+
212220
Enqueueing Command-Buffers
213221
--------------------------------------------------------------------------------
214222

@@ -485,11 +493,13 @@ Functions
485493
* ${x}CommandBufferAppendMemBufferFillExp
486494
* ${x}CommandBufferAppendUSMPrefetchExp
487495
* ${x}CommandBufferAppendUSMAdviseExp
496+
* ${x}CommandBufferAppendNativeCommandExp
488497
* ${x}CommandBufferEnqueueExp
489498
* ${x}CommandBufferUpdateKernelLaunchExp
490499
* ${x}CommandBufferUpdateSignalEventExp
491500
* ${x}CommandBufferUpdateWaitEventsExp
492501
* ${x}CommandBufferGetInfoExp
502+
* ${x}CommandBufferGetNativeHandleExp
493503

494504
Changelog
495505
--------------------------------------------------------------------------------
@@ -514,6 +524,8 @@ Changelog
514524
+-----------+-------------------------------------------------------+
515525
| 1.7 | Remove command handle reference counting and querying |
516526
+-----------+-------------------------------------------------------+
527+
| 1.8 | Support native commands. |
528+
+-----------+-------------------------------------------------------+
517529

518530
Contributors
519531
--------------------------------------------------------------------------------

0 commit comments

Comments
 (0)