Add Native Command support to command-buffer

Enables support for using native commands inside a command-buffer.

include/ur_api.h

@@ -429,6 +429,10 @@ typedef enum ur_function_t {
   UR_FUNCTION_ENQUEUE_EVENTS_WAIT_WITH_BARRIER_EXT = 246,
   /// Enumerator for ::urPhysicalMemGetInfo
   UR_FUNCTION_PHYSICAL_MEM_GET_INFO = 249,
+  /// Enumerator for ::urCommandBufferAppendNativeCommandExp
+  UR_FUNCTION_COMMAND_BUFFER_APPEND_NATIVE_COMMAND_EXP = 250,
+  /// Enumerator for ::urCommandBufferGetNativeHandleExp
+  UR_FUNCTION_COMMAND_BUFFER_GET_NATIVE_HANDLE_EXP = 252,
   /// @cond
   UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
   /// @endcond
@@ -10985,6 +10989,51 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendUSMAdviseExp(
     /// [out][optional] Handle to this command.
     ur_exp_command_buffer_command_handle_t *phCommand);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function adding work through the native API to be executed
+///        immediately.
+typedef void (*ur_exp_command_buffer_native_command_function_t)(
+    /// [in][out] pointer to data to be passed to callback
+    void *pUserData);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Append nodes through a native backend API
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hCommandBuffer`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pfnNativeCommand`
+///     - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
+///     - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
+///     - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP
+///         + `pSyncPointWaitList == NULL && numSyncPointsInWaitList > 0`
+///         + `pSyncPointWaitList != NULL && numSyncPointsInWaitList == 0`
+///     - ::UR_RESULT_ERROR_INVALID_MEM_OBJECT
+///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
+///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
+UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendNativeCommandExp(
+    /// [in] handle of the command-buffer object.
+    ur_exp_command_buffer_handle_t hCommandBuffer,
+    /// [in] function calling the native underlying API, to be executed
+    /// immediately.
+    ur_exp_command_buffer_native_command_function_t pfnNativeCommand,
+    /// [in][optional] data used by pfnNativeCommand
+    void *pData,
+    /// [in][optional] TODO
+    ur_exp_command_buffer_handle_t hChildCommandBuffer,
+    /// [in] The number of sync points in the provided dependency list.
+    uint32_t numSyncPointsInWaitList,
+    /// [in][optional] A list of sync points that this command depends on. May
+    /// be ignored if command-buffer is in-order.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList,
+    /// [out][optional] sync point associated with this command.
+    ur_exp_command_buffer_sync_point_t *pSyncPoint);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Submit a command-buffer for execution on a queue.
 ///
@@ -11211,6 +11260,30 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferGetInfoExp(
     /// [out][optional] bytes returned in command-buffer property
     size_t *pPropSizeRet);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Return platform native command-buffer handle.
+///
+/// @details
+///     - Retrieved native handle can be used for direct interaction with the
+///       native platform driver.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hCommandBuffer`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == phNativeCommandBuffer`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
+UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferGetNativeHandleExp(
+    /// [in] handle of the command-buffer.
+    ur_exp_command_buffer_handle_t hCommandBuffer,
+    /// [out] a pointer to the native handle of the command-buffer.
+    ur_native_handle_t *phNativeCommandBuffer);
+
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
@@ -14167,6 +14240,20 @@ typedef struct ur_command_buffer_append_usm_advise_exp_params_t {
   ur_exp_command_buffer_command_handle_t **pphCommand;
 } ur_command_buffer_append_usm_advise_exp_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urCommandBufferAppendNativeCommandExp
+/// @details Each entry is a pointer to the parameter passed to the function;
+///     allowing the callback the ability to modify the parameter's value
+typedef struct ur_command_buffer_append_native_command_exp_params_t {
+  ur_exp_command_buffer_handle_t *phCommandBuffer;
+  ur_exp_command_buffer_native_command_function_t *ppfnNativeCommand;
+  void **ppData;
+  ur_exp_command_buffer_handle_t *phChildCommandBuffer;
+  uint32_t *pnumSyncPointsInWaitList;
+  const ur_exp_command_buffer_sync_point_t **ppSyncPointWaitList;
+  ur_exp_command_buffer_sync_point_t **ppSyncPoint;
+} ur_command_buffer_append_native_command_exp_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urCommandBufferEnqueueExp
 /// @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 {
   size_t **ppPropSizeRet;
 } ur_command_buffer_get_info_exp_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urCommandBufferGetNativeHandleExp
+/// @details Each entry is a pointer to the parameter passed to the function;
+///     allowing the callback the ability to modify the parameter's value
+typedef struct ur_command_buffer_get_native_handle_exp_params_t {
+  ur_exp_command_buffer_handle_t *phCommandBuffer;
+  ur_native_handle_t **pphNativeCommandBuffer;
+} ur_command_buffer_get_native_handle_exp_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urUsmP2PEnablePeerAccessExp
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_api_funcs.def

@@ -181,11 +181,13 @@ _UR_API(urCommandBufferAppendMemBufferReadRectExp)
 _UR_API(urCommandBufferAppendMemBufferFillExp)
 _UR_API(urCommandBufferAppendUSMPrefetchExp)
 _UR_API(urCommandBufferAppendUSMAdviseExp)
+_UR_API(urCommandBufferAppendNativeCommandExp)
 _UR_API(urCommandBufferEnqueueExp)
 _UR_API(urCommandBufferUpdateKernelLaunchExp)
 _UR_API(urCommandBufferUpdateSignalEventExp)
 _UR_API(urCommandBufferUpdateWaitEventsExp)
 _UR_API(urCommandBufferGetInfoExp)
+_UR_API(urCommandBufferGetNativeHandleExp)
 _UR_API(urUsmP2PEnablePeerAccessExp)
 _UR_API(urUsmP2PDisablePeerAccessExp)
 _UR_API(urUsmP2PPeerAccessGetInfoExp)

include/ur_ddi.h

@@ -1590,6 +1590,15 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMAdviseExp_t)(
     const ur_event_handle_t *, ur_exp_command_buffer_sync_point_t *,
     ur_event_handle_t *, ur_exp_command_buffer_command_handle_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urCommandBufferAppendNativeCommandExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendNativeCommandExp_t)(
+    ur_exp_command_buffer_handle_t,
+    ur_exp_command_buffer_native_command_function_t, void *,
+    ur_exp_command_buffer_handle_t, uint32_t,
+    const ur_exp_command_buffer_sync_point_t *,
+    ur_exp_command_buffer_sync_point_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urCommandBufferEnqueueExp
 typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferEnqueueExp_t)(
@@ -1619,6 +1628,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferGetInfoExp_t)(
     ur_exp_command_buffer_handle_t, ur_exp_command_buffer_info_t, size_t,
     void *, size_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urCommandBufferGetNativeHandleExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferGetNativeHandleExp_t)(
+    ur_exp_command_buffer_handle_t, ur_native_handle_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Table of CommandBufferExp functions pointers
 typedef struct ur_command_buffer_exp_dditable_t {
@@ -1639,11 +1653,13 @@ typedef struct ur_command_buffer_exp_dditable_t {
   ur_pfnCommandBufferAppendMemBufferFillExp_t pfnAppendMemBufferFillExp;
   ur_pfnCommandBufferAppendUSMPrefetchExp_t pfnAppendUSMPrefetchExp;
   ur_pfnCommandBufferAppendUSMAdviseExp_t pfnAppendUSMAdviseExp;
+  ur_pfnCommandBufferAppendNativeCommandExp_t pfnAppendNativeCommandExp;
   ur_pfnCommandBufferEnqueueExp_t pfnEnqueueExp;
   ur_pfnCommandBufferUpdateKernelLaunchExp_t pfnUpdateKernelLaunchExp;
   ur_pfnCommandBufferUpdateSignalEventExp_t pfnUpdateSignalEventExp;
   ur_pfnCommandBufferUpdateWaitEventsExp_t pfnUpdateWaitEventsExp;
   ur_pfnCommandBufferGetInfoExp_t pfnGetInfoExp;
+  ur_pfnCommandBufferGetNativeHandleExp_t pfnGetNativeHandleExp;
 } ur_command_buffer_exp_dditable_t;
 
 ///////////////////////////////////////////////////////////////////////////////

include/ur_print.h

@@ -3161,6 +3161,17 @@ urPrintCommandBufferAppendUsmAdviseExpParams(
     const struct ur_command_buffer_append_usm_advise_exp_params_t *params,
     char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_command_buffer_append_native_command_exp_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL
+urPrintCommandBufferAppendNativeCommandExpParams(
+    const struct ur_command_buffer_append_native_command_exp_params_t *params,
+    char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_command_buffer_enqueue_exp_params_t struct
 /// @returns
@@ -3214,6 +3225,17 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferGetInfoExpParams(
     const struct ur_command_buffer_get_info_exp_params_t *params, char *buffer,
     const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_command_buffer_get_native_handle_exp_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL
+urPrintCommandBufferGetNativeHandleExpParams(
+    const struct ur_command_buffer_get_native_handle_exp_params_t *params,
+    char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_usm_p2p_enable_peer_access_exp_params_t struct
 /// @returns

include/ur_print.hpp

@@ -1177,6 +1177,12 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
   case UR_FUNCTION_PHYSICAL_MEM_GET_INFO:
     os << "UR_FUNCTION_PHYSICAL_MEM_GET_INFO";
     break;
+  case UR_FUNCTION_COMMAND_BUFFER_APPEND_NATIVE_COMMAND_EXP:
+    os << "UR_FUNCTION_COMMAND_BUFFER_APPEND_NATIVE_COMMAND_EXP";
+    break;
+  case UR_FUNCTION_COMMAND_BUFFER_GET_NATIVE_HANDLE_EXP:
+    os << "UR_FUNCTION_COMMAND_BUFFER_GET_NATIVE_HANDLE_EXP";
+    break;
   default:
     os << "unknown enumerator";
     break;
@@ -18618,6 +18624,52 @@ operator<<(std::ostream &os, [[maybe_unused]] const struct
   return os;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the
+/// ur_command_buffer_append_native_command_exp_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &
+operator<<(std::ostream &os, [[maybe_unused]] const struct
+           ur_command_buffer_append_native_command_exp_params_t *params) {
+
+  os << ".hCommandBuffer = ";
+
+  ur::details::printPtr(os, *(params->phCommandBuffer));
+
+  os << ", ";
+  os << ".pfnNativeCommand = ";
+
+  os << reinterpret_cast<void *>(*(params->ppfnNativeCommand));
+
+  os << ", ";
+  os << ".pData = ";
+
+  ur::details::printPtr(os, *(params->ppData));
+
+  os << ", ";
+  os << ".hChildCommandBuffer = ";
+
+  ur::details::printPtr(os, *(params->phChildCommandBuffer));
+
+  os << ", ";
+  os << ".numSyncPointsInWaitList = ";
+
+  os << *(params->pnumSyncPointsInWaitList);
+
+  os << ", ";
+  os << ".pSyncPointWaitList = ";
+
+  ur::details::printPtr(os, *(params->ppSyncPointWaitList));
+
+  os << ", ";
+  os << ".pSyncPoint = ";
+
+  ur::details::printPtr(os, *(params->ppSyncPoint));
+
+  return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_command_buffer_enqueue_exp_params_t type
 /// @returns
@@ -18780,6 +18832,27 @@ operator<<(std::ostream &os,
   return os;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the
+/// ur_command_buffer_get_native_handle_exp_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &
+operator<<(std::ostream &os, [[maybe_unused]] const struct
+           ur_command_buffer_get_native_handle_exp_params_t *params) {
+
+  os << ".hCommandBuffer = ";
+
+  ur::details::printPtr(os, *(params->phCommandBuffer));
+
+  os << ", ";
+  os << ".phNativeCommandBuffer = ";
+
+  ur::details::printPtr(os, *(params->pphNativeCommandBuffer));
+
+  return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_usm_p2p_enable_peer_access_exp_params_t
 /// type
@@ -20047,6 +20120,10 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os,
     os << (const struct ur_command_buffer_append_usm_advise_exp_params_t *)
             params;
   } break;
+  case UR_FUNCTION_COMMAND_BUFFER_APPEND_NATIVE_COMMAND_EXP: {
+    os << (const struct ur_command_buffer_append_native_command_exp_params_t *)
+            params;
+  } break;
   case UR_FUNCTION_COMMAND_BUFFER_ENQUEUE_EXP: {
     os << (const struct ur_command_buffer_enqueue_exp_params_t *)params;
   } break;
@@ -20065,6 +20142,10 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os,
   case UR_FUNCTION_COMMAND_BUFFER_GET_INFO_EXP: {
     os << (const struct ur_command_buffer_get_info_exp_params_t *)params;
   } break;
+  case UR_FUNCTION_COMMAND_BUFFER_GET_NATIVE_HANDLE_EXP: {
+    os << (const struct ur_command_buffer_get_native_handle_exp_params_t *)
+            params;
+  } break;
   case UR_FUNCTION_USM_P2P_ENABLE_PEER_ACCESS_EXP: {
     os << (const struct ur_usm_p2p_enable_peer_access_exp_params_t *)params;
   } break;

scripts/core/EXP-COMMAND-BUFFER.rst

@@ -490,6 +490,7 @@ Functions
 * ${x}CommandBufferUpdateSignalEventExp
 * ${x}CommandBufferUpdateWaitEventsExp
 * ${x}CommandBufferGetInfoExp
+* ${x}CommandBufferGetNativeHandleExp
 
 Changelog
 --------------------------------------------------------------------------------