[SYCL][UR] Add reusable events

unified-runtime/include/unified-runtime/ur_api.h

@@ -512,6 +512,8 @@ typedef enum ur_function_t {
   UR_FUNCTION_QUEUE_GET_GRAPH_EXP = 314,
   /// Enumerator for ::urGraphSetDestructionCallbackExp
   UR_FUNCTION_GRAPH_SET_DESTRUCTION_CALLBACK_EXP = 315,
+  /// Enumerator for ::urEventCreateExp
+  UR_FUNCTION_EVENT_CREATE_EXP = 316,
   /// @cond
   UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
   /// @endcond
@@ -631,6 +633,10 @@ typedef enum ur_structure_type_t {
   UR_STRUCTURE_TYPE_EXP_ENQUEUE_NATIVE_COMMAND_PROPERTIES = 0x3000,
   /// ::ur_exp_enqueue_ext_properties_t
   UR_STRUCTURE_TYPE_EXP_ENQUEUE_EXT_PROPERTIES = 0x4000,
+  /// ::ur_exp_event_create_properties_t
+  UR_STRUCTURE_TYPE_EXP_EVENT_CREATE_PROPERTIES = 0x4001,
+  /// ::ur_exp_enqueue_signal_event_properties_t
+  UR_STRUCTURE_TYPE_EXP_ENQUEUE_SIGNAL_EVENT_PROPERTIES = 0x4002,
   /// ::ur_exp_kernel_arg_properties_t
   UR_STRUCTURE_TYPE_EXP_KERNEL_ARG_PROPERTIES = 0x5000,
   /// ::ur_exp_host_task_properties_t
@@ -2504,6 +2510,12 @@ typedef enum ur_device_info_t {
   /// [::ur_bool_t] returns true if the device supports inter-process
   /// communicable memory handles
   UR_DEVICE_INFO_IPC_MEMORY_SUPPORT_EXP = 0x2023,
+  /// [::ur_bool_t] returns true if the device supports reusable events
+  /// created with ::urEventCreateExp.
+  UR_DEVICE_INFO_REUSABLE_EVENTS_EXP = 0x2024,
+  /// [::ur_bool_t] returns true if the device supports profiling timestamps
+  /// for reusable events created with ::urEventCreateExp.
+  UR_DEVICE_INFO_REUSABLE_EVENTS_PROFILING_EXP = 0x2025,
   /// [::ur_bool_t] returns true if the device supports enqueueing of
   /// allocations and frees.
   UR_DEVICE_INFO_ASYNC_USM_ALLOCATIONS_SUPPORT_EXP = 0x2050,
@@ -13649,6 +13661,107 @@ UR_APIEXPORT ur_result_t UR_APICALL urEnqueueNativeCommandExp(
     /// array.
     ur_event_handle_t *phEvent);
 
+#if !defined(__GNUC__)
+#pragma endregion
+#endif
+// Intel 'oneAPI' Unified Runtime Experimental API for reusable events
+#if !defined(__GNUC__)
+#pragma region reusable_events_(experimental)
+#endif
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Flags for creating a reusable event.
+typedef uint32_t ur_exp_event_create_flags_t;
+typedef enum ur_exp_event_create_flag_t {
+  /// Enables profiling timestamps for the event.
+  UR_EXP_EVENT_CREATE_FLAG_PROFILING_ENABLE = UR_BIT(0),
+  /// @cond
+  UR_EXP_EVENT_CREATE_FLAG_FORCE_UINT32 = 0x7fffffff
+  /// @endcond
+
+} ur_exp_event_create_flag_t;
+/// @brief Bit Mask for validating ur_exp_event_create_flags_t
+#define UR_EXP_EVENT_CREATE_FLAGS_MASK 0xfffffffe
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Properties for ::urEventCreateExp.
+typedef struct ur_exp_event_create_properties_t {
+  /// [in] type of this structure, must be
+  /// ::UR_STRUCTURE_TYPE_EXP_EVENT_CREATE_PROPERTIES
+  ur_structure_type_t stype;
+  /// [in,out][optional] pointer to extension-specific structure
+  void *pNext;
+  /// [in] event creation flags
+  ur_exp_event_create_flags_t flags;
+
+} ur_exp_event_create_properties_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Extended enqueue properties for specifying a pre-existing event to
+///        signal. This structure may be passed via the pNext chain of
+///        ::ur_exp_enqueue_ext_properties_t when calling
+///        ::urEnqueueEventsWaitWithBarrierExt. When present, the implementation
+///        signals hSignalEvent on completion instead of allocating a new event.
+///        The handle value pointed to by hSignalEvent is never overwritten by
+///        the implementation.
+typedef struct ur_exp_enqueue_signal_event_properties_t {
+  /// [in] type of this structure, must be
+  /// ::UR_STRUCTURE_TYPE_EXP_ENQUEUE_SIGNAL_EVENT_PROPERTIES
+  ur_structure_type_t stype;
+  /// [in,out][optional] pointer to extension-specific structure
+  void *pNext;
+  /// [in] handle of an existing reusable event to signal on completion. The
+  /// handle value is not modified by the implementation. The event must
+  /// have been created with ::urEventCreateExp.
+  ur_event_handle_t hSignalEvent;
+
+} ur_exp_enqueue_signal_event_properties_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Create a reusable event object.
+///
+/// @details
+///     - A reusable event can be associated with at most one in-flight command
+///       at a time, but may be reused across multiple successive commands.
+///     - The event is initially in the completed state.
+///     - The context and device must be compatible: hDevice must be one of the
+///       devices associated with hContext.
+///     - To enable profiling timestamps, pass
+///       ::UR_EXP_EVENT_CREATE_FLAG_PROFILING_ENABLE in pProperties->flags.
+///
+/// @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 == hContext`
+///         + `NULL == hDevice`
+///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+///         + `NULL != pProperties && ::UR_EXP_EVENT_CREATE_FLAGS_MASK &
+///         pProperties->flags`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == phEvent`
+///     - ::UR_RESULT_ERROR_INVALID_CONTEXT
+///     - ::UR_RESULT_ERROR_INVALID_DEVICE
+///     - ::UR_RESULT_ERROR_INVALID_VALUE
+///         + `pProperties != NULL && pProperties->flags &
+///         ~::UR_EXP_EVENT_CREATE_FLAG_PROFILING_ENABLE`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If ::UR_DEVICE_INFO_REUSABLE_EVENTS_EXP is false.
+///         + If ::UR_EXP_EVENT_CREATE_FLAG_PROFILING_ENABLE is set and
+///         ::UR_DEVICE_INFO_REUSABLE_EVENTS_PROFILING_EXP is false.
+///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
+///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
+UR_APIEXPORT ur_result_t UR_APICALL urEventCreateExp(
+    /// [in] handle of the context object
+    ur_context_handle_t hContext,
+    /// [in] handle of the device on which the event will be used
+    ur_device_handle_t hDevice,
+    /// [in][optional] pointer to event creation properties
+    const ur_exp_event_create_properties_t *pProperties,
+    /// [out][alloc] pointer to handle of the created event object
+    ur_event_handle_t *phEvent);
+
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
@@ -14273,6 +14386,17 @@ typedef struct ur_event_set_callback_params_t {
   void **ppUserData;
 } ur_event_set_callback_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urEventCreateExp
+/// @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_event_create_exp_params_t {
+  ur_context_handle_t *phContext;
+  ur_device_handle_t *phDevice;
+  const ur_exp_event_create_properties_t **ppProperties;
+  ur_event_handle_t **pphEvent;
+} ur_event_create_exp_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urProgramCreateWithIL
 /// @details Each entry is a pointer to the parameter passed to the function;

unified-runtime/include/unified-runtime/ur_api_funcs.def

@@ -44,6 +44,7 @@ _UR_API(urEventRelease)
 _UR_API(urEventGetNativeHandle)
 _UR_API(urEventCreateWithNativeHandle)
 _UR_API(urEventSetCallback)
+_UR_API(urEventCreateExp)
 _UR_API(urProgramCreateWithIL)
 _UR_API(urProgramCreateWithBinary)
 _UR_API(urProgramBuild)

unified-runtime/include/unified-runtime/ur_ddi.h

@@ -301,6 +301,38 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetEventProcAddrTable(
 typedef ur_result_t(UR_APICALL *ur_pfnGetEventProcAddrTable_t)(
     ur_api_version_t, ur_event_dditable_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urEventCreateExp
+typedef ur_result_t(UR_APICALL *ur_pfnEventCreateExp_t)(
+    ur_context_handle_t, ur_device_handle_t,
+    const ur_exp_event_create_properties_t *, ur_event_handle_t *);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Table of EventExp functions pointers
+typedef struct ur_event_exp_dditable_t {
+  ur_pfnEventCreateExp_t pfnCreateExp;
+} ur_event_exp_dditable_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Exported function for filling application's EventExp table
+///        with current process' addresses
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_VERSION
+UR_DLLEXPORT ur_result_t UR_APICALL urGetEventExpProcAddrTable(
+    /// [in] API version requested
+    ur_api_version_t version,
+    /// [in,out] pointer to table of DDI function pointers
+    ur_event_exp_dditable_t *pDdiTable);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urGetEventExpProcAddrTable
+typedef ur_result_t(UR_APICALL *ur_pfnGetEventExpProcAddrTable_t)(
+    ur_api_version_t, ur_event_exp_dditable_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urProgramCreateWithIL
 typedef ur_result_t(UR_APICALL *ur_pfnProgramCreateWithIL_t)(
@@ -2258,6 +2290,7 @@ typedef struct ur_dditable_t {
   ur_platform_dditable_t Platform;
   ur_context_dditable_t Context;
   ur_event_dditable_t Event;
+  ur_event_exp_dditable_t EventExp;
   ur_program_dditable_t Program;
   ur_program_exp_dditable_t ProgramExp;
   ur_kernel_dditable_t Kernel;

unified-runtime/include/unified-runtime/ur_print.h

@@ -1564,6 +1564,36 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintExpEnqueueNativeCommandProperties(
     const struct ur_exp_enqueue_native_command_properties_t params,
     char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_exp_event_create_flag_t enum
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL
+urPrintExpEventCreateFlags(enum ur_exp_event_create_flag_t value, char *buffer,
+                           const size_t buff_size, size_t *out_size);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_exp_event_create_properties_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintExpEventCreateProperties(
+    const struct ur_exp_event_create_properties_t params, char *buffer,
+    const size_t buff_size, size_t *out_size);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_exp_enqueue_signal_event_properties_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintExpEnqueueSignalEventProperties(
+    const struct ur_exp_enqueue_signal_event_properties_t params, char *buffer,
+    const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_loader_config_create_params_t struct
 /// @returns
@@ -1915,6 +1945,16 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintEventSetCallbackParams(
     const struct ur_event_set_callback_params_t *params, char *buffer,
     const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_event_create_exp_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintEventCreateExpParams(
+    const struct ur_event_create_exp_params_t *params, char *buffer,
+    const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_program_create_with_il_params_t struct
 /// @returns