[SYCL][Bindless][Doc] Rename interop related structs/funcs to external (#14444)

Rename related interop structs/funcs with "external" keyword over
"interop" to align better with existing structs/funcs and other 3rd
party APIs.

Remove "handle" keyword from imported external memory/semaphore objects
to distinguish between 3rd party external handles and imported external
handles.

---------

Co-authored-by: Sean Stirling <[email protected]>
Co-authored-by: chedy.najjar <[email protected]>

Author: 3 people

llvm/include/llvm/SYCLLowerIR/DeviceConfigFile.td

@@ -53,8 +53,8 @@ def AspectExt_oneapi_bindless_images : Aspect<"ext_oneapi_bindless_images">;
 def AspectExt_oneapi_bindless_images_shared_usm : Aspect<"ext_oneapi_bindless_images_shared_usm">;
 def AspectExt_oneapi_bindless_images_1d_usm : Aspect<"ext_oneapi_bindless_images_1d_usm">;
 def AspectExt_oneapi_bindless_images_2d_usm : Aspect<"ext_oneapi_bindless_images_2d_usm">;
-def AspectExt_oneapi_interop_memory_import : Aspect<"ext_oneapi_interop_memory_import">;
-def AspectExt_oneapi_interop_semaphore_import : Aspect<"ext_oneapi_interop_semaphore_import">;
+def AspectExt_oneapi_external_memory_import : Aspect<"ext_oneapi_external_memory_import">;
+def AspectExt_oneapi_external_semaphore_import : Aspect<"ext_oneapi_external_semaphore_import">;
 def AspectExt_oneapi_mipmap : Aspect<"ext_oneapi_mipmap">;
 def AspectExt_oneapi_mipmap_anisotropy : Aspect<"ext_oneapi_mipmap_anisotropy">;
 def AspectExt_oneapi_mipmap_level_reference : Aspect<"ext_oneapi_mipmap_level_reference">;
@@ -130,16 +130,17 @@ def : TargetInfo<"__TestAspectList",
     AspectExt_intel_device_id, AspectExt_intel_memory_clock_rate, AspectExt_intel_memory_bus_width, AspectEmulated,
     AspectExt_intel_legacy_image, AspectExt_oneapi_bindless_images,
     AspectExt_oneapi_bindless_images_shared_usm, AspectExt_oneapi_bindless_images_1d_usm, AspectExt_oneapi_bindless_images_2d_usm,
-    AspectExt_oneapi_interop_memory_import, AspectExt_oneapi_interop_semaphore_import,
+    AspectExt_oneapi_external_memory_import, AspectExt_oneapi_external_semaphore_import,
     AspectExt_oneapi_mipmap, AspectExt_oneapi_mipmap_anisotropy, AspectExt_oneapi_mipmap_level_reference,
-    AspectExt_oneapi_bindless_sampled_image_fetch_3d, AspectExt_oneapi_cubemap, 
+    AspectExt_oneapi_cubemap, 
     AspectExt_oneapi_cubemap_seamless_filtering, 
     AspectExt_oneapi_image_array,
     AspectExt_oneapi_unique_addressing_per_dim,
     AspectExt_oneapi_bindless_images_sample_1d_usm,
     AspectExt_oneapi_bindless_images_sample_2d_usm,
     AspectExt_oneapi_bindless_sampled_image_fetch_1d_usm, AspectExt_oneapi_bindless_sampled_image_fetch_1d,
     AspectExt_oneapi_bindless_sampled_image_fetch_2d_usm, AspectExt_oneapi_bindless_sampled_image_fetch_2d,
+    AspectExt_oneapi_bindless_sampled_image_fetch_3d,
     AspectExt_intel_esimd,
     AspectExt_oneapi_ballot_group, AspectExt_oneapi_fixed_size_group, AspectExt_oneapi_opportunistic_group,
     AspectExt_oneapi_tangle_group, AspectExt_intel_matrix, AspectExt_oneapi_is_composite, AspectExt_oneapi_is_component,
@@ -220,8 +221,8 @@ defvar CudaMinAspects = !listconcat(AllUSMAspects, [AspectGpu, AspectFp64, Aspec
     AspectExt_oneapi_opportunistic_group, AspectExt_oneapi_graph, AspectExt_oneapi_limited_graph]);
 // Bindless images aspects are partially supported on CUDA and disabled by default at the moment.
 defvar CudaBindlessImagesAspects = [AspectExt_oneapi_bindless_images, AspectExt_oneapi_bindless_images_shared_usm,
-    AspectExt_oneapi_bindless_images_1d_usm, AspectExt_oneapi_bindless_images_2d_usm, AspectExt_oneapi_interop_memory_import,
-    AspectExt_oneapi_interop_semaphore_import, AspectExt_oneapi_mipmap, AspectExt_oneapi_mipmap_anisotropy,
+    AspectExt_oneapi_bindless_images_1d_usm, AspectExt_oneapi_bindless_images_2d_usm, AspectExt_oneapi_external_memory_import,
+    AspectExt_oneapi_external_semaphore_import, AspectExt_oneapi_mipmap, AspectExt_oneapi_mipmap_anisotropy,
     AspectExt_oneapi_mipmap_level_reference, AspectExt_oneapi_cubemap, AspectExt_oneapi_cubemap_seamless_filtering,
     AspectExt_oneapi_image_array, AspectExt_oneapi_unique_addressing_per_dim, AspectExt_oneapi_bindless_images_sample_2d_usm,
     AspectExt_oneapi_bindless_images_sample_2d_usm];

sycl/cmake/modules/FetchUnifiedRuntime.cmake

@@ -116,13 +116,12 @@ if(SYCL_PI_UR_USE_FETCH_CONTENT)
   endfunction()
 
   set(UNIFIED_RUNTIME_REPO "https://github.com/oneapi-src/unified-runtime.git")
-  # commit a985a81dc9ba8adfcc8b54e35ad287e97766fb3e
-  # Merge: b7b0c8b3 f772f907
-  # Author: Piotr Balcer <[email protected]>
-  # Date:   Mon Jul 29 09:11:29 2024 +0200
-  #     Merge pull request #1905 from igchor/umf_hwloc_disable
-  #     Bump UMF version to allow disabling hwloc
-  set(UNIFIED_RUNTIME_TAG a985a81dc9ba8adfcc8b54e35ad287e97766fb3e)
+  # commit bc1a28ede0df7f837047b632e00437587672c134
+  # Author: Omar Ahmed <[email protected]>
+  # Date:   Mon Jul 29 16:44:58 2024 +0100
+  #     Merge pull request #1819 from DBDuncan/sean/rename-interop-to-external
+  #    [Bindless][Exp] Rename interop related structs/funcs with "external"
+  set(UNIFIED_RUNTIME_TAG bc1a28ede0df7f837047b632e00437587672c134)
 
   set(UMF_BUILD_EXAMPLES OFF CACHE INTERNAL "EXAMPLES")
   # Due to the use of dependentloadflag and no installer for UMF and hwloc we need

sycl/doc/extensions/experimental/sycl_ext_oneapi_bindless_images.asciidoc

@@ -1591,9 +1591,9 @@ The device aspect descriptors for these queries are:
 [frame="none",options="header"]
 |======================
 |Device descriptor |Description
-|`aspect::ext_oneapi_interop_memory_import` | Indicates if the device supports 
+|`aspect::ext_oneapi_external_memory_import` | Indicates if the device supports 
 importing external memory resources.
-|`aspect::ext_oneapi_interop_semaphore_import`` | Indicates if the device 
+|`aspect::ext_oneapi_external_semaphore_import`` | Indicates if the device 
 supports importing external semaphore resources.
 |======================
 
@@ -1687,35 +1687,35 @@ resource type.
 ```cpp
 namespace sycl::ext::oneapi::experimental {
 
-struct interop_mem_handle {
+struct external_mem {
   using raw_handle_type = /* Implementation defined */;
   raw_handle_type raw_handle;
 };
 
 template <typename ResourceType>
-interop_mem_handle import_external_memory(
+external_mem import_external_memory(
     external_mem_descriptor<ResourceType> externalMemDescriptor,
     const sycl::device &syclDevice,
     const sycl::context &syclContext);
 
 template <typename ResourceType>
-interop_mem_handle import_external_memory(
+external_mem import_external_memory(
     external_mem_descriptor<ResourceType> externalMemDescriptor,
     const sycl::queue &syclQueue);
 
 image_mem_handle map_external_image_memory(
-    interop_mem_handle interopMemHandle,
+    external_mem externalMemHandle,
     const image_descriptor &imageDescriptor,
     const sycl::device &syclDevice,
     const sycl::context &syclContext);
 image_mem_handle map_external_image_memory(
-    interop_mem_handle interopMemHandle,
+    external_mem externalMemHandle,
     const image_descriptor &imageDescriptor,
     const sycl::queue &syclQueue);
 }
 ```
 
-The resulting `interop_mem_handle` can then be mapped, where the resulting type 
+The resulting `external_mem` can then be mapped, where the resulting type 
 is an `image_mem_handle`. This can be used to construct images in the same way 
 as memory allocated through `alloc_image_mem`. The `ext_oneapi_copy` operations 
 also work with imported memory mapped to `image_mem_handle` types.
@@ -1734,16 +1734,16 @@ behaviour.
 Once a user has finished operating on imported memory, they must ensure that 
 they destroy the imported memory handle through `release_external_memory`.
 
-`release_external_memory` can only accept `interop_mem_handles` that were
+`release_external_memory` can only accept `external_mem` objects that were
 created through `import_external_memory`.
 
 ```cpp
 namespace sycl::ext::oneapi::experimental {
 
-void release_external_memory(interop_mem_handle interopMem,
+void release_external_memory(external_mem externalMem,
                              const sycl::device &syclDevice,
                              const sycl::context &syclContext);
-void release_external_memory(interop_mem_handle interopMem,
+void release_external_memory(external_mem externalMem,
                              const sycl::queue &syclQueue);
 }
 ```
@@ -1807,27 +1807,27 @@ compatible with the `resource_fd` resource type.
 ```cpp
 namespace sycl::ext::oneapi::experimental {
 
-struct interop_semaphore_handle {
+struct external_semaphore {
   using raw_handle_type = /* Implementation defined */;
   raw_handle_type raw_handle;
 };
 
 template <typename ResourceType>
-interop_semaphore_handle import_external_semaphore(
+external_semaphore import_external_semaphore(
     external_semaphore_descriptor<ResourceType>
         externalSemaphoreDescriptor,
     const sycl::device &syclDevice,
     const sycl::context &syclContext);
 
 template <typename ResourceType>
-interop_semaphore_handle import_external_semaphore(
+external_semaphore import_external_semaphore(
     external_semaphore_descriptor<ResourceType>
         externalSemaphoreDescriptor,
     const sycl::queue &syclQueue);
 }
 ```
 
-The resulting `interop_semaphore_handle` can then be used in a SYCL command 
+The resulting `external_semaphore` can then be used in a SYCL command 
 group, to either wait until the semaphore signalled, or signal the semaphore.
 
 If the type of semaphore imported supports setting the state of discrete 
@@ -1843,77 +1843,77 @@ namespace sycl {
 class handler {
 public:
   void ext_oneapi_wait_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle);
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore);
 
   void ext_oneapi_wait_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       uint64_t wait_value);
 
   void ext_oneapi_signal_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle);
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore);
 
   void ext_oneapi_signal_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       uint64_t signal_value);
 };
 
 class queue {
 public:
   event ext_oneapi_wait_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle);
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore);
   event ext_oneapi_wait_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       event DepEvent);
   event ext_oneapi_wait_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       const std::vector<event> &DepEvents);
 
   event ext_oneapi_wait_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       uint64_t wait_value);
   event ext_oneapi_wait_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       uint64_t wait_value, 
       event DepEvent);
   event ext_oneapi_wait_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       uint64_t wait_value, 
       const std::vector<event> &DepEvents);
 
   event ext_oneapi_signal_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle);
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore);
   event ext_oneapi_signal_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       event DepEvent);
   event ext_oneapi_signal_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       const std::vector<event> &DepEvents);
 
   event ext_oneapi_signal_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       uint64_t signal_value);
   event ext_oneapi_signal_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       uint64_t signal_value,
       event DepEvent);
   event ext_oneapi_signal_external_semaphore(
-      ext::oneapi::experimental::interop_semaphore_handle
-          interop_semaphore_handle,
+      ext::oneapi::experimental::external_semaphore
+          external_semaphore,
       uint64_t signal_value,
       const std::vector<event> &DepEvents);
 };
@@ -1952,11 +1952,11 @@ access the external semaphore once they are no longer required through
 ```cpp
 namespace sycl::ext::oneapi::experimental {
 
-void release_external_semaphore(interop_semaphore_handle semaphoreHandle,
+void release_external_semaphore(external_semaphore semaphoreHandle,
                                 const sycl::device &syclDevice,
                                 const sycl::context &syclContext);
 
-void release_external_semaphore(interop_semaphore_handle semaphoreHandle,
+void release_external_semaphore(external_semaphore semaphoreHandle,
                                 const sycl::queue &syclQueue);
 
 }
@@ -2547,34 +2547,34 @@ sycl::ext::oneapi::experimental::external_semaphore_descriptor<
 
 try {
   // Extension: import external semaphores
-  sycl::ext::oneapi::experimental::interop_semaphore_handle
-      wait_interop_semaphore_handle =
+  sycl::ext::oneapi::experimental::external_semaphore
+      wait_external_semaphore =
           sycl::ext::oneapi::experimental::import_external_semaphore(
               wait_external_semaphore_desc, queue);
 
-  sycl::ext::oneapi::experimental::interop_semaphore_handle
-      done_interop_semaphore_handle =
+  sycl::ext::oneapi::experimental::external_semaphore
+      done_external_semaphore =
           sycl::ext::oneapi::experimental::import_external_semaphore(
               done_external_semaphore_desc, queue);
 
   // Extension: import external memory from descriptors
-  sycl::ext::oneapi::experimental::interop_mem_handle
-      input_interop_mem_handle =
+  sycl::ext::oneapi::experimental::external_mem
+      input_external_mem =
           sycl::ext::oneapi::experimental::import_external_memory(
               input_ext_mem_desc, queue);
 
-  sycl::ext::oneapi::experimental::interop_mem_handle
-      output_interop_mem_handle =
+  sycl::ext::oneapi::experimental::external_mem
+      output_external_mem =
           sycl::ext::oneapi::experimental::import_external_memory(
               output_ext_mem_desc, queue);
 
   // Extension: map imported external memory to image memory
   sycl::ext::oneapi::experimental::image_mem_handle input_mapped_mem_handle =
       sycl::ext::oneapi::experimental::map_external_image_memory(
-          input_interop_mem_handle, desc, queue);
+          input_external_mem, desc, queue);
   sycl::ext::oneapi::experimental::image_mem_handle output_mapped_mem_handle =
       sycl::ext::oneapi::experimental::map_external_image_memory(
-          output_interop_mem_handle, desc, queue);
+          output_external_mem, desc, queue);
 
   // Extension: create images from mapped memory and return the handles
   sycl::ext::oneapi::experimental::unsampled_image_handle img_input =
@@ -2585,7 +2585,7 @@ try {
           output_mapped_mem_handle, desc, queue);
 
   // Extension: wait for imported semaphore
-  q.ext_oneapi_wait_external_semaphore(wait_interop_semaphore_handle)
+  q.ext_oneapi_wait_external_semaphore(wait_external_semaphore)
 
   // Submit our kernel that depends on imported "wait_semaphore_file_descriptor"
   q.submit([&](sycl::handler &cgh) {
@@ -2610,7 +2610,7 @@ try {
   });
 
   // Extension: signal imported semaphore
-  q.ext_oneapi_signal_external_semaphore(done_interop_semaphore_handle)
+  q.ext_oneapi_signal_external_semaphore(done_external_semaphore)
 
   // The external API can now use the semaphore it exported to 
   // "done_semaphore_file_descriptor" to schedule its own command submissions
@@ -2619,13 +2619,13 @@ try {
 
   // Extension: destroy all external resources
   sycl::ext::oneapi::experimental::release_external_memory(
-      input_interop_mem_handle, queue);
+      input_external_mem, queue);
   sycl::ext::oneapi::experimental::release_external_memory(
-      output_interop_mem_handle, queue);
+      output_external_mem, queue);
   sycl::ext::oneapi::experimental::release_external_semaphore(
-      wait_interop_semaphore_handle, queue);
+      wait_external_semaphore, queue);
   sycl::ext::oneapi::experimental::release_external_semaphore(
-      done_interop_semaphore_handle, queue);
+      done_external_semaphore, queue);
   sycl::ext::oneapi::experimental::destroy_image_handle(img_input, queue);
   sycl::ext::oneapi::experimental::destroy_image_handle(img_output, queue);
 } catch (sycl::exception e) {
@@ -2859,4 +2859,11 @@ These features still need to be handled:
                    3D USM images as they are not supported on any platform.
                  - Refine the description of `ext_oneapi_bindless_images` aspect
                    to indicate support for bindless image APIs.
+|5.16|2024-07-24| - Renamed interop aspect queries, handles, semaphore wait and 
+                    signal functions, by replacing `interop` with `external` for 
+                    consistency with other interop related structs/funcs and 
+                    3rd party interop API naming.
+                  - Removed `handle` keyword from `interop_xxx_handle` to 
+                    clear up possible confusion between 3rd party interop 
+                    handles and the imported `interop_xxx_handle`.
 |======================