[SYCL][Bindless] Add interop memory mapping to USM. (#14701)

This patch introduces `map_external_linear_memory` to enable mapping
interop memory to linear USM, returning a `void *`.

The PI function `piextMemMapExternalLinearMemory` has been added to
enable this in the PI layer.

A Vulkan test case has been added to test this functionality.

---------

Co-authored-by: Duncan Brawley <duncan.brawley@codeplay.com>

Author: przemektmalon

sycl/cmake/modules/FetchUnifiedRuntime.cmake

@@ -115,14 +115,14 @@ if(SYCL_PI_UR_USE_FETCH_CONTENT)
       CACHE PATH "Path to external '${name}' adapter source dir" FORCE)
   endfunction()
 
-set(UNIFIED_RUNTIME_REPO "https://github.com/oneapi-src/unified-runtime.git")
-  # commit 3e762e00bcf13d158fb58e8e8c2eabcfc8934b4e
-  # Merge: c805a71a a2a053de
+  set(UNIFIED_RUNTIME_REPO "https://github.com/oneapi-src/unified-runtime.git")
+  # commit c5d2175b5823d5b74de1e7e0d6081ab6d885bc34
+  # Merge: 99489ad4 c86beb60
   # Author: Omar Ahmed <omar.ahmed@codeplay.com>
-  # Date:   Wed Jul 31 12:26:34 2024 +0100
-  #     Merge pull request #1884 from callumfare/callum/fix_printtrace
-  #     Enable PrintTrace when SYCL UR tracing is enabled
-  set(UNIFIED_RUNTIME_TAG 3e762e00bcf13d158fb58e8e8c2eabcfc8934b4e)
+  # Date:   Wed Jul 31 14:52:26 2024 +0100
+  #     Merge pull request #1882 from przemektmalon/przemek/interop-map-memory
+  #    [Bindless][Exp] Add interop memory mapping to USM.
+  set(UNIFIED_RUNTIME_TAG c5d2175b5823d5b74de1e7e0d6081ab6d885bc34)
 
   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

@@ -1712,19 +1712,35 @@ image_mem_handle map_external_image_memory(
     external_mem externalMemHandle,
     const image_descriptor &imageDescriptor,
     const sycl::queue &syclQueue);
+
+void *map_external_linear_memory(
+    external_mem externalMemHandle,
+    uint64_t size, uint64_t offset,
+    const sycl::device &syclDevice,
+    const sycl::context &syclContext);
+void *map_external_linear_memory(
+    external_mem externalMemHandle,
+    uint64_t size, uint64_t offset,
+    const sycl::queue &syclQueue);
 }
 ```
 
 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.
-
-When calling `create_image` with an `image_mem_handle` mapped from an external 
-memory object, the user must ensure that the image descriptor they pass to 
-`create_image` has members that match or map to those of the external API. 
-A mismatch between any of the `width`, `height`, `depth`, `image_channel_type`,
-or `num_channels` members will result in undefined behavior.
+is an `image_mem_handle` or a `void *`. This can be used to construct images in
+the same way as memory allocated through `alloc_image_mem`, 
+`pitched_alloc_device`, or another USM allocation method. The `ext_oneapi_copy` 
+operations also work with imported memory mapped to `image_mem_handle` and 
+`void *` types.
+
+When calling `create_image` with an `image_mem_handle` or `void *` mapped from 
+an external memory object, the user must ensure that the image descriptor they 
+pass to `create_image` has members that match or map to those of the external 
+API. A mismatch between any of the `width`, `height`, `depth`, 
+`image_channel_type`, or `num_channels` members will result in undefined 
+behavior. Likewise, if the image is mapped to a linear USM (`void *`) region, 
+the pitch value passed to `create_image` needs to match the pitch of the image 
+as defined by the external API. Note that when external memory is mapped to a 
+linear USM region, this is device-side USM, and not accessible on the host.
 
 Additionally, the `image_type` describing the image must match to the image of 
 the external API. The current supported importable image types are `standard` 
@@ -2866,4 +2882,6 @@ These features still need to be handled:
                   - Removed `handle` keyword from `interop_xxx_handle` to 
                     clear up possible confusion between 3rd party interop 
                     handles and the imported `interop_xxx_handle`.
+|5.17|2024-07-30| - Add support for mapping external memory to linear USM using
+                    `map_external_linear_memory`.
 |======================

sycl/include/sycl/ext/oneapi/bindless_images.hpp

@@ -171,7 +171,7 @@ image_mem_handle map_external_image_memory(external_mem extMem,
                                            const sycl::context &syclContext);
 
 /**
- *  @brief   Maps an external memory handle to an image memory handle (which may
+ *  @brief   Maps an external memory object to an image memory handle (which may
  *           have a device optimized memory layout)
  *
  *  @param   extMem      External memory object
@@ -184,6 +184,36 @@ image_mem_handle map_external_image_memory(external_mem extMem,
                                            const image_descriptor &desc,
                                            const sycl::queue &syclQueue);
 
+/**
+ *  @brief   Maps an external memory object to a memory region described by the
+ *           returned void *
+ *
+ *  @param   extMem      External memory object
+ *  @param   offset      Offset of memory region to map
+ *  @param   size        Size of memory region to map
+ *  @param   syclDevice  The device in which we create our image memory handle
+ *  @param   syclContext The context in which we create our image memory handle
+ *  @return  Memory handle to externally allocated memory on the device
+ */
+__SYCL_EXPORT
+void *map_external_linear_memory(external_mem extMem, uint64_t offset,
+                                 uint64_t size, const sycl::device &syclDevice,
+                                 const sycl::context &syclContext);
+
+/**
+ *  @brief   Maps an external memory object to a memory region described by the
+ *           returned void *
+ *
+ *  @param   extMem      External memory object
+ *  @param   offset      Offset of memory region to map
+ *  @param   size        Size of memory region to map
+ *  @param   syclQueue   The queue in which we create our image memory handle
+ *  @return  Memory handle to externally allocated memory on the device
+ */
+__SYCL_EXPORT
+void *map_external_linear_memory(external_mem extMem, uint64_t offset,
+                                 uint64_t size, const sycl::queue &syclQueue);
+
 /**
  *  @brief   Import external semaphore taking an external semaphore descriptor
  *           (the type of which is dependent on the OS & external API)

sycl/source/detail/bindless_images.cpp

@@ -556,6 +556,35 @@ image_mem_handle map_external_image_memory(external_mem extMem,
                                    syclQueue.get_context());
 }
 
+__SYCL_EXPORT
+void *map_external_linear_memory(external_mem extMem, uint64_t offset,
+                                 uint64_t size, const sycl::device &syclDevice,
+                                 const sycl::context &syclContext) {
+  std::shared_ptr<sycl::detail::context_impl> CtxImpl =
+      sycl::detail::getSyclObjImpl(syclContext);
+  ur_context_handle_t C = CtxImpl->getHandleRef();
+  std::shared_ptr<sycl::detail::device_impl> DevImpl =
+      sycl::detail::getSyclObjImpl(syclDevice);
+  ur_device_handle_t Device = DevImpl->getHandleRef();
+  const sycl::detail::PluginPtr &Plugin = CtxImpl->getPlugin();
+
+  ur_exp_external_mem_handle_t urExternalMem{extMem.raw_handle};
+
+  void *retMemory;
+  Plugin->call<sycl::errc::invalid>(urBindlessImagesMapExternalLinearMemoryExp,
+                                    C, Device, offset, size, urExternalMem,
+                                    &retMemory);
+
+  return retMemory;
+}
+
+__SYCL_EXPORT
+void *map_external_linear_memory(external_mem extMem, uint64_t offset,
+                                 uint64_t size, const sycl::queue &syclQueue) {
+  return map_external_linear_memory(
+      extMem, offset, size, syclQueue.get_device(), syclQueue.get_context());
+}
+
 __SYCL_EXPORT void release_external_memory(external_mem extMem,
                                            const sycl::device &syclDevice,
                                            const sycl::context &syclContext) {