Add event update to command-buffers.

Expand the command-buffer experimental feature API so that
it can be used to implement [SYCL-Graph dynamic
events](reble/llvm#372).

This involves extending each command append entry-point to
include the following extra parameters:
* An output `ur_exp_command_buffer_command_handle_t`.
* An Input `ur_event_handle_t` event wait-list of dependent events.
* An output `ur_event_handle_t` event that is signaled when the command
  completes its next execution.

New entry-points are also added to update the wait-list and signal event
parameters of commands:
* `urCommandBufferUpdateSignalEventExp`
* `urCommandBufferUpdateWaitEventsExp`

For this commit the implementation of these new APIs is stubbed out.
Implementing the APIs for at least one adapter and adding new UR
CTS tests will be follow-on work.

Author: Ewan Crawford

include/ur_api.h

@@ -1922,7 +1922,10 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendKernelLaunchExp_t)(
     const size_t *,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
+    uint32_t,
+    const ur_event_handle_t *,
     ur_exp_command_buffer_sync_point_t *,
+    ur_event_handle_t *,
     ur_exp_command_buffer_command_handle_t *);
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -1934,7 +1937,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMMemcpyExp_t)(
     size_t,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
-    ur_exp_command_buffer_sync_point_t *);
+    uint32_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 urCommandBufferAppendUSMFillExp
@@ -1946,7 +1953,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMFillExp_t)(
     size_t,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
-    ur_exp_command_buffer_sync_point_t *);
+    uint32_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 urCommandBufferAppendMemBufferCopyExp
@@ -1959,7 +1970,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferCopyExp_t)(
     size_t,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
-    ur_exp_command_buffer_sync_point_t *);
+    uint32_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 urCommandBufferAppendMemBufferWriteExp
@@ -1971,7 +1986,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferWriteExp_t)(
     const void *,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
-    ur_exp_command_buffer_sync_point_t *);
+    uint32_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 urCommandBufferAppendMemBufferReadExp
@@ -1983,7 +2002,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferReadExp_t)(
     void *,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
-    ur_exp_command_buffer_sync_point_t *);
+    uint32_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 urCommandBufferAppendMemBufferCopyRectExp
@@ -2000,7 +2023,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferCopyRectExp_t)
     size_t,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
-    ur_exp_command_buffer_sync_point_t *);
+    uint32_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 urCommandBufferAppendMemBufferWriteRectExp
@@ -2017,7 +2044,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferWriteRectExp_t
     void *,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
-    ur_exp_command_buffer_sync_point_t *);
+    uint32_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 urCommandBufferAppendMemBufferReadRectExp
@@ -2034,7 +2065,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferReadRectExp_t)
     void *,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
-    ur_exp_command_buffer_sync_point_t *);
+    uint32_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 urCommandBufferAppendMemBufferFillExp
@@ -2047,7 +2082,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferFillExp_t)(
     size_t,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
-    ur_exp_command_buffer_sync_point_t *);
+    uint32_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 urCommandBufferAppendUSMPrefetchExp
@@ -2058,7 +2097,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMPrefetchExp_t)(
     ur_usm_migration_flags_t,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
-    ur_exp_command_buffer_sync_point_t *);
+    uint32_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 urCommandBufferAppendUSMAdviseExp
@@ -2069,7 +2112,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMAdviseExp_t)(
     ur_usm_advice_flags_t,
     uint32_t,
     const ur_exp_command_buffer_sync_point_t *,
-    ur_exp_command_buffer_sync_point_t *);
+    uint32_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
@@ -2096,6 +2143,19 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferUpdateKernelLaunchExp_t)(
     ur_exp_command_buffer_command_handle_t,
     const ur_exp_command_buffer_update_kernel_launch_desc_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urCommandBufferUpdateSignalEventExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferUpdateSignalEventExp_t)(
+    ur_exp_command_buffer_command_handle_t,
+    ur_event_handle_t *);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urCommandBufferUpdateWaitEventsExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferUpdateWaitEventsExp_t)(
+    ur_exp_command_buffer_command_handle_t,
+    uint32_t,
+    const ur_event_handle_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urCommandBufferGetInfoExp
 typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferGetInfoExp_t)(
@@ -2137,6 +2197,8 @@ typedef struct ur_command_buffer_exp_dditable_t {
     ur_pfnCommandBufferRetainCommandExp_t pfnRetainCommandExp;
     ur_pfnCommandBufferReleaseCommandExp_t pfnReleaseCommandExp;
     ur_pfnCommandBufferUpdateKernelLaunchExp_t pfnUpdateKernelLaunchExp;
+    ur_pfnCommandBufferUpdateSignalEventExp_t pfnUpdateSignalEventExp;
+    ur_pfnCommandBufferUpdateWaitEventsExp_t pfnUpdateWaitEventsExp;
     ur_pfnCommandBufferGetInfoExp_t pfnGetInfoExp;
     ur_pfnCommandBufferCommandGetInfoExp_t pfnCommandGetInfoExp;
 } ur_command_buffer_exp_dditable_t;

include/ur_ddi.h

@@ -2442,6 +2442,22 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferReleaseCommandExpParams(
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferUpdateKernelLaunchExpParams(const struct ur_command_buffer_update_kernel_launch_exp_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_command_buffer_update_signal_event_exp_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferUpdateSignalEventExpParams(const struct ur_command_buffer_update_signal_event_exp_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_command_buffer_update_wait_events_exp_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferUpdateWaitEventsExpParams(const struct ur_command_buffer_update_wait_events_exp_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_command_buffer_get_info_exp_params_t struct
 /// @returns