Add specification for cl_ext_image_from_buffer (#752)

Change-Id: Ieca35aedd775379310417b94387ea0776c4a0d55
Signed-off-by: Kevin Petit <kevin.petit@arm.com>

Signed-off-by: Kevin Petit <kevin.petit@arm.com>

Author: kpet

extensions/cl_ext_image_from_buffer.asciidoc

@@ -0,0 +1,304 @@
+// Copyright 2018-2022 The Khronos Group. This work is licensed under a
+// Creative Commons Attribution 4.0 International License; see
+// http://creativecommons.org/licenses/by/4.0/
+
+:data-uri:
+:icons: font
+include::../config/attribs.txt[]
+include::{generated}/api/api-dictionary-no-links.asciidoc[]
+:source-highlighter: coderay
+
+= cl_ext_image_from_buffer
+:R: pass:q,r[^(R)^]
+Khronos{R} OpenCL Working Group
+
+<<<<
+
+== Name Strings
+
+`cl_ext_image_from_buffer`
+
+== Contact
+
+Please see the *Issues* list in the Khronos *OpenCL-Docs* repository: +
+https://github.com/KhronosGroup/OpenCL-Docs
+
+== Contributors
+
+Kevin Petit, Arm Ltd. +
+Jeremy Kemp, Imagination Technologies +
+Alastair Murray, Codeplay Software Ltd. +
+Balaji Calidas, Qualcomm +
+
+== Notice
+
+include::../copyrights.txt[]
+
+== Status
+
+Shipping.
+
+== Version
+
+Built On: {docdate} +
+Version: 1.0.0
+
+== Dependencies
+
+This extension is written against the OpenCL Specification version 3.0.9.
+
+This extension requires OpenCL 3.0.
+
+This extension requires `cl_ext_image_requirements_info`.
+
+== Overview
+
+This extension enables all types of images to be created from an existing buffer
+object.
+
+== New API Enums
+
+Accepted value for the _param_name_ parameter to *clGetRequirementsInfoEXT*:
+
+[source,c]
+----
+CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT   0x1291
+----
+
+== Modifications to the OpenCL API Specification
+
+(Modify Section 5.3.1, *Creating Image Objects*) ::
++
+--
+The following text:
+
+--
+_image_format_ is a pointer to a structure that describes format properties of the image to be
+allocated. A 1D image buffer or 2D image can be created from a buffer by specifying a buffer
+object in the image_desc→mem_object. A 2D image can be created from another 2D image object
+by specifying an image object in the image_desc→mem_object. Refer to the Image Format
+Descriptor section for a detailed description of the image format descriptor.
+--
+
+is replaced with:
+
+--
+_image_format_ is a pointer to a structure that describes format properties of
+the image to be allocated. An image can be created from a buffer by specifying
+a buffer object in the _image_desc_->_mem_object_. A 2D image can be created from
+another 2D image object by specifying an image object in the
+_image_desc_->_mem_object_. Refer to the Image Format Descriptor section for a
+detailed description of the image format descriptor.
+--
+
+The following text:
+
+--
+{CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if a 2D image is created from a buffer and
+the row pitch and base address alignment does not follow the rules described
+for creating a 2D image from a buffer.
+--
+
+is replaced with:
+
+--
+{CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if an image is created from a buffer and
+the row or slice pitch and base address alignment do not follow the rules
+described for creating an image from a buffer.
+--
+
+The following text is added to the list of error conditions for {clCreateImageWithProperties}:
+
+--
+{CL_INVALID_IMAGE_SIZE} if an image is created from a buffer and the buffer
+passed in _image_desc->_mem_object_ is too small to be used as a data store
+for the image, e.g. if its size is smaller than the value returned for
+{CL_IMAGE_REQUIREMENTS_SIZE_EXT} for the parameters used to create the image.
+--
+
+
+The following text:
+
+--
+For a 2D image created from a buffer, the pitch specified (or computed if
+pitch specified is 0) must be a multiple of the maximum of the
+{CL_DEVICE_IMAGE_PITCH_ALIGNMENT} value for all devices in the context associated
+with the buffer specified by mem_object that support images.
+--
+
+is replaced with:
+
+--
+For an image created from a buffer, the pitch specified (or computed if
+pitch specified is 0) must be a multiple of the
+{CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} value for the _image_format_,
+_image_type_ and _flags_ used to create the image.
+--
+
+
+The following text is added to the description for `image_slice_pitch`:
+
+--
+For an image created from a buffer, the pitch specified (or computed if
+pitch specified is 0) must be a multiple of the
+{CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT} value for the _image_format_,
+_image_type_ and _flags_ used to create the image.
+--
+
+The following text:
+
+--
+`mem_object` may refer to a valid buffer or image memory object. `mem_object`
+can be a buffer memory object if image_type is {CL_MEM_OBJECT_IMAGE1D_BUFFER}
+or {CL_MEM_OBJECT_IMAGE2D}. `mem_object` can be an image object if _image_type_
+is {CL_MEM_OBJECT_IMAGE2D}. Otherwise it must be `NULL`. The image pixels are
+taken from the memory objects data store. When the contents of the specified
+memory objects data store are modified, those changes are reflected in the
+contents of the image object and vice-versa at corresponding synchronization
+points.
+--
+
+is replaced with:
+
+--
+`mem_object` may refer to a valid buffer or image memory object. `mem_object`
+can be an image object if _image_type_ is {CL_MEM_OBJECT_IMAGE2D}.
+Otherwise it must be `NULL`. The image pixels are taken from the memory objects
+data store. When the contents of the specified memory objects data store are
+modified, those changes are reflected in the contents of the image object and
+vice-versa at corresponding synchronization points.
+--
+
+The following text is added:
+
+--
+For a 1D image created from a buffer object, the `image_width` {times} size of
+element in bytes must be {leq} size of the buffer object. The image data in the
+buffer object is stored as a single scanline which is a linear sequence of
+adjacent elements.
+
+For a 1D image array created from a buffer object, the `image_slice_pitch` {times}
+`image_array_size` must be {leq} size of the buffer object specified by `mem_object`.
+The image data in the buffer object is stored as a linear sequence of adjacent 1D
+slices. Each slice is a single scanline padded to `image_slice_pitch` bytes.
+Each scanline is a linear sequence of image elements.
+
+For a 2D image array created from a buffer object, the `image_slice_pitch` {times}
+`image_array_size` must be {leq} size of the buffer object specified by `mem_object`.
+The image data in the buffer object is stored as a linear sequence of adjacent 2D
+slices. Each slice is a linear sequence of adjacent scanlines padded to
+`image_slice_pitch` bytes. Each scanline is a linear sequence of image elements padded
+to `image_row_pitch` bytes.
+
+For a 3D image created from a buffer object, the `image_slice_pitch` {times}
+`image_depth` must be {leq} size of the buffer object specified by `mem_object`.
+The image data in the buffer object is stored as a linear sequence of adjacent 2D
+slices padded to `image_slice_pitch` bytes. Each slice is a linear sequence of adjacent
+scanlines. Each scanline is a linear sequence of image elements padded to
+`image_row_pitch` bytes.
+--
+
+The following text:
+
+--
+Concurrent reading from, writing to and copying between both a buffer object and
+1D image buffer or 2D image object associated with the buffer object is undefined.
+Only reading from both a buffer object and 1D image buffer or 2D image object
+associated with the buffer object is defined.
+--
+
+is replaced with:
+
+--
+Concurrent reading from, writing to and copying between both a buffer object and
+an image object associated with the buffer object is undefined. Only reading from
+both a buffer object and image object associated with the buffer object is defined.
+--
+
+(Modify section 5.3.X, *Querying image requirements*) ::
++
+--
+The following is added to the _List of supported param_names by
+*clGetImageRequirementsInfoEXT*:
+
+[width="100%",cols="<34%,<33%,<33%",options="header"]
+|====
+| Image Requirement Info | Return type | Info. returned in _param_value_
+
+| {CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT}
+| `size_t`
+| Returns the slice pitch alignment required in bytes for images created from
+  a buffer with the parameters passed to {clGetImageRequirementsInfoEXT}.
+  The value returned is a power of two. _image_format_ and _image_desc_ are
+  allowed to be `NULL`. When either or both is `NULL` the value returned is
+  the minimum slice pitch alignment that is supported for all possible values
+  of the missing argument(s).
+
+|====
+--
+--
+
+== Interactions with Other Extensions
+
+None.
+
+== Conformance tests
+
+
+. Test access from kernel
+  - For all image types
+  - For a few/all image formats
+  - For several values of row/slice pitch
+  - With or without a host_ptr
+    - Create buffer and fill with data
+    - Optionally create a sub-buffer with a randomly selected offset?
+    - Create an image from the buffer
+    - Read the image from a kernel and compare with values read using the buffer and direct addressing. They must match.
+
+. TODO Test access via read/write/map commands?
+
+. TODO Test copy to/from buffer?
+
+. TODO Test fill?
+
+. TODO Test copy to/from another image?
+
+. Test clGetImageInfo
+  - For all image types (one format per element size)
+  - For a few different row/pitch sizes (image dimensions being equal or not)
+    - Create an image from a buffer
+    - Check that the returned values for {CL_IMAGE_ROW_PITCH} and {CL_IMAGE_SLICE_PICTH} are correct.
+
+. Test clGetMemObjectInfo
+  - For all image types (1 format only)
+    - Create an image from a buffer
+    - Check that {CL_MEM_ASSOCIATED_MEMOBJECT} correctly returns the buffer that was used.
+
+. Negative testing for {clCreateImage} (alignment)
+  - For a few/all image formats
+        - For all image types
+            - Query row pitch, slice pitch and base image address alignment for the format
+            - Create an image from a buffer with invalid row pitch (not a multiple of required alignment) and check that {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} is returned.
+            - Create an image from a buffer with invalid slice pitch (not a multiple of required alignment) and check that {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} is returned.
+            - Create an image from a buffer with invalid base address alignment (not a multiple of required alignment) and check that {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} is returned.
+
+. Negative testing for {clCreateImage} (buffer size)
+  - For a few image formats (at least smallest and biggest element types)
+    - For all image types
+      - Create a buffer too small
+      - Check that image creation from that buffer is rejected with {CL_INVALID_IMAGE_SIZE}
+
+== Issues
+
+None.
+
+== Version History
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|====
+| Version | Date       | Author       | Changes
+| 1.0.0   | 2022-01-25 | Kevin Petit  | *Initial EXT revision*
+|====
+

xml/cl.xml

@@ -1718,7 +1718,7 @@ server's OpenCL/api-docs repository.
         <enum value="0x1284"        name="CL_PROFILING_COMMAND_COMPLETE"/>
             <unused start="0x1285" end="0x128F" comment="Reserved for cl_profiling_info"/>
         <enum value="0x1290"        name="CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT"/>
-            <unused start="0x1291" end="0x1291" comment="Reserved for MR179"/>
+        <enum value="0x1291"        name="CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT"/>
         <enum value="0x1292"        name="CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT"/>
         <enum value="0x1293"             name="CL_COMMAND_BUFFER_FLAGS_KHR"/>
         <enum value="0x1294"             name="CL_COMMAND_BUFFER_QUEUES_KHR"/>
@@ -7200,5 +7200,10 @@ server's OpenCL/api-docs repository.
                 <command name="clGetMutableCommandInfoKHR"/>
             </require>
         </extension>
+        <extension name="cl_ext_image_from_buffer" supported="opencl">
+            <require comment="cl_image_requirements_info_ext">
+                <enum name="CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT"/>
+            </require>
+        </extension>
     </extensions>
 </registry>