[SYCL][Bindless][UR][L0][E2E] Fix linear interop memory and L0 V1 adapter leaks. (#18353)

This patch fixes the mapping of interop memory to a linear range
represented by a `void*`. The SYCL Bindless Images spec is clarified
with wording to indicate which free APIs should be used on mapped
imported memory.

Using `sycl::free` for freeing mapped imported linear memory regions
does not work for the LevelZero adapter, as the backend needs to call
`zeMemFree` directly - it cannot go through the regular `sycl::free`
code as that will use UMF free functions by default. This is invalid for
memory regions mapped using `map_external_linear_memory`.

The `unmap_external_linear_memory` SYCL API has been added to the
Bindless Images specification to remedy this problem. An
`unmap_external_image_memory` has also been added.

This patch also introduces an E2E test which verifies that a Vulkan
buffer's memory can be correctly imported into SYCL and its data
retrieved from and written to within a SYCL kernel by using purely USM
pointers (i.e. without using bindless images). This is a step towards
extending the test coverage of interop functionality currently in the
Bindless Images extension, with the goal being at some point splitting
the interop functionality into one or more separate extensions.

Two other fixes have been made in the LevelZero UR adapter.

A leaked `ze_image_handle_t` object has been fixed in the LevelZero V1
adapter. The previous implementation incorrectly reinterpreted bindless
memory handles as `ur_mem_handle_t` types. The implementation of
`urBindlessImagesImageFreeExp` is now unified between V1 and V2,
removing the leak. As such the `level_zero/v2/image.cpp` file has been
removed.

The `urMemoryHandle` member of `ur_ze_external_memory_data` has been
removed. Aside from being incorrectly reinterpreted from
`ur_bindless_mem_handle_t`, the LevelZero adapter does not need to track
the memory handle for external memory resources.

Author: przemektmalon

sycl/doc/extensions/experimental/sycl_ext_oneapi_bindless_images.asciidoc

@@ -2078,6 +2078,10 @@ the same way as memory allocated through `alloc_image_mem`,
 operations also work with imported memory mapped to `image_mem_handle` and 
 `void *` types.
 
+An `external_mem` handle can only be mapped to a single `image_mem_handle` or
+`void *` at any one time. Attempting to map a single `external_mem` handle to
+more than one `image_mem_handle` or `void *` is considered undefined behaviour.
+
 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 
@@ -2093,11 +2097,41 @@ the external API. The current supported importable image types are `standard`
 and `mipmap`. Attempting to import other image types will result in undefined 
 behaviour.
 
-Once a user has finished operating on imported memory, they must ensure that 
-they destroy the imported memory handle through `release_external_memory`.
+Once a user has finished operating on mapped memory, they must ensure that they
+unmap that memory.
+
+Memory mapped using `map_external_image_memory` should be unmapped using
+`unmap_external_image_memory`. The `image_type` parameter passed to this
+function must reflect the `image_type` of the image descriptor used when the
+memory was originally mapped. Passing an `image_type` value different to that of
+the value used in the image descriptor when the memory was originally mapped
+will result in undefined behaviour.
 
-`release_external_memory` can only accept `external_mem` objects that were
-created through `import_external_memory`.
+Memory mapped using `map_external_linear_memory` should be unmapped using
+`unmap_external_linear_memory`.
+
+```cpp
+namespace sycl::ext::oneapi::experimental {
+
+void unmap_external_image_memory(image_mem_handle mappedImageMem,
+                                 image_type imageType,
+                                 const sycl::device &syclDevice,
+                                 const sycl::context &syclContext);
+void unmap_external_image_memory(image_mem_handle mappedImageMem,
+                                 image_type imageType,
+                                 const sycl::queue &syclQueue);
+
+void unmap_external_linear_memory(void *mappedLinearMem,
+                                 const sycl::device &syclDevice,
+                                 const sycl::context &syclContext);
+void unmap_external_linear_memory(void *mappedLinearMem,
+                                  const sycl::queue &syclQueue);
+}
+```
+
+Once all memory mapped from a given `external_mem` handle has been unmapped,
+and the user has finished operating on the external memory, they should then
+release the `externa_mem` handle using `release_external_memory`.
 
 ```cpp
 namespace sycl::ext::oneapi::experimental {
@@ -2110,9 +2144,6 @@ void release_external_memory(external_mem externalMem,
 }
 ```
 
-Destroying or freeing any imported memory through `image_mem_free` or 
-`sycl::free` will result in undefined behavior.
-
 === Importing external semaphores [[importing_external_semaphores]]
 
 In addition to proposing importation of external memory resources, we also 

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

@@ -285,6 +285,54 @@ __SYCL_EXPORT void release_external_memory(external_mem externalMem,
 __SYCL_EXPORT void release_external_memory(external_mem externalMem,
                                            const sycl::queue &syclQueue);
 
+/**
+ *  @brief   Unmap external linear memory region
+ *
+ *  @param   mappedLinearMem Pointer to the mapped linear memory region to unmap
+ *  @param   syclDevice  The device in which the external memory was created
+ *  @param   syclContext The context in which the external memory was created
+ */
+__SYCL_EXPORT void
+unmap_external_linear_memory(void *mappedLinearMem,
+                             const sycl::device &syclDevice,
+                             const sycl::context &syclContext);
+
+/**
+ *  @brief   Unmap external linear memory region
+ *
+ *  @param   mappedLinearMem Pointer to the mapped linear memory region to unmap
+ *  @param   syclQueue The queue in which the external memory was created
+ */
+inline void unmap_external_linear_memory(void *mappedLinearMem,
+                                         const sycl::queue &syclQueue) {
+  unmap_external_linear_memory(mappedLinearMem, syclQueue.get_device(),
+                               syclQueue.get_context());
+}
+
+/**
+ *  @brief   Unmap external image memory
+ *
+ *  @param   mappedImageMem Handle to the mapped image memory to unmap
+ *  @param   syclDevice  The device in which the external memory was created
+ *  @param   syclContext The context in which the external memory was created
+ */
+__SYCL_EXPORT void unmap_external_image_memory(
+    image_mem_handle mappedImageMem, image_type imageType,
+    const sycl::device &syclDevice, const sycl::context &syclContext);
+
+/**
+ *  @brief   Unmap external image memory
+ *
+ *  @param   mappedImageMem Handle to the mapped image memory to unmap
+ *  @param   syclQueue The queue in which the external memory was created
+ */
+inline void unmap_external_image_memory(image_mem_handle mappedImageMem,
+                                        image_type imageType,
+                                        const sycl::queue &syclQueue) {
+  unmap_external_image_memory(mappedImageMem, imageType, syclQueue.get_device(),
+                              syclQueue.get_context());
+}
+
 /**
  *  @brief   Create an image and return the device image handle
  *

sycl/source/detail/bindless_images.cpp

@@ -621,6 +621,30 @@ __SYCL_EXPORT void release_external_memory(external_mem extMem,
                           syclQueue.get_context());
 }
 
+__SYCL_EXPORT void
+unmap_external_linear_memory(void *mappedLinearRegion,
+                             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::AdapterPtr &Adapter = CtxImpl->getAdapter();
+
+  Adapter->call<
+      sycl::errc::invalid,
+      sycl::detail::UrApiKind::urBindlessImagesFreeMappedLinearMemoryExp>(
+      C, Device, mappedLinearRegion);
+}
+
+__SYCL_EXPORT void unmap_external_image_memory(
+    image_mem_handle mappedImageMem, image_type imageType,
+    const sycl::device &syclDevice, const sycl::context &syclContext) {
+  free_image_mem(mappedImageMem, imageType, syclDevice, syclContext);
+}
+
 template <>
 __SYCL_EXPORT external_semaphore import_external_semaphore(
     external_semaphore_descriptor<resource_fd> externalSemaphoreDesc,