From 20b89ef7b76ba95a3f7c397e226c8bc05caf1242 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Thu, 9 Jan 2025 19:41:59 +0000 Subject: [PATCH] Integrate cl_ext_image_requirements_info into unified specification (#1295) * Integrate cl_ext_image_requirements_info into unified specification Signed-off-by: Kevin Petit Change-Id: Ia249f78aa521a8d202dfafbb736c9887574e56f9 * Update api/opencl_runtime_layer.asciidoc Co-authored-by: Ben Ashbaugh * Update api/opencl_runtime_layer.asciidoc Co-authored-by: Ben Ashbaugh --------- Signed-off-by: Kevin Petit Co-authored-by: Ben Ashbaugh --- api/cl_ext_image_requirements_info.asciidoc | 93 ++++- api/opencl_platform_layer.asciidoc | 21 + api/opencl_runtime_layer.asciidoc | 189 +++++++++ .../cl_ext_image_requirements_info.asciidoc | 388 ------------------ extensions/extensions.txt | 2 - 5 files changed, 299 insertions(+), 394 deletions(-) delete mode 100644 extensions/cl_ext_image_requirements_info.asciidoc diff --git a/api/cl_ext_image_requirements_info.asciidoc b/api/cl_ext_image_requirements_info.asciidoc index 6de780853..01577f1e0 100644 --- a/api/cl_ext_image_requirements_info.asciidoc +++ b/api/cl_ext_image_requirements_info.asciidoc @@ -1,4 +1,4 @@ -// Copyright 2018-2024 The Khronos Group Inc. +// Copyright 2018-2025 The Khronos Group Inc. // SPDX-License-Identifier: CC-BY-4.0 include::{generated}/meta/{refprefix}cl_ext_image_requirements_info.txt[] @@ -6,14 +6,99 @@ include::{generated}/meta/{refprefix}cl_ext_image_requirements_info.txt[] === Other Extension Metadata *Last Modified Date*:: - 2022-01-18 + 2025-01-06 *IP Status*:: No known IP claims. +*Interactions and External Dependencies*:: + - This extension interacts with {cl_khr_image2d_from_buffer_EXT} +*Contributors*:: + - Kevin Petit, Arm Ltd. + - Jeremy Kemp, Imagination Technologies + - Alastair Murray, Codeplay Software Ltd. + - Balaji Calidas, Qualcomm === Description -The latest published specification for this extension is available on -the https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_image_requirements_info.html[OpenCL registry]. +This extension enables applications to query requirements for an image without +having to create the image. + +=== New Commands + + * {clGetImageRequirementsInfoEXT} + +=== New Types + + * {cl_image_requirements_info_ext_TYPE} + +=== New Enums + + * {cl_image_requirements_info_ext_TYPE} + ** {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} + ** {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} + ** {CL_IMAGE_REQUIREMENTS_SIZE_EXT} + ** {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT} + ** {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} + ** {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} + ** {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} + +=== Conformance tests + +. Basic checks for {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} and {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} +* For all image formats and types +** Check that the {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} and {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} queries can be performed successfully and that the values returned are a power of two. + +. Check consistency with `cl_khr_image2d_from_buffer` +* When `cl_khr_image2d_from_buffer` is supported, check that the value returned by {CL_DEVICE_IMAGE_PITCH_ALIGNMENT} after converting in bytes for the supported format with the biggest element size (channel data type size * number of channels) is greater than or equal to the value returned by {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} for all supported formats. +* When `cl_khr_image2d_from_buffer` is supported, check that the value returned by {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT} after converting in bytes for the supported format with the biggest element size (channel data type size * number of channels) is greater than or equal to the value returned by {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} for all supported formats. + +. Negative tests for {CL_IMAGE_REQUIREMENTS_SIZE_EXT} +* Check that attempting to perform the {CL_IMAGE_REQUIREMENTS_SIZE_EXT} query without specifying the _image_format_ results in {CL_INVALID_VALUE} being returned. +* Check that attempting to perform the {CL_IMAGE_REQUIREMENTS_SIZE_EXT} query without specifying the _image_desc_ results in {CL_INVALID_VALUE} being returned. + +. Consistency checks for {CL_IMAGE_REQUIREMENTS_SIZE_EXT} +* When creating 2D images from a buffer is supported, for all formats and a selection of image dimensions +** Check that the {CL_IMAGE_REQUIREMENTS_SIZE_EXT} query can be performed successfully. +** Create a buffer with the size returned and check that an image can successfully be created from the buffer. +** Check that the value returned for {CL_MEM_SIZE} for the image is the same as the value returned for {CL_IMAGE_REQUIREMENTS_SIZE_EXT}. + +. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT} +* For all image formats, image types and a selection of values for other members in _image_desc_ (that MUST include `0`) +** Check that the {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT} query can be performed successfully +** Check that the value is smaller than or equal to the value returned for {CL_DEVICE_IMAGE_MAX_BUFFER_SIZE} for images of {CL_MEM_OBJECT_IMAGE1D_BUFFER} type or smaller than or equal to the value returned for {CL_DEVICE_IMAGE3D_MAX_WIDTH} for images of {CL_MEM_OBJECT_IMAGE3D} type or smaller than or equal to the value returned for {CL_DEVICE_IMAGE2D_MAX_WIDTH} for all other image types. + +. Negative tests for {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} +* Attempt to perform the {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} query on all image types for which it is not valid +* Check that {CL_INVALID_IMAGE_DESCRIPTOR} is returned in all cases. + +. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} +* For all image formats, valid image types and a selection of values for other members in _image_desc_ (that MUST include `0`) +** Check that the {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} query can be performed successfully +** Check that the value is smaller than or equal to the value returned for {CL_DEVICE_IMAGE2D_MAX_HEIGHT} for 2D or 2D array images or {CL_DEVICE_IMAGE3D_MAX_HEIGHT} for 3D images. + +. Negative testing for {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} +* Attempt to perform the {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} query on all image types for which it is not valid +* Check that {CL_INVALID_IMAGE_DESCRIPTOR} is returned in all cases. + +. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} +* For all image formats, valid image types and a selection of values for other members in _image_desc_ (that MUST include `0`) +** Check that the {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} query can be performed successfully +** Check that the value is smaller than or equal to the value returned for {CL_DEVICE_IMAGE3D_MAX_DEPTH}. + +. Negative testing for {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} +* Attempt to perform the {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} query on all image types for which it is not valid +* Check that {CL_INVALID_IMAGE_DESCRIPTOR} is returned in all cases. + +. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} +* For all image formats, valid image types and a selection of values for other members in _image_desc_ (that MUST include `0`) +** Check that the {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} query can be performed successfully +** Check that the value is smaller than or equal to the value returned for {CL_DEVICE_IMAGE_MAX_ARRAY_SIZE}. + +. General negative testing for {clGetImageRequirementsInfoEXT} +** Write tests for all possible testable generic error codes. + +=== Issues + +None. === Version History diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 584c4ce4c..bf6c329ae 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -784,6 +784,16 @@ endif::cl_khr_image2d_from_buffer[] or 2.2 device if {CL_DEVICE_IMAGE_SUPPORT} is {CL_TRUE}. This value must be 0 for devices that do not support 2D images created from a buffer. + +ifdef::cl_ext_image_requirements_info+cl_khr_image2d_from_buffer[] + If the {cl_khr_image2d_from_buffer_EXT} and {cl_ext_image_requirements_info_EXT} + extensions are supported, the value returned by {CL_DEVICE_IMAGE_PITCH_ALIGNMENT} + after converting in bytes for the supported format with the biggest element size + (channel data type size {times} number of channels) must be greater than or equal to + the value returned by {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} for any + supported format. +endif::cl_ext_image_requirements_info+cl_khr_image2d_from_buffer[] + | {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT_anchor} include::{generated}/api/version-notes/CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT.asciidoc[] @@ -802,6 +812,17 @@ endif::cl_khr_image2d_from_buffer[] or 2.2 device if {CL_DEVICE_IMAGE_SUPPORT} is {CL_TRUE}. This value must be 0 for devices that do not support 2D images created from a buffer. + +ifdef::cl_ext_image_requirements_info+cl_khr_image2d_from_buffer[] + If the {cl_khr_image2d_from_buffer_EXT} and {cl_ext_image_requirements_info_EXT} + extensions are supported, the value returned by + {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT} after converting in bytes for the + supported format with the biggest element size + (channel data type size {times} number of channels) must be greater than or equal to + the value returned by {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} for any + supported format. +endif::cl_ext_image_requirements_info+cl_khr_image2d_from_buffer[] + | {CL_DEVICE_MAX_PIPE_ARGS_anchor} include::{generated}/api/version-notes/CL_DEVICE_MAX_PIPE_ARGS.asciidoc[] diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 019288efc..e10bdcd32 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -2654,9 +2654,19 @@ endif::cl_khr_external_memory[] The image row pitch must be {geq} _image_width_ {times} the size of an image element in bytes, and must be a multiple of the size of an image element in bytes. +ifndef::cl_ext_image_requirements_info[] For a 2D image created from a buffer the image row pitch must also be a multiple of the maximum of the {CL_DEVICE_IMAGE_PITCH_ALIGNMENT} value for all devices in the context that support images. +endif::cl_ext_image_requirements_info[] +ifdef::cl_ext_image_requirements_info[] + For a 2D image created from a buffer, the image row pitch must also + - Be a multiple of the {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} value + returned for parameters compatible with those used to create the image, if + the {cl_ext_image_requirements_info_EXT} extension is supported, or + - Be a multiple of the maximum of the {CL_DEVICE_IMAGE_PITCH_ALIGNMENT} value + for all devices in the context that support images, otherwise. +endif::cl_ext_image_requirements_info[] * _image_slice_pitch_ is the size in bytes of each 2D slice in a 3D image, or the size in bytes of each image in a 1D or 2D image array. The _image_slice_pitch_ must be zero if _host_ptr_ is `NULL` @@ -2718,12 +2728,26 @@ descriptor information associated with `mem_object`. Image elements are stored according to their image format as described in <>. +ifndef::cl_ext_image_requirements_info[] If the buffer object specified by `mem_object` was created with {CL_MEM_USE_HOST_PTR}, the _host_ptr_ specified to {clCreateBuffer} or {clCreateBufferWithProperties} must be aligned to the maximum of the {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT} value for all devices in the context associated with the buffer specified by `mem_object` that support images. +endif::cl_ext_image_requirements_info[] +ifdef::cl_ext_image_requirements_info[] +If the buffer object specified by `mem_object` was created with +{CL_MEM_USE_HOST_PTR}, the _host_ptr_ specified to {clCreateBuffer} or +{clCreateBufferWithProperties} must + + * Be aligned to the {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} value + for the returned for parameters compatible with those used to create the + image, if the {cl_ext_image_requirements_info_EXT} extension is supported, or + * Be aligned to the maximum of the {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT} + value for all devices in the context associated with the buffer specified by + `mem_object` that support images, otherwise. +endif::cl_ext_image_requirements_info[] Creating a 2D image object from another 2D image object creates a new 2D image object that shares the image data store with `mem_object` but views @@ -5112,6 +5136,171 @@ returned in _errcode_ret_: -- endif::cl_khr_gl_sharing[] +ifdef::cl_ext_image_requirements_info[] +=== Querying Image Requirements + +[open,refpage='clGetImageRequirementsInfoEXT',desc='Get information on image requirements.',type='protos'] +-- +To get information specific to the requirements of an image before creating it call the function + +include::{generated}/api/protos/clGetImageRequirementsInfoEXT.txt[] +include::{generated}/api/version-notes/clGetImageRequirementsInfoEXT.asciidoc[] + + * _context_ is the OpenCL context in which the query will be performed. + * _properties_ is an optional list of properties for the image object and their + corresponding values. The list is terminated with the special property 0. If + no properties are required, properties may be `NULL`. + * _flags_ is a bit-field that is used to specify allocation and usage information + about the image format being queried and is described in the + <> table. _flags_ may be {CL_MEM_READ_WRITE} to + specialize the query for images that may be read from and written to by different + kernel instances when correctly ordered by event dependencies, or {CL_MEM_READ_ONLY} + to specialize the query for images that may be read from by a kernel, or + {CL_MEM_WRITE_ONLY} to specialiaze the query for images that may be written to by + a kernel, or {CL_MEM_KERNEL_READ_AND_WRITE} to specialize the query for images that + may be both read from and written to by the same kernel instance. When _flags_ is + `0` the value returned for the query must be correct for all possible values of _flags_. + * _image_format_ is a pointer to a structure describing the format of the image + for which requirements are being queried. Refer to the + <> section for a detailed + description. + * _image_desc_ is a pointer to a structure that describes type and dimensions of + the image for which requirements are being queried. Refer to the + <> section for a detailed description of + the image descriptor. + * _param_name_ specifies the information to query. + The list of supported _param_name_ types and the information returned in + _param_value_ by {clGetImageRequirementsInfoEXT} is described in the + <> table. + * _param_value_ is a pointer to memory where the appropriate result being + queried is returned. + If _param_value_ is `NULL`, it is ignored. + * _param_value_size_ is used to specify the size in bytes of memory pointed to + by _param_value_. + This size must be {geq} size of return type as described in the + <> table. + * _param_value_size_ret_ returns the actual size in bytes of data being + queried by _param_name_. + If _param_value_size_ret_ is `NULL`, it is ignored. + +[[image-requirements-info-table]] +.List of supported param_names by {clGetImageRequirementsInfoEXT} +[cols="4,1,4",options="header"] +|==== +| Image Format Info | Return type | Info. returned in _param_value_ + +| {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT_anchor} +| `size_t` +| Returns the minimum alignment in bytes required for the data store backing + an image created using the parameters passed to {clGetImageRequirementsInfoEXT}. + _image_format_ or _image_desc_ are allowed to be `NULL`. When either or both is + `NULL` the implementation will return an alignment that would be sufficient for + all possible values of the missing argument. + + The value returned is a power of two. + +|{CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT_anchor} +| `size_t` +| Returns the row 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_ or _image_desc_ + are allowed to be `NULL`. When either or both is `NULL` the value returned is + the minimum row pitch alignment that works for all possible values of the missing + argument(s). + +| {CL_IMAGE_REQUIREMENTS_SIZE_EXT_anchor} +| `size_t` +| Returns the minimal size in bytes that a buffer would need to be to back an + image created using the parameters passed to {clGetImageRequirementsInfoEXT}. + + + Both _image_format_ and _image_desc_ must be non-`NULL`, otherwise + {CL_INVALID_VALUE} is returned. + +| {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT_anchor} +| `cl_uint` +| Returns the max width supported for creating images with the parameters passed + to {clGetImageRequirementsInfoEXT}. + _image_format_ or _image_desc_ are allowed to be `NULL`. When either or both is + `NULL` the implementation will return a max width that would be supported for + all possible values of the missing argument(s). + + When _image_desc_ is not `NULL`, the value of its _image_width_ member is + ignored and has no effect on the value returned. The value of all other members, + except `mem_object` may be `0` to require that the value returned be supported + for all possible values of the members that are set to `0`. + +// TODO: should we require _image_width_ to be `0`? + +| {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT_anchor} +| `cl_uint` +| Returns the max height supported for creating images with the parameters passed + to {clGetImageRequirementsInfoEXT}. + _image_format_ or _image_desc_ are allowed to be `NULL`. When either or both is + `NULL` the implementation will return a max height that would be supported for + all possible values of the missing argument(s). + + When _image_desc_ is not `NULL`, the value of its _image_height_ member is + ignored and has no effect on the value returned. The value of all other members, + except `mem_object` may be `0` to require that the value returned be supported + for all possible values of the members that are set to `0`. + + If _image_desc_ is not `NULL`, then _image_type_ must be either `0`, + {CL_MEM_OBJECT_IMAGE2D}, {CL_MEM_OBJECT_IMAGE2D_ARRAY}, or {CL_MEM_OBJECT_IMAGE3D}, + otherwise {CL_INVALID_IMAGE_DESCRIPTOR} is returned. + +// TODO: should we require _image_height_ to be `0`? + +| {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT_anchor} +| `cl_uint` +| Returns the max depth supported for creating images with the parameters passed + to {clGetImageRequirementsInfoEXT}. + _image_format_ or _image_desc_ are allowed to be `NULL`. When either or both is + `NULL` the implementation will return a max depth that would be supported for + all possible values of the missing argument(s). + + When _image_desc_ is not `NULL`, the value of its _image_depth_ member is + ignored and has no effect on the value returned. The value of all other members, + except `mem_object` may be `0` to require that the value returned be supported + for all possible values of the members that are set to `0`. + + If _image_desc_ is not `NULL`, then _image_type_ must be either `0` or + {CL_MEM_OBJECT_IMAGE3D}, otherwise {CL_INVALID_IMAGE_DESCRIPTOR} is returned. + +// TODO: should we require _image_depth_ to be `0`? + +| {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT_anchor} +| `cl_uint` +| Returns the max array size supported for creating images with the parameters passed + to {clGetImageRequirementsInfoEXT}. + _image_format_ or _image_desc_ are allowed to be `NULL`. When either or both is + `NULL` the implementation will return a max array size that would be supported for + all possible values of the missing argument(s). + + When _image_desc_ is not `NULL`, the value of its _image_array_size_ member is + ignored and has no effect on the value returned. The value of all other members, + except `mem_object` may be `0` to require that the value returned be supported + for all possible values of the members that are set to `0`. + + If _image_desc_ is not `NULL`, then _image_type_ must be either `0`, + {CL_MEM_OBJECT_IMAGE1D_ARRAY} or {CL_MEM_OBJECT_IMAGE2D_ARRAY}, otherwise + {CL_INVALID_IMAGE_DESCRIPTOR} is returned. + +// TODO: should we require _image_array_size_ to be `0`? +|==== + +// refError + +{clGetImageRequirementsInfoEXT} returns {CL_SUCCESS} if the function is executed +successfully. +Otherwise, it returns one of the following errors: + + * {CL_INVALID_CONTEXT} if _context_ if not a valid context. + * {CL_INVALID_PROPERTY} if a property name in properties is not a supported + property name, if the value specified for a supported property name is not + valid, or if the same property name is specified more than once. + * {CL_INVALID_VALUE} if values specified in _flags_ are not valid. + * {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if values specified in _image_format_ + are not valid. + * {CL_INVALID_IMAGE_DESCRIPTOR} if values specified in _image_desc_ + are not valid. + * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes + specified by _param_value_size_ is < size of return type as described in + the <> table and + _param_value_ is not `NULL`. + * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required + by the OpenCL implementation on the device. + * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources + required by the OpenCL implementation on the host. +-- +endif::cl_ext_image_requirements_info[] == Pipes diff --git a/extensions/cl_ext_image_requirements_info.asciidoc b/extensions/cl_ext_image_requirements_info.asciidoc deleted file mode 100644 index aedc71bc5..000000000 --- a/extensions/cl_ext_image_requirements_info.asciidoc +++ /dev/null @@ -1,388 +0,0 @@ -// Copyright 2018-2024 The Khronos Group Inc. -// SPDX-License-Identifier: CC-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_requirements_info -:R: pass:q,r[^(R)^] -Khronos{R} OpenCL Working Group - -== Name Strings - -`cl_ext_image_requirements_info` - -== 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: 0.5.0 - -== Dependencies - -This extension is written against the OpenCL Specification Version 3.0.9. - -This extension requires OpenCL 3.0. - -== Overview - -This extension enables applications to query requirements for an image without -having to create the image. - -== New API Functions - -[source,c] ----- -cl_int clGetImageRequirementsInfoEXT( - cl_context context, - const cl_mem_properties* properties, - cl_mem_flags flags, - const cl_image_format* image_format, - const cl_image_desc* image_desc, - cl_image_requirements_info_ext param_name, - size_t param_value_size, - void* param_value, - size_t* param_value_size_ret); ----- - -== New API Types - -[source,c] ----- -typedef cl_uint cl_image_requirements_info_ext; ----- - -== New API Enums - -Accepted value for the _param_name_ parameter to {clGetImageRequirementsInfoEXT}: - -[source,c] ----- -CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT 0x1290 -CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT 0x1292 -CL_IMAGE_REQUIREMENTS_SIZE_EXT 0x12B2 -CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT 0x12B3 -CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT 0x12B4 -CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT 0x12B5 -CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT 0x12B6 ----- - -== Modifications to the OpenCL API Specification - -(Modify Section 5.3.1, *Creating Image Objects*) :: -+ --- -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 a 2D 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 returned for parameters -compatible with those used to create the image. --- - -The following text: --- -If the buffer object specified by mem_object was created with {CL_MEM_USE_HOST_PTR}, -the _host_ptr_ specified to {clCreateBuffer} or {clCreateBufferWithProperties} must -be aligned to the maximum of the {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT} value for -all devices in the context associated with the buffer specified by mem_object that -support images. --- - -is replaced with: - --- -If the buffer object specified by mem_object was created with {CL_MEM_USE_HOST_PTR}, -the _host_ptr_ specified to {clCreateBuffer} or {clCreateBufferWithProperties} must -be aligned to the {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} value for the -returned for parameters compatible with those used to create the image. --- - --- - -(Modify Section 5.3, *Image Objects*) :: -+ --- - -(Add a new subsection 5.3.X, *Querying image requirements*) :: -+ --- -[open,refpage='clGetImageRequirementsInfoEXT',desc='Get information on image requirements.',type='protos'] - -To get information specific to the requirements of an image before creating it call the function - -include::{generated}/api/protos/clGetImageRequirementsInfoEXT.txt[] - - * _context_ is the OpenCL context in which the query will be performed. - * _properties_ is an optional list of properties for the image object and their - corresponding values. The list is terminated with the special property 0. If - no properties are required, properties may be `NULL`. - * _flags_ is a bit-field that is used to specify allocation and usage information - about the image format being queried and is described in the - <> table. _flags_ may be {CL_MEM_READ_WRITE} to - specialize the query for images that may be read from and written to by different - kernel instances when correctly ordered by event dependencies, or {CL_MEM_READ_ONLY} - to specialize the query for images that may be read from by a kernel, or - {CL_MEM_WRITE_ONLY} to specialiaze the query for images that may be written to by - a kernel, or {CL_MEM_KERNEL_READ_AND_WRITE} to specialize the query for images that - may be both read from and written to by the same kernel instance. When _flags_ is - `0` the value returned for the query must be correct for all possible values of _flags_. - * _image_format_ is a pointer to a structure describing the format of the image - for which requirements are being queried. Refer to the - <> section for a detailed - description. - * _image_desc_ is a pointer to a structure that describes type and dimensions of - the image for which requirements are being queried. Refer to the - <> section for a detailed description of - the image descriptor. - * _param_name_ specifies the information to query. - The list of supported _param_name_ types and the information returned in - _param_value_ by {clGetImageRequirementsInfoEXT} is described in the - <> table. - * _param_value_ is a pointer to memory where the appropriate result being - queried is returned. - If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. - * _param_value_size_ret_ returns the actual size in bytes of data being - queried by _param_name_. - If _param_value_size_ret_ is `NULL`, it is ignored. - -[[image-requirements-info-table]] -.List of supported param_names by <> -[cols="4,1,4",options="header"] -|==== -| Image Format Info | Return type | Info. returned in _param_value_ - -| {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} -| `size_t` -| Returns the minimum alignment in bytes required for the data store backing - an image created using the parameters passed to {clGetImageRequirementsInfoEXT}. - _image_format_ or _image_desc_ are allowed to be `NULL`. When either or both is - `NULL` the implementation will return an alignment that would be sufficient for - all possible values of the missing argument. + - The value returned is a power of two. - -|{CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} -| `size_t` -| Returns the row 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_ or _image_desc_ - are allowed to be `NULL`. When either or both is `NULL` the value returned is - the minimum row pitch alignment that works for all possible values of the missing - argument(s). - -| {CL_IMAGE_REQUIREMENTS_SIZE_EXT} -| `size_t` -| Returns the minimal size in bytes that a buffer would need to be to back an - image created using the parameters passed to {clGetImageRequirementsInfoEXT}. - + - Both _image_format_ and _image_desc_ must be non-`NULL`, otherwise - {CL_INVALID_VALUE} is returned. - -| {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT} -| `cl_uint` -| Returns the max width supported for creating images with the parameters passed - to {clGetImageRequirementsInfoEXT}. - _image_format_ or _image_desc_ are allowed to be `NULL`. When either or both is - `NULL` the implementation will return a max width that would be supported for - all possible values of the missing argument(s). + - When _image_desc_ is not `NULL`, the value of its _image_width_ member is - ignored and has no effect on the value returned. The value of all other members, - except `mem_object` may be `0` to require that the value returned be supported - for all possible values of the members that are set to `0`. + - TODO: should we require _image_width_ to be `0`? - -| {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} -| `cl_uint` -| Returns the max height supported for creating images with the parameters passed - to {clGetImageRequirementsInfoEXT}. - _image_format_ or _image_desc_ are allowed to be `NULL`. When either or both is - `NULL` the implementation will return a max height that would be supported for - all possible values of the missing argument(s). + - When _image_desc_ is not `NULL`, the value of its _image_height_ member is - ignored and has no effect on the value returned. The value of all other members, - except `mem_object` may be `0` to require that the value returned be supported - for all possible values of the members that are set to `0`. + - If _image_desc_ is not `NULL`, then _image_type_ must be either `0`, - {CL_MEM_OBJECT_IMAGE2D}, {CL_MEM_OBJECT_IMAGE2D_ARRAY}, or {CL_MEM_OBJECT_IMAGE3D}, - otherwise {CL_INVALID_IMAGE_DESCRIPTOR} is returned. + - TODO: should we require _image_height_ to be `0`? - -| {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} -| `cl_uint` -| Returns the max depth supported for creating images with the parameters passed - to {clGetImageRequirementsInfoEXT}. - _image_format_ or _image_desc_ are allowed to be `NULL`. When either or both is - `NULL` the implementation will return a max depth that would be supported for - all possible values of the missing argument(s). + - When _image_desc_ is not `NULL`, the value of its _image_depth_ member is - ignored and has no effect on the value returned. The value of all other members, - except `mem_object` may be `0` to require that the value returned be supported - for all possible values of the members that are set to `0`. + - If _image_desc_ is not `NULL`, then _image_type_ must be either `0` or - {CL_MEM_OBJECT_IMAGE3D}, otherwise {CL_INVALID_IMAGE_DESCRIPTOR} is returned. + - TODO: should we require _image_depth_ to be `0`? - -| {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} -| `cl_uint` -| Returns the max array size supported for creating images with the parameters passed - to {clGetImageRequirementsInfoEXT}. - _image_format_ or _image_desc_ are allowed to be `NULL`. When either or both is - `NULL` the implementation will return a max array size that would be supported for - all possible values of the missing argument(s). + - When _image_desc_ is not `NULL`, the value of its _image_array_size_ member is - ignored and has no effect on the value returned. The value of all other members, - except `mem_object` may be `0` to require that the value returned be supported - for all possible values of the members that are set to `0`. + - If _image_desc_ is not `NULL`, then _image_type_ must be either `0`, - {CL_MEM_OBJECT_IMAGE1D_ARRAY} or {CL_MEM_OBJECT_IMAGE2D_ARRAY}, otherwise - {CL_INVALID_IMAGE_DESCRIPTOR} is returned. + - TODO: should we require _image_array_size_ to be `0`? -|==== - -// refError - -{clGetImageRequirementsInfoEXT} returns {CL_SUCCESS} if the function is executed -successfully. -Otherwise, it returns one of the following errors: - - * {CL_INVALID_CONTEXT} if _context_ if not a valid context. - * {CL_INVALID_PROPERTY} if a property name in properties is not a supported - property name, if the value specified for a supported property name is not - valid, or if the same property name is specified more than once. - * {CL_INVALID_VALUE} if values specified in _flags_ are not valid. - * {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if values specified in _image_format_ - are not valid. - * {CL_INVALID_IMAGE_DESCRIPTOR} if values specified in _image_desc_ - are not valid. - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and - _param_value_ is not `NULL`. - * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required - by the OpenCL implementation on the device. - * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources - required by the OpenCL implementation on the host. --- --- - -== Interactions with Other Extensions - -This extension interacts with `cl_khr_image2d_from_buffer`. - -When `cl_khr_image2d_from_buffer` is supported: - -- The value returned by {CL_DEVICE_IMAGE_PITCH_ALIGNMENT} after converting in - bytes for the supported format with the biggest element size - (channel data type size * number of channels) must be greater than or equal - to the value returned by {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} for any - supported format. -- The value returned by {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT} after converting - in bytes for the supported format with the biggest element size - (channel data type size * number of channels) must be greater than or equal to - the value returned by {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} for any - supported format. - -== Conformance tests - -. Basic checks for {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} and {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} -* For all image formats and types -** Check that the {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} and {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} queries can be performed successfully and that the values returned are a power of two. - -. Check consistency with `cl_khr_image2d_from_buffer` -* When `cl_khr_image2d_from_buffer` is supported, check that the value returned by {CL_DEVICE_IMAGE_PITCH_ALIGNMENT} after converting in bytes for the supported format with the biggest element size (channel data type size * number of channels) is greater than or equal to the value returned by {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} for all supported formats. -* When `cl_khr_image2d_from_buffer` is supported, check that the value returned by {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT} after converting in bytes for the supported format with the biggest element size (channel data type size * number of channels) is greater than or equal to the value returned by {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} for all supported formats. - -. Negative tests for {CL_IMAGE_REQUIREMENTS_SIZE_EXT} -* Check that attempting to perform the {CL_IMAGE_REQUIREMENTS_SIZE_EXT} query without specifying the _image_format_ results in {CL_INVALID_VALUE} being returned. -* Check that attempting to perform the {CL_IMAGE_REQUIREMENTS_SIZE_EXT} query without specifying the _image_desc_ results in {CL_INVALID_VALUE} being returned. - -. Consistency checks for {CL_IMAGE_REQUIREMENTS_SIZE_EXT} -* When creating 2D images from a buffer is supported, for all formats and a selection of image dimensions -** Check that the {CL_IMAGE_REQUIREMENTS_SIZE_EXT} query can be performed successfully. -** Create a buffer with the size returned and check that an image can successfully be created from the buffer. -** Check that the value returned for {CL_MEM_SIZE} for the image is the same as the value returned for {CL_IMAGE_REQUIREMENTS_SIZE_EXT}. - -. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT} -* For all image formats, image types and a selection of values for other members in _image_desc_ (that MUST include `0`) -** Check that the {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT} query can be performed successfully -** Check that the value is smaller than or equal to the value returned for {CL_DEVICE_IMAGE_MAX_BUFFER_SIZE} for images of {CL_MEM_OBJECT_IMAGE1D_BUFFER} type or smaller than or equal to the value returned for {CL_DEVICE_IMAGE3D_MAX_WIDTH} for images of {CL_MEM_OBJECT_IMAGE3D} type or smaller than or equal to the value returned for {CL_DEVICE_IMAGE2D_MAX_WIDTH} for all other image types. - -. Negative tests for {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} -* Attempt to perform the {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} query on all image types for which it is not valid -* Check that {CL_INVALID_IMAGE_DESCRIPTOR} is returned in all cases. - -. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} -* For all image formats, valid image types and a selection of values for other members in _image_desc_ (that MUST include `0`) -** Check that the {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} query can be performed successfully -** Check that the value is smaller than or equal to the value returned for {CL_DEVICE_IMAGE2D_MAX_HEIGHT} for 2D or 2D array images or {CL_DEVICE_IMAGE3D_MAX_HEIGHT} for 3D images. - -. Negative testing for {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} -* Attempt to perform the {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} query on all image types for which it is not valid -* Check that {CL_INVALID_IMAGE_DESCRIPTOR} is returned in all cases. - -. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} -* For all image formats, valid image types and a selection of values for other members in _image_desc_ (that MUST include `0`) -** Check that the {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} query can be performed successfully -** Check that the value is smaller than or equal to the value returned for {CL_DEVICE_IMAGE3D_MAX_DEPTH}. - -. Negative testing for {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} -* Attempt to perform the {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} query on all image types for which it is not valid -* Check that {CL_INVALID_IMAGE_DESCRIPTOR} is returned in all cases. - -. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} -* For all image formats, valid image types and a selection of values for other members in _image_desc_ (that MUST include `0`) -** Check that the {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} query can be performed successfully -** Check that the value is smaller than or equal to the value returned for {CL_DEVICE_IMAGE_MAX_ARRAY_SIZE}. - -. General negative testing for {clGetImageRequirementsInfoEXT} -** Write tests for all possible testable generic error codes. - -== Issues - -None. - -== Version History - -[cols="5,15,15,70"] -[grid="rows"] -[options="header"] -|==== -| Version | Date | Author | Changes -| 0.5.0 | 2022-01-18 | Kevin Petit | *Initial EXT revision* -|==== diff --git a/extensions/extensions.txt b/extensions/extensions.txt index d28468b9c..6414878d7 100644 --- a/extensions/extensions.txt +++ b/extensions/extensions.txt @@ -39,8 +39,6 @@ include::cl_ext_float_atomics.asciidoc[] include::cl_ext_image_from_buffer.asciidoc[] <<< include::cl_ext_image_raw10_raw12.asciidoc[] -<<< -include::cl_ext_image_requirements_info.asciidoc[] // Vendor Extensions :leveloffset: 0