[SYCL][Bindless][Doc][ABI-Break] Rename external semaphore destroy to…

… release (#14535) Rename function destroy_external_semaphore to release_external_semaphore. This name change is to clarify exactly what is happening to the external semaphore. That is, it is being released not destroyed. Corresponding UR PR: oneapi-src/unified-runtime#1855
intel · Jul 18, 2024 · 13c9d0e · 13c9d0e
1 parent 5647f9f
commit 13c9d0e
Show file tree

Hide file tree

Showing 22 changed files with 60 additions and 56 deletions.
diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_bindless_images.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_bindless_images.asciidoc
@@ -1903,17 +1903,18 @@ the `ext_oneapi_signal_external_semaphore` call complete.
 `ext_oneapi_wait_external_semaphore` and `ext_oneapi_signal_external_semaphore` 
 are non-blocking, asynchronous operations.
 
-The user must ensure to destroy all external semaphore objects once they are no 
-longer required through `destroy_external_semaphore`.
+The user must ensure to destroy all SYCL external semaphore objects used to 
+access the external semaphore once they are no longer required through 
+`release_external_semaphore`.
 
 ```cpp
 namespace sycl::ext::oneapi::experimental {
 
-void destroy_external_semaphore(interop_semaphore_handle semaphoreHandle,
+void release_external_semaphore(interop_semaphore_handle semaphoreHandle,
  const sycl::device &syclDevice,
  const sycl::context &syclContext);
 
-void destroy_external_semaphore(interop_semaphore_handle semaphoreHandle,
+void release_external_semaphore(interop_semaphore_handle semaphoreHandle,
  const sycl::queue &syclQueue);
 
 }
@@ -2579,9 +2580,9 @@ try {
  input_interop_mem_handle, queue);
  sycl::ext::oneapi::experimental::release_external_memory(
  output_interop_mem_handle, queue);
- sycl::ext::oneapi::experimental::destroy_external_semaphore(
+ sycl::ext::oneapi::experimental::release_external_semaphore(
  wait_interop_semaphore_handle, queue);
- sycl::ext::oneapi::experimental::destroy_external_semaphore(
+ sycl::ext::oneapi::experimental::release_external_semaphore(
  done_interop_semaphore_handle, queue);
  sycl::ext::oneapi::experimental::destroy_image_handle(img_input, queue);
  sycl::ext::oneapi::experimental::destroy_image_handle(img_output, queue);
@@ -2808,4 +2809,6 @@ These features still need to be handled:
  - Fetch sampled image arrays with `fetch_image_array` API.
 |5.13|2024-07-10| - Added const-qualifiers to `Src` param in `ext_oneapi_copy`
  funcs.
+|5.14|2024-07-17| - Rename `destroy_external_semaphore` to 
+ `release_external_semaphore`.
 |======================
diff --git a/sycl/include/sycl/detail/pi.def b/sycl/include/sycl/detail/pi.def
@@ -209,7 +209,7 @@ _PI_API(piextImportExternalMemory)
 _PI_API(piextMemReleaseInterop)
 _PI_API(piextMemMapExternalArray)
 _PI_API(piextImportExternalSemaphore)
-_PI_API(piextDestroyExternalSemaphore)
+_PI_API(piextReleaseExternalSemaphore)
 _PI_API(piextWaitExternalSemaphore)
 _PI_API(piextSignalExternalSemaphore)
 

diff --git a/sycl/include/sycl/detail/pi.h b/sycl/include/sycl/detail/pi.h
@@ -203,9 +203,10 @@
 // 17.59 Added const-qualifier to src_ptr in piextMemImageCopy.
 // 18.60 Remove deprecated functions piextMemImportOpaqueFD and
 // piextImportExternalSemaphoreOpaqueFD
+// 19.61 Rename piextDestroyExternalSemaphore to piextReleaseExternalSemaphore
 
-#define _PI_H_VERSION_MAJOR 18
-#define _PI_H_VERSION_MINOR 60
+#define _PI_H_VERSION_MAJOR 19
+#define _PI_H_VERSION_MINOR 61
 
 #define _PI_STRING_HELPER(a) #a
 #define _PI_CONCAT(a, b) _PI_STRING_HELPER(a.b)
@@ -3163,14 +3164,14 @@ piextImportExternalSemaphore(pi_context context, pi_device device,
  pi_external_semaphore_descriptor *sem_descriptor,
  pi_interop_semaphore_handle *ret_handle);
 
-/// API to destroy the external semaphore handle.
+/// API to release the external semaphore.
 ///
 /// \param context is the pi_context
 /// \param device is the pi_device
 /// \param sem_handle is the interop semaphore handle to the external semaphore
 /// to be destroyed
 __SYCL_EXPORT pi_result
-piextDestroyExternalSemaphore(pi_context context, pi_device device,
+piextReleaseExternalSemaphore(pi_context context, pi_device device,
  pi_interop_semaphore_handle sem_handle);
 
 /// API to instruct the queue with a non-blocking wait on an external semaphore.

diff --git a/sycl/include/sycl/ext/oneapi/bindless_images.hpp b/sycl/include/sycl/ext/oneapi/bindless_images.hpp
@@ -224,7 +224,7 @@ __SYCL_EXPORT interop_semaphore_handle import_external_semaphore(
  const sycl::queue &syclQueue);
 
 /**
- * @brief Destroy the external semaphore handle
+ * @brief Release the external semaphore
  *
  * @param semaphoreHandle The interop semaphore handle to destroy
  * @param syclDevice The device in which the interop semaphore handle was
@@ -233,19 +233,19 @@ __SYCL_EXPORT interop_semaphore_handle import_external_semaphore(
  * created
  */
 __SYCL_EXPORT void
-destroy_external_semaphore(interop_semaphore_handle semaphoreHandle,
+release_external_semaphore(interop_semaphore_handle semaphoreHandle,
  const sycl::device &syclDevice,
  const sycl::context &syclContext);
 
 /**
- * @brief Destroy the external semaphore handle
+ * @brief Release the external semaphore
  *
  * @param semaphoreHandle The interop semaphore handle to destroy
  * @param syclQueue The queue in which the interop semaphore handle was
  * created
  */
 __SYCL_EXPORT void
-destroy_external_semaphore(interop_semaphore_handle semaphoreHandle,
+release_external_semaphore(interop_semaphore_handle semaphoreHandle,
  const sycl::queue &syclQueue);
 
 /**

diff --git a/sycl/plugins/cuda/pi_cuda.cpp b/sycl/plugins/cuda/pi_cuda.cpp
@@ -484,9 +484,9 @@ piextImportExternalSemaphore(pi_context Context, pi_device Device,
 }
 
 __SYCL_EXPORT pi_result
-piextDestroyExternalSemaphore(pi_context Context, pi_device Device,
+piextReleaseExternalSemaphore(pi_context Context, pi_device Device,
  pi_interop_semaphore_handle SemHandle) {
- return pi2ur::piextDestroyExternalSemaphore(Context, Device, SemHandle);
+ return pi2ur::piextReleaseExternalSemaphore(Context, Device, SemHandle);
 }
 
 __SYCL_EXPORT pi_result piextWaitExternalSemaphore(

diff --git a/sycl/plugins/hip/pi_hip.cpp b/sycl/plugins/hip/pi_hip.cpp
@@ -487,9 +487,9 @@ piextImportExternalSemaphore(pi_context Context, pi_device Device,
 }
 
 __SYCL_EXPORT pi_result
-piextDestroyExternalSemaphore(pi_context Context, pi_device Device,
+piextReleaseExternalSemaphore(pi_context Context, pi_device Device,
  pi_interop_semaphore_handle SemHandle) {
- return pi2ur::piextDestroyExternalSemaphore(Context, Device, SemHandle);
+ return pi2ur::piextReleaseExternalSemaphore(Context, Device, SemHandle);
 }
 
 __SYCL_EXPORT pi_result piextWaitExternalSemaphore(

diff --git a/sycl/plugins/level_zero/pi_level_zero.cpp b/sycl/plugins/level_zero/pi_level_zero.cpp
@@ -496,9 +496,9 @@ piextImportExternalSemaphore(pi_context Context, pi_device Device,
 }
 
 __SYCL_EXPORT pi_result
-piextDestroyExternalSemaphore(pi_context Context, pi_device Device,
+piextReleaseExternalSemaphore(pi_context Context, pi_device Device,
  pi_interop_semaphore_handle SemHandle) {
- return pi2ur::piextDestroyExternalSemaphore(Context, Device, SemHandle);
+ return pi2ur::piextReleaseExternalSemaphore(Context, Device, SemHandle);
 }
 
 __SYCL_EXPORT pi_result piextWaitExternalSemaphore(

diff --git a/sycl/plugins/native_cpu/pi_native_cpu.cpp b/sycl/plugins/native_cpu/pi_native_cpu.cpp
@@ -491,9 +491,9 @@ piextImportExternalSemaphore(pi_context Context, pi_device Device,
 }
 
 __SYCL_EXPORT pi_result
-piextDestroyExternalSemaphore(pi_context Context, pi_device Device,
+piextReleaseExternalSemaphore(pi_context Context, pi_device Device,
  pi_interop_semaphore_handle SemHandle) {
- return pi2ur::piextDestroyExternalSemaphore(Context, Device, SemHandle);
+ return pi2ur::piextReleaseExternalSemaphore(Context, Device, SemHandle);
 }
 
 __SYCL_EXPORT pi_result piextWaitExternalSemaphore(

diff --git a/sycl/plugins/opencl/pi_opencl.cpp b/sycl/plugins/opencl/pi_opencl.cpp
@@ -467,9 +467,9 @@ piextImportExternalSemaphore(pi_context Context, pi_device Device,
  RetHandle);
 }
 
-pi_result piextDestroyExternalSemaphore(pi_context Context, pi_device Device,
+pi_result piextReleaseExternalSemaphore(pi_context Context, pi_device Device,
  pi_interop_semaphore_handle SemHandle) {
- return pi2ur::piextDestroyExternalSemaphore(Context, Device, SemHandle);
+ return pi2ur::piextReleaseExternalSemaphore(Context, Device, SemHandle);
 }
 
 __SYCL_EXPORT pi_result piextWaitExternalSemaphore(

diff --git a/sycl/plugins/unified_runtime/CMakeLists.txt b/sycl/plugins/unified_runtime/CMakeLists.txt
@@ -100,12 +100,12 @@ if(SYCL_PI_UR_USE_FETCH_CONTENT)
  endfunction()
 
  set(UNIFIED_RUNTIME_REPO "https://github.com/oneapi-src/unified-runtime.git")
- # commit 6c2329edef40cdacb8e28704eb02172c4c17a903
+ # commit 0abf37072567c27ff412ea7acfce7b72b9e4b3c0
  # Author: Kenneth Benzie (Benie) <k.benzie@codeplay.com>
- # Date: Tue Jul 16 21:04:25 2024 +0100
- # Merge pull request #1743 from Seanst98/sean/copy-const-qualifiers
- # [Bindless][Exp] Add const-qualifier to Src param in urBindlessImagesImageCopyExp
- set(UNIFIED_RUNTIME_TAG 6c2329edef40cdacb8e28704eb02172c4c17a903)
+ # Date: Wed Jul 17 19:12:31 2024 +0100
+ # Reinstate "Merge pull request #1855 from Seanst98/sean/rename-external-semaphore-release""
+ # This reverts commit b26e53cdbd178ee03c3e8252aa00e596deb1f313.
+ set(UNIFIED_RUNTIME_TAG 0abf37072567c27ff412ea7acfce7b72b9e4b3c0)
 
  fetch_adapter_source(level_zero
  ${UNIFIED_RUNTIME_REPO}

diff --git a/sycl/plugins/unified_runtime/pi2ur.hpp b/sycl/plugins/unified_runtime/pi2ur.hpp
@@ -5618,7 +5618,7 @@ piextImportExternalSemaphore(pi_context Context, pi_device Device,
 }
 
 inline pi_result
-piextDestroyExternalSemaphore(pi_context Context, pi_device Device,
+piextReleaseExternalSemaphore(pi_context Context, pi_device Device,
  pi_interop_semaphore_handle SemHandle) {
  PI_ASSERT(Context, PI_ERROR_INVALID_CONTEXT);
  PI_ASSERT(Device, PI_ERROR_INVALID_DEVICE);
@@ -5628,7 +5628,7 @@ piextDestroyExternalSemaphore(pi_context Context, pi_device Device,
  auto UrSemHandle =
  reinterpret_cast<ur_exp_interop_semaphore_handle_t>(SemHandle);
 
- HANDLE_ERRORS(urBindlessImagesDestroyExternalSemaphoreExp(UrContext, UrDevice,
+ HANDLE_ERRORS(urBindlessImagesReleaseExternalSemaphoreExp(UrContext, UrDevice,
  UrSemHandle));
 
  return PI_SUCCESS;

diff --git a/sycl/plugins/unified_runtime/pi_unified_runtime.cpp b/sycl/plugins/unified_runtime/pi_unified_runtime.cpp
@@ -1419,9 +1419,9 @@ piextImportExternalSemaphore(pi_context Context, pi_device Device,
 }
 
 __SYCL_EXPORT pi_result
-piextDestroyExternalSemaphore(pi_context Context, pi_device Device,
+piextReleaseExternalSemaphore(pi_context Context, pi_device Device,
  pi_interop_semaphore_handle SemHandle) {
- return pi2ur::piextDestroyExternalSemaphore(Context, Device, SemHandle);
+ return pi2ur::piextReleaseExternalSemaphore(Context, Device, SemHandle);
 }
 
 __SYCL_EXPORT pi_result piextWaitExternalSemaphore(

diff --git a/sycl/source/detail/bindless_images.cpp b/sycl/source/detail/bindless_images.cpp
@@ -620,7 +620,7 @@ __SYCL_EXPORT interop_semaphore_handle import_external_semaphore(
 }
 
 __SYCL_EXPORT void
-destroy_external_semaphore(interop_semaphore_handle semaphoreHandle,
+release_external_semaphore(interop_semaphore_handle semaphoreHandle,
  const sycl::device &syclDevice,
  const sycl::context &syclContext) {
  std::shared_ptr<sycl::detail::context_impl> CtxImpl =
@@ -632,14 +632,14 @@ destroy_external_semaphore(interop_semaphore_handle semaphoreHandle,
  pi_device Device = DevImpl->getHandleRef();
 
  Plugin->call<sycl::errc::invalid,
- sycl::detail::PiApiKind::piextDestroyExternalSemaphore>(
+ sycl::detail::PiApiKind::piextReleaseExternalSemaphore>(
  C, Device, (pi_interop_semaphore_handle)semaphoreHandle.raw_handle);
 }
 
 __SYCL_EXPORT void
-destroy_external_semaphore(interop_semaphore_handle semaphoreHandle,
+release_external_semaphore(interop_semaphore_handle semaphoreHandle,
  const sycl::queue &syclQueue) {
- destroy_external_semaphore(semaphoreHandle, syclQueue.get_device(),
+ release_external_semaphore(semaphoreHandle, syclQueue.get_device(),
  syclQueue.get_context());
 }
 

diff --git a/sycl/test-e2e/bindless_images/vulkan_interop/unsampled_images.cpp b/sycl/test-e2e/bindless_images/vulkan_interop/unsampled_images.cpp
@@ -134,9 +134,9 @@ create_test_handles(sycl::context &ctxt, sycl::device &dev,
 }
 
 void cleanup_test(sycl::context &ctxt, sycl::device &dev, handles_t handles) {
- syclexp::destroy_external_semaphore(
+ syclexp::release_external_semaphore(
  handles.sycl_wait_interop_semaphore_handle, dev, ctxt);
- syclexp::destroy_external_semaphore(
+ syclexp::release_external_semaphore(
  handles.sycl_done_interop_semaphore_handle, dev, ctxt);
  syclexp::destroy_image_handle(handles.input_1, dev, ctxt);
  syclexp::destroy_image_handle(handles.input_2, dev, ctxt);

diff --git a/sycl/test/abi/pi_cuda_symbol_check.dump b/sycl/test/abi/pi_cuda_symbol_check.dump
@@ -106,14 +106,14 @@ piextCommandBufferUpdateKernelLaunch
 piextContextCreateWithNativeHandle
 piextContextGetNativeHandle
 piextContextSetExtendedDeleter
-piextDestroyExternalSemaphore
 piextDeviceCreateWithNativeHandle
 piextDeviceGetNativeHandle
 piextDeviceSelectBinary
 piextDisablePeerAccess
 piextEnablePeerAccess
 piextEnqueueCommandBuffer
 piextEnqueueCooperativeKernelLaunch
+piextEnqueueKernelLaunchCustom
 piextEnqueueNativeCommand
 piextEnqueueReadHostPipe
 piextEnqueueWriteHostPipe
@@ -157,6 +157,7 @@ piextProgramSetSpecializationConstant
 piextQueueCreate
 piextQueueCreateWithNativeHandle
 piextQueueGetNativeHandle
+piextReleaseExternalSemaphore
 piextSignalExternalSemaphore
 piextUSMDeviceAlloc
 piextUSMEnqueueFill
@@ -181,4 +182,3 @@ piextVirtualMemReserve
 piextVirtualMemSetAccess
 piextVirtualMemUnmap
 piextWaitExternalSemaphore
-piextEnqueueKernelLaunchCustom
diff --git a/sycl/test/abi/pi_hip_symbol_check.dump b/sycl/test/abi/pi_hip_symbol_check.dump
@@ -106,7 +106,7 @@ piextCommandBufferUpdateKernelLaunch
 piextContextCreateWithNativeHandle
 piextContextGetNativeHandle
 piextContextSetExtendedDeleter
-piextDestroyExternalSemaphore
+piextReleaseExternalSemaphore
 piextDeviceCreateWithNativeHandle
 piextDeviceGetNativeHandle
 piextDeviceSelectBinary

diff --git a/sycl/test/abi/pi_level_zero_symbol_check.dump b/sycl/test/abi/pi_level_zero_symbol_check.dump
@@ -105,14 +105,14 @@ piextCommandBufferUpdateKernelLaunch
 piextContextCreateWithNativeHandle
 piextContextGetNativeHandle
 piextContextSetExtendedDeleter
-piextDestroyExternalSemaphore
 piextDeviceCreateWithNativeHandle
 piextDeviceGetNativeHandle
 piextDeviceSelectBinary
 piextDisablePeerAccess
 piextEnablePeerAccess
 piextEnqueueCommandBuffer
 piextEnqueueCooperativeKernelLaunch
+piextEnqueueKernelLaunchCustom
 piextEnqueueNativeCommand
 piextEnqueueReadHostPipe
 piextEnqueueWriteHostPipe
@@ -156,6 +156,7 @@ piextProgramSetSpecializationConstant
 piextQueueCreate
 piextQueueCreateWithNativeHandle
 piextQueueGetNativeHandle
+piextReleaseExternalSemaphore
 piextSignalExternalSemaphore
 piextUSMDeviceAlloc
 piextUSMEnqueueFill
@@ -180,4 +181,3 @@ piextVirtualMemReserve
 piextVirtualMemSetAccess
 piextVirtualMemUnmap
 piextWaitExternalSemaphore
-piextEnqueueKernelLaunchCustom
diff --git a/sycl/test/abi/pi_nativecpu_symbol_check.dump b/sycl/test/abi/pi_nativecpu_symbol_check.dump
@@ -106,7 +106,7 @@ piextCommandBufferUpdateKernelLaunch
 piextContextCreateWithNativeHandle
 piextContextGetNativeHandle
 piextContextSetExtendedDeleter
-piextDestroyExternalSemaphore
+piextReleaseExternalSemaphore
 piextDeviceCreateWithNativeHandle
 piextDeviceGetNativeHandle
 piextDeviceSelectBinary

diff --git a/sycl/test/abi/pi_opencl_symbol_check.dump b/sycl/test/abi/pi_opencl_symbol_check.dump
@@ -105,14 +105,14 @@ piextCommandBufferUpdateKernelLaunch
 piextContextCreateWithNativeHandle
 piextContextGetNativeHandle
 piextContextSetExtendedDeleter
-piextDestroyExternalSemaphore
 piextDeviceCreateWithNativeHandle
 piextDeviceGetNativeHandle
 piextDeviceSelectBinary
 piextDisablePeerAccess
 piextEnablePeerAccess
 piextEnqueueCommandBuffer
 piextEnqueueCooperativeKernelLaunch
+piextEnqueueKernelLaunchCustom
 piextEnqueueNativeCommand
 piextEnqueueReadHostPipe
 piextEnqueueWriteHostPipe
@@ -133,9 +133,6 @@ piextMemGetNativeHandle
 piextMemImageAllocate
 piextMemImageCopy
 piextMemImageCreateWithNativeHandle
-piextPhysicalMemCreate
-piextPhysicalMemRelease
-piextPhysicalMemRetain
 piextMemImageFree
 piextMemImageGetInfo
 piextMemMapExternalArray
@@ -147,6 +144,9 @@ piextMemSampledImageHandleDestroy
 piextMemUnsampledImageCreate
 piextMemUnsampledImageHandleDestroy
 piextPeerAccessGetInfo
+piextPhysicalMemCreate
+piextPhysicalMemRelease
+piextPhysicalMemRetain
 piextPlatformCreateWithNativeHandle
 piextPlatformGetNativeHandle
 piextPluginGetOpaqueData
@@ -156,6 +156,7 @@ piextProgramSetSpecializationConstant
 piextQueueCreate
 piextQueueCreateWithNativeHandle
 piextQueueGetNativeHandle
+piextReleaseExternalSemaphore
 piextSignalExternalSemaphore
 piextUSMDeviceAlloc
 piextUSMEnqueueFill
@@ -180,4 +181,3 @@ piextVirtualMemReserve
 piextVirtualMemSetAccess
 piextVirtualMemUnmap
 piextWaitExternalSemaphore
-piextEnqueueKernelLaunchCustom
diff --git a/sycl/test/abi/sycl_symbols_linux.dump b/sycl/test/abi/sycl_symbols_linux.dump
@@ -3045,8 +3045,8 @@ _ZN4sycl3_V13ext6oneapi12experimental25import_external_semaphoreINS3_21resource_
 _ZN4sycl3_V13ext6oneapi12experimental25import_external_semaphoreINS3_21resource_win32_handleEEENS3_24interop_semaphore_handleENS3_29external_semaphore_descriptorIT_EERKNS0_6deviceERKNS0_7contextE
 _ZN4sycl3_V13ext6oneapi12experimental25map_external_image_memoryENS3_18interop_mem_handleERKNS3_16image_descriptorERKNS0_5queueE
 _ZN4sycl3_V13ext6oneapi12experimental25map_external_image_memoryENS3_18interop_mem_handleERKNS3_16image_descriptorERKNS0_6deviceERKNS0_7contextE
-_ZN4sycl3_V13ext6oneapi12experimental26destroy_external_semaphoreENS3_24interop_semaphore_handleERKNS0_5queueE
-_ZN4sycl3_V13ext6oneapi12experimental26destroy_external_semaphoreENS3_24interop_semaphore_handleERKNS0_6deviceERKNS0_7contextE
+_ZN4sycl3_V13ext6oneapi12experimental26release_external_semaphoreENS3_24interop_semaphore_handleERKNS0_5queueE
+_ZN4sycl3_V13ext6oneapi12experimental26release_external_semaphoreENS3_24interop_semaphore_handleERKNS0_6deviceERKNS0_7contextE
 _ZN4sycl3_V13ext6oneapi12experimental4node12update_rangeILi1EEEvNS0_5rangeIXT_EEE
 _ZN4sycl3_V13ext6oneapi12experimental4node12update_rangeILi2EEEvNS0_5rangeIXT_EEE
 _ZN4sycl3_V13ext6oneapi12experimental4node12update_rangeILi3EEEvNS0_5rangeIXT_EEE