Merge pull request #2253 from pbalcer/low-power-events

add low-power events experimental extension spec

Author: pbalcer

include/ur_api.h

@@ -230,6 +230,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_COMMAND_BUFFER_UPDATE_SIGNAL_EVENT_EXP = 243,             ///< Enumerator for ::urCommandBufferUpdateSignalEventExp
     UR_FUNCTION_COMMAND_BUFFER_UPDATE_WAIT_EVENTS_EXP = 244,              ///< Enumerator for ::urCommandBufferUpdateWaitEventsExp
     UR_FUNCTION_BINDLESS_IMAGES_MAP_EXTERNAL_LINEAR_MEMORY_EXP = 245,     ///< Enumerator for ::urBindlessImagesMapExternalLinearMemoryExp
+    UR_FUNCTION_ENQUEUE_EVENTS_WAIT_WITH_BARRIER_EXT = 246,               ///< Enumerator for ::urEnqueueEventsWaitWithBarrierExt
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -288,6 +289,7 @@ typedef enum ur_structure_type_t {
     UR_STRUCTURE_TYPE_EXP_SAMPLER_CUBEMAP_PROPERTIES = 0x2006,               ///< ::ur_exp_sampler_cubemap_properties_t
     UR_STRUCTURE_TYPE_EXP_IMAGE_COPY_REGION = 0x2007,                        ///< ::ur_exp_image_copy_region_t
     UR_STRUCTURE_TYPE_EXP_ENQUEUE_NATIVE_COMMAND_PROPERTIES = 0x3000,        ///< ::ur_exp_enqueue_native_command_properties_t
+    UR_STRUCTURE_TYPE_EXP_ENQUEUE_EXT_PROPERTIES = 0x4000,                   ///< ::ur_exp_enqueue_ext_properties_t
     /// @cond
     UR_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -1702,6 +1704,7 @@ typedef enum ur_device_info_t {
                                                                      ///< backed 2D sampled image data.
     UR_DEVICE_INFO_ENQUEUE_NATIVE_COMMAND_SUPPORT_EXP = 0x2020,      ///< [::ur_bool_t] returns true if the device supports enqueueing of native
                                                                      ///< work
+    UR_DEVICE_INFO_LOW_POWER_EVENTS_EXP = 0x2021,                    ///< [::ur_bool_t] returns true if the device supports low-power events.
     /// @cond
     UR_DEVICE_INFO_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -1727,7 +1730,7 @@ typedef enum ur_device_info_t {
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
 ///         + `NULL == hDevice`
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
-///         + `::UR_DEVICE_INFO_ENQUEUE_NATIVE_COMMAND_SUPPORT_EXP < propName`
+///         + `::UR_DEVICE_INFO_LOW_POWER_EVENTS_EXP < propName`
 ///     - ::UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION
 ///         + If `propName` is not supported by the adapter.
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
@@ -5447,13 +5450,17 @@ typedef enum ur_queue_flag_t {
                                                              ///< ignore this flag.
     UR_QUEUE_FLAG_SYNC_WITH_DEFAULT_STREAM = UR_BIT(10),     ///< Synchronize with the default stream. Only meaningful for CUDA. Other
                                                              ///< platforms may ignore this flag.
+    UR_QUEUE_FLAG_LOW_POWER_EVENTS_EXP = UR_BIT(11),         ///< Hint: use low-power events. Only meaningful for Level Zero, where the
+                                                             ///< implementation may use interrupt-driven events. May reduce CPU
+                                                             ///< utilization at the cost of increased event completion latency. Other
+                                                             ///< platforms may ignore this flag.
     /// @cond
     UR_QUEUE_FLAG_FORCE_UINT32 = 0x7fffffff
     /// @endcond
 
 } ur_queue_flag_t;
 /// @brief Bit Mask for validating ur_queue_flags_t
-#define UR_QUEUE_FLAGS_MASK 0xfffff800
+#define UR_QUEUE_FLAGS_MASK 0xfffff000
 
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Query information about a command queue
@@ -9974,6 +9981,89 @@ urUsmP2PPeerAccessGetInfoExp(
     size_t *pPropSizeRet              ///< [out][optional] pointer to the actual size in bytes of the queried propName.
 );
 
+#if !defined(__GNUC__)
+#pragma endregion
+#endif
+// Intel 'oneAPI' Unified Runtime Experimental API for low-power events API
+#if !defined(__GNUC__)
+#pragma region low_power_events_(experimental)
+#endif
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Extended enqueue properties
+typedef uint32_t ur_exp_enqueue_ext_flags_t;
+typedef enum ur_exp_enqueue_ext_flag_t {
+    UR_EXP_ENQUEUE_EXT_FLAG_LOW_POWER_EVENTS = UR_BIT(11), ///< Hint: use low-power events. Only meaningful for Level Zero, where the
+                                                           ///< implementation may use interrupt-driven events. May reduce CPU
+                                                           ///< utilization at the cost of increased event completion latency. Other
+                                                           ///< platforms may ignore this flag.
+    /// @cond
+    UR_EXP_ENQUEUE_EXT_FLAG_FORCE_UINT32 = 0x7fffffff
+    /// @endcond
+
+} ur_exp_enqueue_ext_flag_t;
+/// @brief Bit Mask for validating ur_exp_enqueue_ext_flags_t
+#define UR_EXP_ENQUEUE_EXT_FLAGS_MASK 0xfffff7ff
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Extended enqueue properties
+typedef struct ur_exp_enqueue_ext_properties_t {
+    ur_structure_type_t stype;        ///< [in] type of this structure, must be
+                                      ///< ::UR_STRUCTURE_TYPE_EXP_ENQUEUE_EXT_PROPERTIES
+    void *pNext;                      ///< [in,out][optional] pointer to extension-specific structure
+    ur_exp_enqueue_ext_flags_t flags; ///< [in] extended enqueue flags
+
+} ur_exp_enqueue_ext_properties_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Enqueue a barrier command which waits a list of events to complete
+///        before it completes, with optional extended properties
+///
+/// @details
+///     - If the event list is empty, it waits for all previously enqueued
+///       commands to complete.
+///     - It blocks command execution - any following commands enqueued after it
+///       do not execute until it completes.
+///     - It returns an event which can be waited on.
+///
+/// @remarks
+///   _Analogues_
+///     - **clEnqueueBarrierWithWaitList**
+///
+/// @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 == hQueue`
+///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+///         + `NULL != pProperties && ::UR_EXP_ENQUEUE_EXT_FLAGS_MASK & pProperties->flags`
+///     - ::UR_RESULT_ERROR_INVALID_QUEUE
+///     - ::UR_RESULT_ERROR_INVALID_EVENT
+///     - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
+///         + `phEventWaitList == NULL && numEventsInWaitList > 0`
+///         + `phEventWaitList != NULL && numEventsInWaitList == 0`
+///         + If event objects in phEventWaitList are not valid events.
+///     - ::UR_RESULT_ERROR_IN_EVENT_LIST_EXEC_STATUS
+///         + An event in `phEventWaitList` has ::UR_EVENT_STATUS_ERROR.
+///     - ::UR_RESULT_ERROR_INVALID_VALUE
+///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
+///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
+UR_APIEXPORT ur_result_t UR_APICALL
+urEnqueueEventsWaitWithBarrierExt(
+    ur_queue_handle_t hQueue,                           ///< [in] handle of the queue object
+    const ur_exp_enqueue_ext_properties_t *pProperties, ///< [in][optional] pointer to the extended enqueue properties
+    uint32_t numEventsInWaitList,                       ///< [in] size of the event wait list
+    const ur_event_handle_t *phEventWaitList,           ///< [in][optional][range(0, numEventsInWaitList)] pointer to a list of
+                                                        ///< events that must be complete before this command can be executed.
+                                                        ///< If nullptr, the numEventsInWaitList must be 0, indicating that all
+                                                        ///< previously enqueued commands
+                                                        ///< must be complete.
+    ur_event_handle_t *phEvent                          ///< [out][optional] 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.
+);
+
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
@@ -11450,6 +11540,18 @@ typedef struct ur_enqueue_kernel_launch_custom_exp_params_t {
     ur_event_handle_t **pphEvent;
 } ur_enqueue_kernel_launch_custom_exp_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urEnqueueEventsWaitWithBarrierExt
+/// @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_events_wait_with_barrier_ext_params_t {
+    ur_queue_handle_t *phQueue;
+    const ur_exp_enqueue_ext_properties_t **ppProperties;
+    uint32_t *pnumEventsInWaitList;
+    const ur_event_handle_t **pphEventWaitList;
+    ur_event_handle_t **pphEvent;
+} ur_enqueue_events_wait_with_barrier_ext_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urEnqueueCooperativeKernelLaunchExp
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_api_funcs.def

@@ -126,6 +126,7 @@ _UR_API(urEnqueueDeviceGlobalVariableWrite)
 _UR_API(urEnqueueDeviceGlobalVariableRead)
 _UR_API(urEnqueueReadHostPipe)
 _UR_API(urEnqueueWriteHostPipe)
+_UR_API(urEnqueueEventsWaitWithBarrierExt)
 _UR_API(urEnqueueKernelLaunchCustomExp)
 _UR_API(urEnqueueCooperativeKernelLaunchExp)
 _UR_API(urEnqueueTimestampRecordingExp)

include/ur_ddi.h

@@ -1398,6 +1398,15 @@ typedef ur_result_t(UR_APICALL *ur_pfnEnqueueWriteHostPipe_t)(
     const ur_event_handle_t *,
     ur_event_handle_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urEnqueueEventsWaitWithBarrierExt
+typedef ur_result_t(UR_APICALL *ur_pfnEnqueueEventsWaitWithBarrierExt_t)(
+    ur_queue_handle_t,
+    const ur_exp_enqueue_ext_properties_t *,
+    uint32_t,
+    const ur_event_handle_t *,
+    ur_event_handle_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Table of Enqueue functions pointers
 typedef struct ur_enqueue_dditable_t {
@@ -1426,6 +1435,7 @@ typedef struct ur_enqueue_dditable_t {
     ur_pfnEnqueueDeviceGlobalVariableRead_t pfnDeviceGlobalVariableRead;
     ur_pfnEnqueueReadHostPipe_t pfnReadHostPipe;
     ur_pfnEnqueueWriteHostPipe_t pfnWriteHostPipe;
+    ur_pfnEnqueueEventsWaitWithBarrierExt_t pfnEventsWaitWithBarrierExt;
 } ur_enqueue_dditable_t;
 
 ///////////////////////////////////////////////////////////////////////////////

include/ur_print.h

@@ -1058,6 +1058,22 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintExpLaunchProperty(const struct ur_exp
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintExpPeerInfo(enum ur_exp_peer_info_t value, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_exp_enqueue_ext_flag_t enum
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintExpEnqueueExtFlags(enum ur_exp_enqueue_ext_flag_t value, char *buffer, const size_t buff_size, size_t *out_size);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_exp_enqueue_ext_properties_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintExpEnqueueExtProperties(const struct ur_exp_enqueue_ext_properties_t params, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_exp_enqueue_native_command_flag_t enum
 /// @returns
@@ -2034,6 +2050,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintEnqueueWriteHostPipeParams(const stru
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintEnqueueKernelLaunchCustomExpParams(const struct ur_enqueue_kernel_launch_custom_exp_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_enqueue_events_wait_with_barrier_ext_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL 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_cooperative_kernel_launch_exp_params_t struct
 /// @returns