[UR][L0V2] Add experimental oneapi reusable events implementation

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

@@ -520,6 +520,8 @@ typedef enum ur_function_t {
   UR_FUNCTION_IPC_OPEN_PHYS_MEM_HANDLE_EXP = 318,
   /// Enumerator for ::urIPCClosePhysMemHandleExp
   UR_FUNCTION_IPC_CLOSE_PHYS_MEM_HANDLE_EXP = 319,
+  /// Enumerator for ::urEventCreateExp
+  UR_FUNCTION_EVENT_CREATE_EXP = 320,
   /// @cond
   UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
   /// @endcond
@@ -645,6 +647,8 @@ typedef enum ur_structure_type_t {
   UR_STRUCTURE_TYPE_EXP_HOST_TASK_PROPERTIES = 0x6000,
   /// ::ur_exp_usm_host_alloc_register_properties_t
   UR_STRUCTURE_TYPE_EXP_USM_HOST_ALLOC_REGISTER_PROPERTIES = 0x7000,
+  /// ::ur_exp_event_desc_t
+  UR_STRUCTURE_TYPE_EXP_EVENT_DESC = 0x8000,
   /// @cond
   UR_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
   /// @endcond
@@ -13671,9 +13675,13 @@ UR_APIEXPORT ur_result_t UR_APICALL urEnqueueEventsWaitWithBarrierExt(
     /// previously enqueued commands
     /// must be complete.
     const ur_event_handle_t *phEventWaitList,
-    /// [out][optional][alloc] return an event object that identifies this
+    /// [in,out][optional][alloc] return an event object that identifies this
     /// particular command instance. If phEventWaitList and phEvent are not
-    /// NULL, phEvent must not refer to an element of the phEventWaitList array.
+    /// NULL, phEvent must not refer to an element of the phEventWaitList
+    /// array. If *phEvent is not NULL on input and points to a reusable event
+    /// created by ::urEventCreateExp, it is signaled by this command instead
+    /// of allocating a new event. Behavior for events not created by
+    /// ::urEventCreateExp is adapter-specific.
     ur_event_handle_t *phEvent);
 
 #if !defined(__GNUC__)
@@ -13767,6 +13775,85 @@ 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 Reusable event creation flags.
+typedef uint32_t ur_exp_event_flags_t;
+typedef enum ur_exp_event_flag_t {
+  /// Event captures UR_PROFILING_INFO_COMMAND_START and
+  /// UR_PROFILING_INFO_COMMAND_END timestamps when signalled.
+  UR_EXP_EVENT_FLAG_ENABLE_PROFILING = UR_BIT(0),
+  /// @cond
+  UR_EXP_EVENT_FLAG_FORCE_UINT32 = 0x7fffffff
+  /// @endcond
+
+} ur_exp_event_flag_t;
+/// @brief Bit Mask for validating ur_exp_event_flags_t
+#define UR_EXP_EVENT_FLAGS_MASK 0xfffffffe
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Descriptor type for creating reusable events.
+typedef struct ur_exp_event_desc_t {
+  /// [in] type of this structure, must be
+  /// ::UR_STRUCTURE_TYPE_EXP_EVENT_DESC
+  ur_structure_type_t stype;
+  /// [in][optional] pointer to extension-specific structure
+  const void *pNext;
+  /// [in] handle of the device object associated with this event
+  ur_device_handle_t hDevice;
+  /// [in] combination of event creation flags. If
+  /// ::UR_EXP_EVENT_FLAG_ENABLE_PROFILING is set, the event captures
+  /// UR_PROFILING_INFO_COMMAND_START and UR_PROFILING_INFO_COMMAND_END
+  /// timestamps when signalled. If it is not set, profiling info queries on
+  /// this event return ::UR_RESULT_ERROR_PROFILING_INFO_NOT_AVAILABLE
+  /// unless the queue used to signal the event has profiling enabled.
+  ur_exp_event_flags_t flags;
+
+} ur_exp_event_desc_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Create a reusable event object that can be passed to
+///        ::urEnqueueEventsWaitWithBarrierExt to signal work. The event is not
+///        associated with any enqueued command.
+///
+/// @details
+///     - If ::UR_EXP_EVENT_FLAG_ENABLE_PROFILING is set in pEventDesc->flags
+///       and the platform does not support per-event profiling, the function
+///       returns ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE.
+///
+/// @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 == pEventDesc->hDevice`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pEventDesc`
+///         + `NULL == phEvent`
+///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+///         + `::UR_EXP_EVENT_FLAGS_MASK & pEventDesc->flags`
+///     - ::UR_RESULT_ERROR_INVALID_CONTEXT
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + `pEventDesc->flags & ::UR_EXP_EVENT_FLAG_ENABLE_PROFILING` and the
+///         platform does not support per-event profiling
+///     - ::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] pointer to event creation descriptor
+    const ur_exp_event_desc_t *pEventDesc,
+    /// [out] pointer to the handle of the event object created
+    ur_event_handle_t *phEvent);
+
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
@@ -14391,6 +14478,16 @@ 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;
+  const ur_exp_event_desc_t **ppEventDesc;
+  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,37 @@ 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, const ur_exp_event_desc_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)(
@@ -2283,6 +2314,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,26 @@ 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_flag_t enum
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL
+urPrintExpEventFlags(enum ur_exp_event_flag_t value, char *buffer,
+                     const size_t buff_size, size_t *out_size);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_exp_event_desc_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL
+urPrintExpEventDesc(const struct ur_exp_event_desc_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 +1935,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