[UR][L0v2] Implement IPC event sharing in the Level Zero v2 adapter

Adds the producer/consumer side of UR's IPC event extension on top of
Level Zero's counter-based event IPC APIs (zeEventCounterBased{Create,
Get/Open/CloseIpcHandle}).

  * urEventCreateExp handles UR_EXP_EVENT_FLAG_IPC_EXP only; the non-IPC
    reusable-event path is left to PR #22349. IPC + profiling is
    rejected.
  * IPC events are not pooled. The primary use case is IPC + reusable
    events, where the user reuses one event many times, so pool reuse
    buys little; and sharing pooled events across processes is unsafe
    because a recycled event hands one process state another process
    is still relying on. The producer wraps a freshly-created
    ze_event_handle_t; the consumer uses a dedicated raii variant whose
    destructor calls zeEventCounterBasedCloseIpcHandle, so
    urEventRelease tears the imported event down correctly with no
    separate close entry point.
  * UR_DEVICE_INFO_IPC_EVENT_SUPPORT_EXP is gated on v2/Linux, BMG+,
    and latest driver - this might need to be revised eventually.

Conformance tests signal the producer event via Level Zero directly so
they do not depend on the reusable-event extension.

Assisted-By: Claude

Author: againull

unified-runtime/source/adapters/level_zero/device.cpp

@@ -1389,6 +1389,19 @@ ur_result_t urDeviceGetInfo(
 #else
     return ReturnValue(false);
 #endif
+  case UR_DEVICE_INFO_IPC_EVENT_SUPPORT_EXP: {
+#if defined(UR_ADAPTER_LEVEL_ZERO_V2) && defined(__linux__)
+    constexpr uint32_t MinDriverBuild = 38646;
+    ZeStruct<ze_driver_properties_t> ZeDriverProperties;
+    ZE2UR_CALL(zeDriverGetProperties,
+               (Device->Platform->ZeDriver, &ZeDriverProperties));
+    const uint32_t DriverBuild = ZeDriverProperties.driverVersion & 0xFFFF;
+    return ReturnValue(static_cast<ur_bool_t>(Device->isBMGOrNewer() &&
+                                              DriverBuild >= MinDriverBuild));
+#else
+    return ReturnValue(false);
+#endif
+  }
   case UR_DEVICE_INFO_ASYNC_BARRIER:
     return ReturnValue(false);
   case UR_DEVICE_INFO_HOST_PIPE_READ_WRITE_SUPPORT:

unified-runtime/source/adapters/level_zero/device.hpp

@@ -209,6 +209,11 @@ struct ur_device_handle_t_ : ur_object {
             ZeDeviceIpVersionExt->ipVersion >= 0x030f0000);
   }
 
+  bool isBMGOrNewer() {
+    return (ZeDeviceProperties->vendorId == 0x8086 &&
+            ZeDeviceIpVersionExt->ipVersion >= 0x05004000);
+  }
+
   bool isIntegrated() {
     return (ZeDeviceProperties->flags & ZE_DEVICE_PROPERTY_FLAG_INTEGRATED);
   }

unified-runtime/source/adapters/level_zero/v2/common.hpp

@@ -107,6 +107,15 @@ HANDLE_WRAPPER_TYPE(ze_context_handle_t, zeContextDestroy)
 HANDLE_WRAPPER_TYPE(ze_command_list_handle_t, zeCommandListDestroy)
 HANDLE_WRAPPER_TYPE(ze_image_handle_t, zeImageDestroy)
 
+// Counter-based event IPC handle opened via zeEventCounterBasedOpenIpcHandle.
+// Same underlying handle type as ze_event_handle_t but a different teardown
+// function, hence a distinct alias.
+inline constexpr char ipc_event_destroy_name[] =
+    "zeEventCounterBasedCloseIpcHandle";
+using ipc_event_handle_t =
+    ze_handle_wrapper<::ze_event_handle_t, zeEventCounterBasedCloseIpcHandle,
+                      ipc_event_destroy_name>;
+
 template <typename RawHandle, ur_result_t (*retain)(RawHandle),
           ur_result_t (*release)(RawHandle)>
 struct ur_handle {

unified-runtime/source/adapters/level_zero/v2/event.cpp

@@ -14,9 +14,11 @@
 #include "event.hpp"
 #include "event_pool.hpp"
 #include "event_provider.hpp"
+#include "event_provider_counter.hpp"
 #include "queue_api.hpp"
 #include "queue_handle.hpp"
 
+#include "../device.hpp"
 #include "../ur_interface_loader.hpp"
 
 static uint64_t adjustEndEventTimestamp(uint64_t adjustedStartTimestamp,
@@ -164,11 +166,7 @@ void ur_event_handle_t_::reset() {
 }
 
 ze_event_handle_t ur_event_handle_t_::getZeEvent() const {
-  if (event_pool) {
-    return std::get<v2::raii::cache_borrowed_event>(hZeEvent).get();
-  } else {
-    return std::get<v2::raii::ze_event_handle_t>(hZeEvent).get();
-  }
+  return std::visit([](const auto &h) { return h.get(); }, hZeEvent);
 }
 
 ur_result_t ur_event_handle_t_::retain() {
@@ -182,10 +180,14 @@ ur_result_t ur_event_handle_t_::release() {
 
   if (event_pool) {
     event_pool->free(this);
-  } else {
-    std::get<v2::raii::ze_event_handle_t>(hZeEvent).release();
-    delete this;
+    return UR_RESULT_SUCCESS;
   }
+
+  // The variant destructor runs the correct teardown:
+  //  - ze_event_handle_t honors ownZeHandle (zeEventDestroy if owned, no-op
+  //    for externally-imported events).
+  //  - ipc_event_handle_t runs zeEventCounterBasedCloseIpcHandle.
+  delete this;
   return UR_RESULT_SUCCESS;
 }
 
@@ -197,6 +199,14 @@ bool ur_event_handle_t_::isProfilingEnabled() const {
   return flags & v2::EVENT_FLAGS_PROFILING_ENABLED;
 }
 
+bool ur_event_handle_t_::isIpcCapable() const {
+  return flags & v2::EVENT_FLAGS_IPC;
+}
+
+bool ur_event_handle_t_::isIpcImported() const {
+  return flags & v2::EVENT_FLAGS_IPC_IMPORTED;
+}
+
 std::pair<uint64_t *, ze_event_handle_t>
 ur_event_handle_t_::getEventEndTimestampAndHandle() {
   return {profilingData.eventEndTimestampAddr(), getZeEvent()};
@@ -234,6 +244,11 @@ ur_event_handle_t_::ur_event_handle_t_(
           ,
           nullptr) {}
 
+ur_event_handle_t_::ur_event_handle_t_(ur_context_handle_t hContext,
+                                       event_variant hZeEvent,
+                                       v2::event_flags_t flags)
+    : ur_event_handle_t_(hContext, std::move(hZeEvent), flags, nullptr) {}
+
 namespace ur::level_zero {
 ur_result_t urEventRetain(ur_event_handle_t hEvent) try {
   return hEvent->retain();
@@ -391,6 +406,11 @@ ur_result_t urEventGetProfilingInfo(
 
 ur_result_t urEventGetNativeHandle(ur_event_handle_t hEvent,
                                    ur_native_handle_t *phNativeEvent) try {
+  // Imported event handle must be torn down via
+  // zeEventCounterBasedCloseIpcHandle, not zeEventDestroy; don't hand it out.
+  if (hEvent->isIpcImported()) {
+    return UR_RESULT_ERROR_INVALID_EVENT;
+  }
   *phNativeEvent = reinterpret_cast<ur_native_handle_t>(hEvent->getZeEvent());
   return UR_RESULT_SUCCESS;
 } catch (...) {
@@ -416,12 +436,35 @@ urEventCreateWithNativeHandle(ur_native_handle_t hNativeEvent,
   return exceptionToResult(std::current_exception());
 }
 
-ur_result_t urEventCreateExp(ur_context_handle_t /*hContext*/,
-                             ur_device_handle_t /*hDevice*/,
-                             const ur_exp_event_desc_t * /*pEventDesc*/,
-                             ur_event_handle_t * /*phEvent*/) {
-  UR_LOG(ERR, "{} function not implemented!", __FUNCTION__);
+ur_result_t urEventCreateExp(ur_context_handle_t hContext,
+                             ur_device_handle_t hDevice,
+                             const ur_exp_event_desc_t *pEventDesc,
+                             ur_event_handle_t *phEvent) try {
+  if (!hContext || !hDevice)
+    return UR_RESULT_ERROR_INVALID_NULL_HANDLE;
+  if (!pEventDesc || !phEvent)
+    return UR_RESULT_ERROR_INVALID_NULL_POINTER;
+
+  if (pEventDesc->flags & UR_EXP_EVENT_FLAGS_MASK)
+    return UR_RESULT_ERROR_INVALID_ENUMERATION;
+
+  if (pEventDesc->flags & UR_EXP_EVENT_FLAG_IPC_EXP) {
+    if (pEventDesc->flags & UR_EXP_EVENT_FLAG_ENABLE_PROFILING)
+      return UR_RESULT_ERROR_INVALID_VALUE;
+
+    ze_event_handle_t hZeEvent = nullptr;
+    UR_CALL(v2::createIpcCounterBasedEvent(hContext, hDevice, &hZeEvent));
+
+    *phEvent = new ur_event_handle_t_(
+        hContext, v2::raii::ze_event_handle_t{hZeEvent, /*ownZeHandle=*/true},
+        v2::EVENT_FLAGS_COUNTER | v2::EVENT_FLAGS_IPC);
+    return UR_RESULT_SUCCESS;
+  }
+
+  UR_LOG(ERR, "{}: non-IPC reusable events not implemented!", __FUNCTION__);
   return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+} catch (...) {
+  return exceptionToResult(std::current_exception());
 }
 
 } // namespace ur::level_zero

unified-runtime/source/adapters/level_zero/v2/event.hpp

@@ -56,10 +56,16 @@ struct event_profiling_data_t {
 
 struct ur_event_handle_t_ : ur_object {
 public:
-  // cache_borrowed_event is used for pooled events, whilst ze_event_handle_t is
-  // used for native events
+  // The variant alternative encodes how the L0 event handle is torn down:
+  //  - cache_borrowed_event: returned to the pool.
+  //  - ze_event_handle_t: native event (urEventCreateWithNativeHandle if
+  //    external, urEventCreateExp with IPC flag if adapter-owned); the
+  //    wrapper's ownZeHandle flag controls whether zeEventDestroy runs.
+  //  - ipc_event_handle_t: opened from an IPC handle in another process;
+  //    torn down via zeEventCounterBasedCloseIpcHandle.
   using event_variant =
-      std::variant<v2::raii::cache_borrowed_event, v2::raii::ze_event_handle_t>;
+      std::variant<v2::raii::cache_borrowed_event, v2::raii::ze_event_handle_t,
+                   v2::raii::ipc_event_handle_t>;
 
   ur_event_handle_t_(ur_context_handle_t hContext,
                      v2::raii::cache_borrowed_event eventAllocation,
@@ -69,6 +75,11 @@ struct ur_event_handle_t_ : ur_object {
                      ur_native_handle_t hNativeEvent,
                      const ur_event_native_properties_t *pProperties);
 
+  // Wraps a caller-built event_variant with explicit flags. Used by the IPC
+  // producer (urEventCreateExp) and consumer (urIPCOpenEventHandleExp) paths.
+  ur_event_handle_t_(ur_context_handle_t hContext, event_variant hZeEvent,
+                     v2::event_flags_t flags);
+
   // Set the queue and command that this event is associated with
   void setQueue(ur_queue_t_ *hQueue);
   void setCommandType(ur_command_t commandType);
@@ -99,6 +110,12 @@ struct ur_event_handle_t_ : ur_object {
   // Tells if this event comes from a pool that has profiling enabled.
   bool isProfilingEnabled() const;
 
+  // True for IPC-shareable events (both producer and consumer side).
+  bool isIpcCapable() const;
+
+  // True for events opened via urIPCOpenEventHandleExp.
+  bool isIpcImported() const;
+
   // Queue associated with this event. Can be nullptr (for native events)
   ur_queue_t_ *getQueue() const;
 

unified-runtime/source/adapters/level_zero/v2/event_provider.hpp

@@ -24,7 +24,13 @@ using event_flags_t = uint32_t;
 enum event_flag_t {
   EVENT_FLAGS_COUNTER = UR_BIT(0),
   EVENT_FLAGS_PROFILING_ENABLED = UR_BIT(1),
+  // IPC-shareable producer event.
+  EVENT_FLAGS_IPC = UR_BIT(2),
+  // Event opened from an IPC handle.
+  EVENT_FLAGS_IPC_IMPORTED = UR_BIT(3),
 };
+// Bits used to index pooled events in event_pool_cache. IPC events are never
+// pool-allocated, so EVENT_FLAGS_IPC* are excluded from this count.
 static constexpr size_t EVENT_FLAGS_USED_BITS = 2;
 
 enum queue_type {

unified-runtime/source/adapters/level_zero/v2/event_provider_counter.cpp

@@ -113,4 +113,20 @@ std::unique_ptr<event_provider> createProvider(ur_platform_handle_t platform,
   return std::make_unique<provider_normal>(context, queueType, flags);
 }
 
+ur_result_t createIpcCounterBasedEvent(ur_context_handle_t context,
+                                       ur_device_handle_t device,
+                                       ze_event_handle_t *phEvent) {
+  ze_event_counter_based_desc_t desc = {};
+  desc.stype = ZE_STRUCTURE_TYPE_EVENT_COUNTER_BASED_DESC;
+  desc.flags = ZE_EVENT_COUNTER_BASED_FLAG_HOST_VISIBLE |
+               ZE_EVENT_COUNTER_BASED_FLAG_IMMEDIATE |
+               ZE_EVENT_COUNTER_BASED_FLAG_NON_IMMEDIATE |
+               ZE_EVENT_COUNTER_BASED_FLAG_IPC;
+  desc.signal = ZE_EVENT_SCOPE_FLAG_HOST;
+
+  ZE2UR_CALL(zeEventCounterBasedCreate,
+             (context->getZeHandle(), device->ZeDevice, &desc, phEvent));
+  return UR_RESULT_SUCCESS;
+}
+
 } // namespace v2

unified-runtime/source/adapters/level_zero/v2/event_provider_counter.hpp

@@ -61,4 +61,10 @@ std::unique_ptr<event_provider> createProvider(ur_platform_handle_t platform,
                                                ur_device_handle_t device,
                                                event_flags_t flags);
 
+// Creates an IPC-shareable counter-based ze_event_handle_t for the producer
+// side of urEventCreateExp.
+ur_result_t createIpcCounterBasedEvent(ur_context_handle_t context,
+                                       ur_device_handle_t device,
+                                       ze_event_handle_t *phEvent);
+
 } // namespace v2

unified-runtime/source/adapters/level_zero/v2/ipc_event.cpp

@@ -7,28 +7,97 @@
 //
 //===----------------------------------------------------------------------===//
 
+#include <memory>
+
 #include <unified-runtime/ur_api.h>
 
+#include "../platform.hpp"
 #include "../ur_interface_loader.hpp"
+#include "context.hpp"
+#include "event.hpp"
 
 namespace ur::level_zero {
 
-ur_result_t urIPCGetEventHandleExp(ur_event_handle_t /*hEvent*/,
-                                   void ** /*ppIPCEventHandleData*/,
-                                   size_t * /*pIPCEventHandleDataSizeRet*/) {
-  return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+namespace {
+
+// Fixed L0 IPC handle size; reported by Get and validated by Open.
+constexpr size_t kIpcEventHandleDataSize =
+    sizeof(ze_ipc_event_counter_based_handle_t);
+
+} // namespace
+
+ur_result_t urIPCGetEventHandleExp(ur_event_handle_t hEvent,
+                                   void **ppIPCEventHandleData,
+                                   size_t *pIPCEventHandleDataSizeRet) try {
+  if (!hEvent) {
+    return UR_RESULT_ERROR_INVALID_NULL_HANDLE;
+  }
+  if (!ppIPCEventHandleData || !pIPCEventHandleDataSizeRet) {
+    return UR_RESULT_ERROR_INVALID_NULL_POINTER;
+  }
+
+  std::shared_lock<ur_shared_mutex> lock(hEvent->Mutex);
+
+  if (!hEvent->isIpcCapable() || hEvent->isIpcImported()) {
+    return UR_RESULT_ERROR_INVALID_EVENT;
+  }
+  if (hEvent->isProfilingEnabled() || hEvent->isTimestamped()) {
+    return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+  }
+
+  auto handle = std::make_unique<ze_ipc_event_counter_based_handle_t>();
+  ZE2UR_CALL(zeEventCounterBasedGetIpcHandle,
+             (hEvent->getZeEvent(), handle.get()));
+
+  // Caller releases the buffer via urIPCPutEventHandleExp.
+  *ppIPCEventHandleData = handle.release();
+  *pIPCEventHandleDataSizeRet = kIpcEventHandleDataSize;
+  return UR_RESULT_SUCCESS;
+} catch (...) {
+  return exceptionToResult(std::current_exception());
 }
 
 ur_result_t urIPCPutEventHandleExp(ur_context_handle_t /*hContext*/,
-                                   void * /*pIPCEventHandleData*/) {
-  return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+                                   void *pIPCEventHandleData) try {
+  if (!pIPCEventHandleData) {
+    return UR_RESULT_ERROR_INVALID_NULL_POINTER;
+  }
+  // Free the buffer allocated by urIPCGetEventHandleExp via RAII.
+  std::unique_ptr<ze_ipc_event_counter_based_handle_t> owner(
+      static_cast<ze_ipc_event_counter_based_handle_t *>(pIPCEventHandleData));
+  return UR_RESULT_SUCCESS;
+} catch (...) {
+  return exceptionToResult(std::current_exception());
 }
 
-ur_result_t urIPCOpenEventHandleExp(ur_context_handle_t /*hContext*/,
-                                    const void * /*pIPCEventHandleData*/,
-                                    size_t /*ipcEventHandleDataSize*/,
-                                    ur_event_handle_t * /*phEvent*/) {
-  return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+ur_result_t urIPCOpenEventHandleExp(ur_context_handle_t hContext,
+                                    const void *pIPCEventHandleData,
+                                    size_t ipcEventHandleDataSize,
+                                    ur_event_handle_t *phEvent) try {
+  if (!pIPCEventHandleData || !phEvent) {
+    return UR_RESULT_ERROR_INVALID_NULL_POINTER;
+  }
+  if (ipcEventHandleDataSize != kIpcEventHandleDataSize) {
+    return UR_RESULT_ERROR_INVALID_VALUE;
+  }
+
+  // The driver consumes the handle by value.
+  ze_ipc_event_counter_based_handle_t handle =
+      *static_cast<const ze_ipc_event_counter_based_handle_t *>(
+          pIPCEventHandleData);
+  ze_event_handle_t hZeEvent = nullptr;
+  ZE2UR_CALL(zeEventCounterBasedOpenIpcHandle,
+             (hContext->getZeHandle(), handle, &hZeEvent));
+
+  // The ipc_event_handle_t variant runs zeEventCounterBasedCloseIpcHandle on
+  // urEventRelease.
+  *phEvent =
+      new ur_event_handle_t_(hContext, v2::raii::ipc_event_handle_t{hZeEvent},
+                             v2::EVENT_FLAGS_COUNTER | v2::EVENT_FLAGS_IPC |
+                                 v2::EVENT_FLAGS_IPC_IMPORTED);
+  return UR_RESULT_SUCCESS;
+} catch (...) {
+  return exceptionToResult(std::current_exception());
 }
 
 } // namespace ur::level_zero

unified-runtime/test/conformance/device_code/linker_error.cpp

@@ -3,8 +3,8 @@
 //
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
+#include <iostream>
 #include <sycl/sycl.hpp>
-
 SYCL_EXTERNAL void this_function_does_not_exist();
 
 int main() {