Skip to content

Commit 20b89ef

Browse files
kpetbashbaug
kpet
and
bashbaug
authored
Integrate cl_ext_image_requirements_info into unified specification (#1295)
* Integrate cl_ext_image_requirements_info into unified specification Signed-off-by: Kevin Petit <kevin.petit@arm.com> Change-Id: Ia249f78aa521a8d202dfafbb736c9887574e56f9 * Update api/opencl_runtime_layer.asciidoc Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com> * Update api/opencl_runtime_layer.asciidoc Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com> --------- Signed-off-by: Kevin Petit <kevin.petit@arm.com> Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com>
1 parent 0f4b9a6 commit 20b89ef

5 files changed

Lines changed: 299 additions & 394 deletions

‎api/cl_ext_image_requirements_info.asciidoc‎

Lines changed: 89 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,104 @@
1-
// Copyright 2018-2024 The Khronos Group Inc.
1+
// Copyright 2018-2025 The Khronos Group Inc.
22
// SPDX-License-Identifier: CC-BY-4.0
33

44
include::{generated}/meta/{refprefix}cl_ext_image_requirements_info.txt[]
55

66
=== Other Extension Metadata
77

88
*Last Modified Date*::
9-
2022-01-18
9+
2025-01-06
1010
*IP Status*::
1111
No known IP claims.
12+
*Interactions and External Dependencies*::
13+
- This extension interacts with {cl_khr_image2d_from_buffer_EXT}
14+
*Contributors*::
15+
- Kevin Petit, Arm Ltd.
16+
- Jeremy Kemp, Imagination Technologies
17+
- Alastair Murray, Codeplay Software Ltd.
18+
- Balaji Calidas, Qualcomm
1219

1320
=== Description
1421

15-
The latest published specification for this extension is available on
16-
the https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_image_requirements_info.html[OpenCL registry].
22+
This extension enables applications to query requirements for an image without
23+
having to create the image.
24+
25+
=== New Commands
26+
27+
* {clGetImageRequirementsInfoEXT}
28+
29+
=== New Types
30+
31+
* {cl_image_requirements_info_ext_TYPE}
32+
33+
=== New Enums
34+
35+
* {cl_image_requirements_info_ext_TYPE}
36+
** {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT}
37+
** {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT}
38+
** {CL_IMAGE_REQUIREMENTS_SIZE_EXT}
39+
** {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT}
40+
** {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT}
41+
** {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT}
42+
** {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT}
43+
44+
=== Conformance tests
45+
46+
. Basic checks for {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} and {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT}
47+
* For all image formats and types
48+
** 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.
49+
50+
. Check consistency with `cl_khr_image2d_from_buffer`
51+
* 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.
52+
* 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.
53+
54+
. Negative tests for {CL_IMAGE_REQUIREMENTS_SIZE_EXT}
55+
* Check that attempting to perform the {CL_IMAGE_REQUIREMENTS_SIZE_EXT} query without specifying the _image_format_ results in {CL_INVALID_VALUE} being returned.
56+
* Check that attempting to perform the {CL_IMAGE_REQUIREMENTS_SIZE_EXT} query without specifying the _image_desc_ results in {CL_INVALID_VALUE} being returned.
57+
58+
. Consistency checks for {CL_IMAGE_REQUIREMENTS_SIZE_EXT}
59+
* When creating 2D images from a buffer is supported, for all formats and a selection of image dimensions
60+
** Check that the {CL_IMAGE_REQUIREMENTS_SIZE_EXT} query can be performed successfully.
61+
** Create a buffer with the size returned and check that an image can successfully be created from the buffer.
62+
** 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}.
63+
64+
. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT}
65+
* For all image formats, image types and a selection of values for other members in _image_desc_ (that MUST include `0`)
66+
** Check that the {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT} query can be performed successfully
67+
** 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.
68+
69+
. Negative tests for {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT}
70+
* Attempt to perform the {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} query on all image types for which it is not valid
71+
* Check that {CL_INVALID_IMAGE_DESCRIPTOR} is returned in all cases.
72+
73+
. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT}
74+
* For all image formats, valid image types and a selection of values for other members in _image_desc_ (that MUST include `0`)
75+
** Check that the {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT} query can be performed successfully
76+
** 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.
77+
78+
. Negative testing for {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT}
79+
* Attempt to perform the {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} query on all image types for which it is not valid
80+
* Check that {CL_INVALID_IMAGE_DESCRIPTOR} is returned in all cases.
81+
82+
. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT}
83+
* For all image formats, valid image types and a selection of values for other members in _image_desc_ (that MUST include `0`)
84+
** Check that the {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT} query can be performed successfully
85+
** Check that the value is smaller than or equal to the value returned for {CL_DEVICE_IMAGE3D_MAX_DEPTH}.
86+
87+
. Negative testing for {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT}
88+
* Attempt to perform the {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} query on all image types for which it is not valid
89+
* Check that {CL_INVALID_IMAGE_DESCRIPTOR} is returned in all cases.
90+
91+
. Consistency checks for {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT}
92+
* For all image formats, valid image types and a selection of values for other members in _image_desc_ (that MUST include `0`)
93+
** Check that the {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT} query can be performed successfully
94+
** Check that the value is smaller than or equal to the value returned for {CL_DEVICE_IMAGE_MAX_ARRAY_SIZE}.
95+
96+
. General negative testing for {clGetImageRequirementsInfoEXT}
97+
** Write tests for all possible testable generic error codes.
98+
99+
=== Issues
100+
101+
None.
17102

18103
=== Version History
19104

‎api/opencl_platform_layer.asciidoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -784,6 +784,16 @@ endif::cl_khr_image2d_from_buffer[]
784784
or 2.2 device if {CL_DEVICE_IMAGE_SUPPORT} is {CL_TRUE}.
785785

786786
This value must be 0 for devices that do not support 2D images created from a buffer.
787+
788+
ifdef::cl_ext_image_requirements_info+cl_khr_image2d_from_buffer[]
789+
If the {cl_khr_image2d_from_buffer_EXT} and {cl_ext_image_requirements_info_EXT}
790+
extensions are supported, the value returned by {CL_DEVICE_IMAGE_PITCH_ALIGNMENT}
791+
after converting in bytes for the supported format with the biggest element size
792+
(channel data type size {times} number of channels) must be greater than or equal to
793+
the value returned by {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} for any
794+
supported format.
795+
endif::cl_ext_image_requirements_info+cl_khr_image2d_from_buffer[]
796+
787797
| {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT_anchor}
788798

789799
include::{generated}/api/version-notes/CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT.asciidoc[]
@@ -802,6 +812,17 @@ endif::cl_khr_image2d_from_buffer[]
802812
or 2.2 device if {CL_DEVICE_IMAGE_SUPPORT} is {CL_TRUE}.
803813

804814
This value must be 0 for devices that do not support 2D images created from a buffer.
815+
816+
ifdef::cl_ext_image_requirements_info+cl_khr_image2d_from_buffer[]
817+
If the {cl_khr_image2d_from_buffer_EXT} and {cl_ext_image_requirements_info_EXT}
818+
extensions are supported, the value returned by
819+
{CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT} after converting in bytes for the
820+
supported format with the biggest element size
821+
(channel data type size {times} number of channels) must be greater than or equal to
822+
the value returned by {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT} for any
823+
supported format.
824+
endif::cl_ext_image_requirements_info+cl_khr_image2d_from_buffer[]
825+
805826
| {CL_DEVICE_MAX_PIPE_ARGS_anchor}
806827

807828
include::{generated}/api/version-notes/CL_DEVICE_MAX_PIPE_ARGS.asciidoc[]

0 commit comments

Comments
 (0)