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

@@ -1921,7 +1921,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 *);
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -1933,7 +1936,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
@@ -1945,7 +1952,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
@@ -1958,7 +1969,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
@@ -1970,7 +1985,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
@@ -1982,7 +2001,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
@@ -1999,7 +2022,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
@@ -2016,7 +2043,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
@@ -2033,7 +2064,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
@@ -2046,7 +2081,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
@@ -2057,7 +2096,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
@@ -2068,7 +2111,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
@@ -2095,6 +2142,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)(
@@ -2136,6 +2196,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

@@ -2426,6 +2426,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