[Exp][Bindless Images] Experimental Bindless Images

scripts/core/EXP-BINDLESS-IMAGES.rst

@@ -0,0 +1,136 @@
+
+<%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+
+.. _exp-bindless-images:
+
+================================================================================
+Bindless Images
+================================================================================
+
+.. warning::
+
+    Experimental features:
+
+    *   May be replaced, updated, or removed at any time.
+    *   Do not require maintaining API/ABI stability of their own additions over
+        time.
+    *   Do not require conformance testing of their own additions.
+
+================================================================================
+Terminology
+================================================================================
+For the purposes of this document, a bindless image is one which provides
+access to the underlying data via image reference handles. At the application
+level, this allows the user to implement programs where the number of images
+is not known at compile-time, and store all handles to images -- irrespective
+of varying formats and layouts -- in some container, e.g. a dynamic array.
+
+================================================================================
+Motivation
+================================================================================
+The `DPC++ bindless images extension <https://github.com/intel/llvm/pull/8307>`_
+has sought to provide the flexibility of bindless images at the SYCL
+application level. This extension has been implemented using the CUDA backend of
+the DPC++ PI. With the movement to migrate from PI to the Unified Runtime in
+DPC++, as seen in `Port CUDA plugin to Unified Runtime
+<https://github.com/intel/llvm/pull/9512/>`_, the Unified Runtime's support for
+this experimental feature would enable the DPC++ bindless images extension to be
+migrated to UR without issue.
+
+================================================================================
+Overview
+================================================================================
+
+In this document, we propose the following experimental additions to the Unified
+Runtime:
+
+* Bindless images support
+
+  * Sampled images
+  * Unsampled images
+  * Mipmaps
+  * USM backed images
+
+* Interoperability support
+
+  * External memory
+  * Semaphores
+
+================================================================================
+API
+================================================================================
+
+--------------------------------------------------------------------------------
+Definitions
+--------------------------------------------------------------------------------
+
+* ${x}_exp_sampler_mip_properties_t
+
+The following definitions will be implementation-dependent
+
+* ${x}_exp_image_handle_t
+* ${x}_exp_image_mem_handle_t
+* ${x}_exp_interop_mem_handle_t
+* ${x}_exp_interop_semaphore_handle_t
+
+--------------------------------------------------------------------------------
+Enums
+--------------------------------------------------------------------------------
+
+* ${x}_device_info_t
+* ${x}_command_t
+* ${x}_exp_image_copy_flags_t
+
+--------------------------------------------------------------------------------
+Interface
+--------------------------------------------------------------------------------
+
+* USM
+   * ${x}USMPitchedAllocExp
+
+* Bindless Images
+   * ${x}BindlessImagesUnsampledImageHandleDestroyExp
+   * ${x}BindlessImagesSampledImageHandleDestroyExp
+   * ${x}BindlessImagesImageAllocateExp
+   * ${x}BindlessImagesImageFreeExp
+   * ${x}BindlessImagesUnsampledImageCreateExp
+   * ${x}BindlessImagesSampledImageCreateExp
+   * ${x}BindlessImagesImageCopyExp
+   * ${x}BindlessImagesImageGetInfoExp
+   * ${x}BindlessImagesMipmapGetLevelExp
+   * ${x}BindlessImagesMipmapFreeExp
+
+* Interop
+   * ${x}BindlessImagesImportOpaqueFDExp
+   * ${x}BindlessImagesMapExternalArrayExp
+   * ${x}BindlessImagesReleaseInteropExp
+   * ${x}BindlessImagesImportExternalSemaphoreOpaqueFDExp
+   * ${x}BindlessImagesDestroyExternalSemaphoreExp
+   * ${x}BindlessImagesWaitExternalSemaphoreExp
+   * ${x}BindlessImagesSignalExternalSemaphoreExp
+
+
+================================================================================
+Changelog
+================================================================================
+
++-----------+------------------------+
+| Revision  | Changes                |
++===========+========================+
+| 1         | Intial Draft           |
++-----------+------------------------+
+
+================================================================================
+Contributors
+================================================================================
+
+* Isaac Ault `isaac.ault@codeplay.com <isaac.ault@codeplay.com>`_
+* Duncan Brawley `duncan.brawley@codeplay.com <duncan.brawley@codeplay.com>`_
+* Przemek Malon `przemek.malon@codeplay.com <przemek.malon@codeplay.com>`_
+* Chedy Najjar `chedy.najjar@codeplay.com <chedy.najjar@codeplay.com>`_
+* Sean Stirling `sean.stirling@codeplay.com <sean.stirling@codeplay.com>`_
+* Peter Zuzek `peter@codeplay.com peter@codeplay.com <peter@codeplay.com>`_

scripts/core/common.yml

@@ -329,6 +329,8 @@ etors:
       desc: $x_device_partition_properties_t
     - name: EXP_COMMAND_BUFFER_DESC
       desc: $x_exp_command_buffer_desc_t
+    - name: EXP_SAMPLER_MIP_PROPERTIES
+      desc: $x_exp_sampler_mip_properties_t
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Base for all properties types"

scripts/core/device.yml

@@ -385,6 +385,54 @@ etors:
       desc: "[uint32_t] The maximum number of registers available per block."
     - name: IP_VERSION
       desc: "[uint32_t] The device IP version. The meaning of the device IP version is implementation-defined, but newer devices should have a higher version than older devices."
+    - name: BINDLESS_IMAGES_SUPPORT_EXP
+      value: "0x2000"
+      desc: "[$x_bool_t] returns true if the device supports the creation of bindless images"
+    - name: BINDLESS_IMAGES_1D_USM_SUPPORT_EXP
+      value: "0x2001"
+      desc: "[$x_bool_t] returns true if the device supports the creation of 1D bindless images backed by USM"
+    - name: BINDLESS_IMAGES_2D_USM_SUPPORT_EXP
+      value: "0x2002"
+      desc: "[$x_bool_t] returns true if the device supports the creation of 2D bindless images backed by USM"
+    - name: BINDLESS_IMAGES_3D_USM_SUPPORT_EXP
+      value: "0x2003"
+      desc: "[$x_bool_t] returns true if the device supports the creation of 3D bindless images backed by USM"
+    - name: IMAGE_PITCH_ALIGN_EXP
+      value: "0x2004"
+      desc: "[uint32_t] returns the required alignment of the pitch between two rows of an image in bytes"
+    - name: MAX_IMAGE_LINEAR_WIDTH_EXP
+      value: "0x2005"
+      desc: "[size_t] returns the maximum linear width allowed for images allocated using USM"
+    - name: MAX_IMAGE_LINEAR_HEIGHT_EXP
+      value: "0x2006"
+      desc: "[size_t] returns the maximum linear height allowed for images allocated using USM"
+    - name: MAX_IMAGE_LINEAR_PITCH_EXP
+      value: "0x2007"
+      desc: "[size_t] returns the maximum linear pitch allowed for images allocated using USM"
+    - name: MIPMAP_SUPPORT_EXP
+      value: "0x2008"
+      desc: "[$x_bool_t] returns true if the device supports allocating mipmap resources"
+    - name: MIPMAP_ANISOTROPY_SUPPORT_EXP
+      value: "0x2009"
+      desc: "[$x_bool_t] returns true if the device supports sampling mipmap images with anisotropic filtering"
+    - name: MIPMAP_MAX_ANISOTROPY_EXP
+      value: "0x200A"
+      desc: "[uint32_t] returns the maximum anisotropic ratio supported by the device"
+    - name: MIPMAP_LEVEL_REFERENCE_SUPPORT_EXP
+      value: "0x200B"
+      desc: "[$x_bool_t] returns true if the device supports using images created from individual mipmap levels"
+    - name: INTEROP_MEMORY_IMPORT_SUPPORT_EXP
+      value: "0x200C"
+      desc: "[$x_bool_t] returns true if the device supports importing external memory resources"
+    - name: INTEROP_MEMORY_EXPORT_SUPPORT_EXP
+      value: "0x200D"
+      desc: "[$x_bool_t] returns true if the device supports exporting internal memory resources"
+    - name: INTEROP_SEMAPHORE_IMPORT_SUPPORT_EXP
+      value: "0x200E"
+      desc: "[$x_bool_t] returns true if the device supports importing external semaphore resources"
+    - name: INTEROP_SEMAPHORE_EXPORT_SUPPORT_EXP
+      value: "0x200F"
+      desc: "[$x_bool_t] returns true if the device supports exporting internal event resources"
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieves various information about device"

scripts/core/event.yml

@@ -75,6 +75,12 @@ etors:
       desc: Event created by $xEnqueueWriteHostPipe
     - name: COMMAND_BUFFER_ENQUEUE_EXP
       desc: Event created by $xCommandBufferEnqueueExp
+    - name: INTEROP_SEMAPHORE_WAIT_EXP
+      value: "0x2000"
+      desc: Event created by $xBindlessImagesWaitExternalSemaphoreExp
+    - name: INTEROP_SEMAPHORE_SIGNAL_EXP
+      value: "0x2001"
+      desc: Event created by $xBindlessImagesSignalExternalSemaphoreExp
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Event Status"