Rename urCommandBufferEnqueueExp to urEnqueueCommandBufferExp

The API to enqueue a closed command-buffer to a queue is defined
in the YAML as a part of the command-buffer class, but it should be
part of the enqueue class like other enqueue API extensions.

This PR updates the YAML and regenerates UR code, making the associated
changes to adapters and CTS.

Closes #2600

include/ur_api.h

@@ -423,8 +423,6 @@ typedef enum ur_function_t {
   UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP = 240,
   /// Enumerator for ::urCommandBufferAppendUSMAdviseExp
   UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 241,
-  /// Enumerator for ::urCommandBufferEnqueueExp
-  UR_FUNCTION_COMMAND_BUFFER_ENQUEUE_EXP = 242,
   /// Enumerator for ::urCommandBufferUpdateSignalEventExp
   UR_FUNCTION_COMMAND_BUFFER_UPDATE_SIGNAL_EVENT_EXP = 243,
   /// Enumerator for ::urCommandBufferUpdateWaitEventsExp
@@ -439,6 +437,8 @@ typedef enum ur_function_t {
   UR_FUNCTION_TENSOR_MAP_ENCODE_TILED_EXP = 248,
   /// Enumerator for ::urPhysicalMemGetInfo
   UR_FUNCTION_PHYSICAL_MEM_GET_INFO = 249,
+  /// Enumerator for ::urEnqueueCommandBufferExp
+  UR_FUNCTION_ENQUEUE_COMMAND_BUFFER_EXP = 250,
   /// @cond
   UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
   /// @endcond
@@ -10994,8 +10994,8 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendUSMAdviseExp(
 ///     - ::UR_RESULT_ERROR_DEVICE_LOST
 ///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
-///         + `NULL == hCommandBuffer`
 ///         + `NULL == hQueue`
+///         + `NULL == hCommandBuffer`
 ///     - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
 ///     - ::UR_RESULT_ERROR_INVALID_QUEUE
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT
@@ -11005,11 +11005,11 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendUSMAdviseExp(
 ///         + If event objects in phEventWaitList are not valid events.
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
-UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferEnqueueExp(
-    /// [in] Handle of the command-buffer object.
-    ur_exp_command_buffer_handle_t hCommandBuffer,
+UR_APIEXPORT ur_result_t UR_APICALL urEnqueueCommandBufferExp(
     /// [in] The queue to submit this command-buffer for execution.
     ur_queue_handle_t hQueue,
+    /// [in] Handle of the command-buffer object.
+    ur_exp_command_buffer_handle_t hCommandBuffer,
     /// [in] Size of the event wait list.
     uint32_t numEventsInWaitList,
     /// [in][optional][range(0, numEventsInWaitList)] pointer to a list of
@@ -13812,6 +13812,18 @@ typedef struct ur_enqueue_events_wait_with_barrier_ext_params_t {
   ur_event_handle_t **pphEvent;
 } ur_enqueue_events_wait_with_barrier_ext_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urEnqueueCommandBufferExp
+/// @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_enqueue_command_buffer_exp_params_t {
+  ur_queue_handle_t *phQueue;
+  ur_exp_command_buffer_handle_t *phCommandBuffer;
+  uint32_t *pnumEventsInWaitList;
+  const ur_event_handle_t **pphEventWaitList;
+  ur_event_handle_t **pphEvent;
+} ur_enqueue_command_buffer_exp_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urEnqueueCooperativeKernelLaunchExp
 /// @details Each entry is a pointer to the parameter passed to the function;
@@ -14491,18 +14503,6 @@ 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 urCommandBufferEnqueueExp
-/// @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_enqueue_exp_params_t {
-  ur_exp_command_buffer_handle_t *phCommandBuffer;
-  ur_queue_handle_t *phQueue;
-  uint32_t *pnumEventsInWaitList;
-  const ur_event_handle_t **pphEventWaitList;
-  ur_event_handle_t **pphEvent;
-} ur_command_buffer_enqueue_exp_params_t;
-
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urCommandBufferRetainCommandExp
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_api_funcs.def

@@ -132,6 +132,7 @@ _UR_API(urEnqueueReadHostPipe)
 _UR_API(urEnqueueWriteHostPipe)
 _UR_API(urEnqueueEventsWaitWithBarrierExt)
 _UR_API(urEnqueueKernelLaunchCustomExp)
+_UR_API(urEnqueueCommandBufferExp)
 _UR_API(urEnqueueCooperativeKernelLaunchExp)
 _UR_API(urEnqueueTimestampRecordingExp)
 _UR_API(urEnqueueNativeCommandExp)
@@ -181,7 +182,6 @@ _UR_API(urCommandBufferAppendMemBufferReadRectExp)
 _UR_API(urCommandBufferAppendMemBufferFillExp)
 _UR_API(urCommandBufferAppendUSMPrefetchExp)
 _UR_API(urCommandBufferAppendUSMAdviseExp)
-_UR_API(urCommandBufferEnqueueExp)
 _UR_API(urCommandBufferRetainCommandExp)
 _UR_API(urCommandBufferReleaseCommandExp)
 _UR_API(urCommandBufferUpdateKernelLaunchExp)

include/ur_ddi.h

@@ -1117,6 +1117,12 @@ typedef ur_result_t(UR_APICALL *ur_pfnEnqueueKernelLaunchCustomExp_t)(
     const size_t *, const size_t *, uint32_t, const ur_exp_launch_property_t *,
     uint32_t, const ur_event_handle_t *, ur_event_handle_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urEnqueueCommandBufferExp
+typedef ur_result_t(UR_APICALL *ur_pfnEnqueueCommandBufferExp_t)(
+    ur_queue_handle_t, ur_exp_command_buffer_handle_t, uint32_t,
+    const ur_event_handle_t *, ur_event_handle_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urEnqueueCooperativeKernelLaunchExp
 typedef ur_result_t(UR_APICALL *ur_pfnEnqueueCooperativeKernelLaunchExp_t)(
@@ -1142,6 +1148,7 @@ typedef ur_result_t(UR_APICALL *ur_pfnEnqueueNativeCommandExp_t)(
 /// @brief Table of EnqueueExp functions pointers
 typedef struct ur_enqueue_exp_dditable_t {
   ur_pfnEnqueueKernelLaunchCustomExp_t pfnKernelLaunchCustomExp;
+  ur_pfnEnqueueCommandBufferExp_t pfnCommandBufferExp;
   ur_pfnEnqueueCooperativeKernelLaunchExp_t pfnCooperativeKernelLaunchExp;
   ur_pfnEnqueueTimestampRecordingExp_t pfnTimestampRecordingExp;
   ur_pfnEnqueueNativeCommandExp_t pfnNativeCommandExp;
@@ -1590,12 +1597,6 @@ 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 urCommandBufferEnqueueExp
-typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferEnqueueExp_t)(
-    ur_exp_command_buffer_handle_t, ur_queue_handle_t, uint32_t,
-    const ur_event_handle_t *, ur_event_handle_t *);
-
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urCommandBufferRetainCommandExp
 typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferRetainCommandExp_t)(
@@ -1655,7 +1656,6 @@ typedef struct ur_command_buffer_exp_dditable_t {
   ur_pfnCommandBufferAppendMemBufferFillExp_t pfnAppendMemBufferFillExp;
   ur_pfnCommandBufferAppendUSMPrefetchExp_t pfnAppendUSMPrefetchExp;
   ur_pfnCommandBufferAppendUSMAdviseExp_t pfnAppendUSMAdviseExp;
-  ur_pfnCommandBufferEnqueueExp_t pfnEnqueueExp;
   ur_pfnCommandBufferRetainCommandExp_t pfnRetainCommandExp;
   ur_pfnCommandBufferReleaseCommandExp_t pfnReleaseCommandExp;
   ur_pfnCommandBufferUpdateKernelLaunchExp_t pfnUpdateKernelLaunchExp;

include/ur_print.h

@@ -2676,6 +2676,16 @@ urPrintEnqueueEventsWaitWithBarrierExtParams(
     const struct ur_enqueue_events_wait_with_barrier_ext_params_t *params,
     char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_enqueue_command_buffer_exp_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintEnqueueCommandBufferExpParams(
+    const struct ur_enqueue_command_buffer_exp_params_t *params, char *buffer,
+    const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_enqueue_cooperative_kernel_launch_exp_params_t struct
 /// @returns
@@ -3211,16 +3221,6 @@ 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_enqueue_exp_params_t struct
-/// @returns
-///     - ::UR_RESULT_SUCCESS
-///     - ::UR_RESULT_ERROR_INVALID_SIZE
-///         - `buff_size < out_size`
-UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferEnqueueExpParams(
-    const struct ur_command_buffer_enqueue_exp_params_t *params, char *buffer,
-    const size_t buff_size, size_t *out_size);
-
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_command_buffer_retain_command_exp_params_t struct
 /// @returns

include/ur_print.hpp

@@ -1200,9 +1200,6 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
   case UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP:
     os << "UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP";
     break;
-  case UR_FUNCTION_COMMAND_BUFFER_ENQUEUE_EXP:
-    os << "UR_FUNCTION_COMMAND_BUFFER_ENQUEUE_EXP";
-    break;
   case UR_FUNCTION_COMMAND_BUFFER_UPDATE_SIGNAL_EVENT_EXP:
     os << "UR_FUNCTION_COMMAND_BUFFER_UPDATE_SIGNAL_EVENT_EXP";
     break;
@@ -1224,6 +1221,9 @@ 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_ENQUEUE_COMMAND_BUFFER_EXP:
+    os << "UR_FUNCTION_ENQUEUE_COMMAND_BUFFER_EXP";
+    break;
   default:
     os << "unknown enumerator";
     break;
@@ -16693,6 +16693,53 @@ operator<<(std::ostream &os, [[maybe_unused]] const struct
   return os;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_enqueue_command_buffer_exp_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &
+operator<<(std::ostream &os,
+           [[maybe_unused]] const struct ur_enqueue_command_buffer_exp_params_t
+               *params) {
+
+  os << ".hQueue = ";
+
+  ur::details::printPtr(os, *(params->phQueue));
+
+  os << ", ";
+  os << ".hCommandBuffer = ";
+
+  ur::details::printPtr(os, *(params->phCommandBuffer));
+
+  os << ", ";
+  os << ".numEventsInWaitList = ";
+
+  os << *(params->pnumEventsInWaitList);
+
+  os << ", ";
+  os << ".phEventWaitList = ";
+  ur::details::printPtr(
+      os, reinterpret_cast<const void *>(*(params->pphEventWaitList)));
+  if (*(params->pphEventWaitList) != NULL) {
+    os << " {";
+    for (size_t i = 0; i < *params->pnumEventsInWaitList; ++i) {
+      if (i != 0) {
+        os << ", ";
+      }
+
+      ur::details::printPtr(os, (*(params->pphEventWaitList))[i]);
+    }
+    os << "}";
+  }
+
+  os << ", ";
+  os << ".phEvent = ";
+
+  ur::details::printPtr(os, *(params->pphEvent));
+
+  return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the
 /// ur_enqueue_cooperative_kernel_launch_exp_params_t type
@@ -19123,53 +19170,6 @@ operator<<(std::ostream &os, [[maybe_unused]] const struct
   return os;
 }
 
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Print operator for the ur_command_buffer_enqueue_exp_params_t type
-/// @returns
-///     std::ostream &
-inline std::ostream &
-operator<<(std::ostream &os,
-           [[maybe_unused]] const struct ur_command_buffer_enqueue_exp_params_t
-               *params) {
-
-  os << ".hCommandBuffer = ";
-
-  ur::details::printPtr(os, *(params->phCommandBuffer));
-
-  os << ", ";
-  os << ".hQueue = ";
-
-  ur::details::printPtr(os, *(params->phQueue));
-
-  os << ", ";
-  os << ".numEventsInWaitList = ";
-
-  os << *(params->pnumEventsInWaitList);
-
-  os << ", ";
-  os << ".phEventWaitList = ";
-  ur::details::printPtr(
-      os, reinterpret_cast<const void *>(*(params->pphEventWaitList)));
-  if (*(params->pphEventWaitList) != NULL) {
-    os << " {";
-    for (size_t i = 0; i < *params->pnumEventsInWaitList; ++i) {
-      if (i != 0) {
-        os << ", ";
-      }
-
-      ur::details::printPtr(os, (*(params->pphEventWaitList))[i]);
-    }
-    os << "}";
-  }
-
-  os << ", ";
-  os << ".phEvent = ";
-
-  ur::details::printPtr(os, *(params->pphEvent));
-
-  return os;
-}
-
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_command_buffer_retain_command_exp_params_t
 /// type
@@ -20626,6 +20626,9 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os,
     os << (const struct ur_enqueue_events_wait_with_barrier_ext_params_t *)
             params;
   } break;
+  case UR_FUNCTION_ENQUEUE_COMMAND_BUFFER_EXP: {
+    os << (const struct ur_enqueue_command_buffer_exp_params_t *)params;
+  } break;
   case UR_FUNCTION_ENQUEUE_COOPERATIVE_KERNEL_LAUNCH_EXP: {
     os << (const struct ur_enqueue_cooperative_kernel_launch_exp_params_t *)
             params;
@@ -20800,9 +20803,6 @@ 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_ENQUEUE_EXP: {
-    os << (const struct ur_command_buffer_enqueue_exp_params_t *)params;
-  } break;
   case UR_FUNCTION_COMMAND_BUFFER_RETAIN_COMMAND_EXP: {
     os << (const struct ur_command_buffer_retain_command_exp_params_t *)params;
   } break;

scripts/core/EXP-COMMAND-BUFFER.rst

@@ -184,7 +184,7 @@ specific graph command-buffer execution is required this ordering must be
 enforced by the user to ensure there is only a single command-buffer execution
 in flight when using these command signal events.
 
-When a user calls ${x}CommandBufferEnqueueExp all the signal events returned
+When a user calls ${x}EnqueueCommandBufferExp all the signal events returned
 from the individual commands in the command-buffer are synchronously reset to
 a non-complete state prior to the asynchronous commands beginning.
 
@@ -221,8 +221,8 @@ enqueued or executed simultaneously, and submissions may be serialized.
 .. parsed-literal::
     ${x}_event_handle_t executionEvent;
 
-    ${x}CommandBufferEnqueueExp(hCommandBuffer, hQueue, 0, nullptr,
-                              &executionEvent);
+    ${x}EnqueueCommandBufferExp(hQueue, hCommandBuffer, 0, nullptr,
+                                &executionEvent);
 
 
 Updating Command-Buffer Commands
@@ -384,7 +384,7 @@ ${x}CommandBufferUpdateSignalEventExp there must also have been a non-null
     ${x}CommandBufferFinalizeExp(hCommandBuffer);
 
     // Enqueue command-buffer
-    ${x}CommandBufferEnqueueExp(hCommandBuffer, hQueue, 0, nullptr, nullptr);
+    ${x}EnqueueCommandBufferExp(hQueue, hCommandBuffer, 0, nullptr, nullptr);
 
     // Wait for command-buffer to finish
     ${x}QueueFinish(hQueue);
@@ -437,7 +437,6 @@ Enums
     * ${X}_FUNCTION_COMMAND_BUFFER_RELEASE_EXP
     * ${X}_FUNCTION_COMMAND_BUFFER_FINALIZE_EXP
     * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_KERNEL_LAUNCH_EXP
-    * ${X}_FUNCTION_COMMAND_BUFFER_ENQUEUE_EXP
     * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_USM_MEMCPY_EXP
     * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_USM_FILL_EXP
     * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_COPY_EXP
@@ -450,6 +449,7 @@ Enums
     * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP
     * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP
     * ${X}_FUNCTION_COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_EXP
+    * ${X}_FUNCTION_ENQUEUE_COMMAND_BUFFER_EXP
 * ${x}_exp_command_buffer_info_t
     * ${X}_EXP_COMMAND_BUFFER_INFO_REFERENCE_COUNT
     * ${X}_EXP_COMMAND_BUFFER_INFO_DESCRIPTOR
@@ -485,14 +485,14 @@ Functions
 * ${x}CommandBufferAppendMemBufferFillExp
 * ${x}CommandBufferAppendUSMPrefetchExp
 * ${x}CommandBufferAppendUSMAdviseExp
-* ${x}CommandBufferEnqueueExp
 * ${x}CommandBufferRetainCommandExp
 * ${x}CommandBufferReleaseCommandExp
 * ${x}CommandBufferUpdateKernelLaunchExp
 * ${x}CommandBufferUpdateSignalEventExp
 * ${x}CommandBufferUpdateWaitEventsExp
 * ${x}CommandBufferGetInfoExp
 * ${x}CommandBufferCommandGetInfoExp
+* ${x}EnqueueCommandBufferExp
 
 Changelog
 --------------------------------------------------------------------------------
@@ -515,6 +515,8 @@ Changelog
 +-----------+-------------------------------------------------------+
 | 1.6       | Command level synchronization with event objects      |
 +-----------+-------------------------------------------------------+
+| 1.7       | Rename enqueue API to `urEnqueueCommandBufferEXP      |
++-----------+-------------------------------------------------------+
 
 Contributors
 --------------------------------------------------------------------------------