From ada5a292425c8e4853af0729921231522faf375c Mon Sep 17 00:00:00 2001 From: Kevin Petit Date: Tue, 17 Jan 2023 15:34:34 +0000 Subject: [PATCH 1/2] WIP cl_ext_image_tiling_control Change-Id: I6c391b5ecaa203f7db566db68a7e3d124d6038a2 Signed-off-by: Kevin Petit --- .../cl_ext_image_tiling_control.asciidoc | 219 ++++++++++++++++++ extensions/extensions.txt | 2 + xml/cl.xml | 41 +++- 3 files changed, 261 insertions(+), 1 deletion(-) create mode 100644 extensions/cl_ext_image_tiling_control.asciidoc diff --git a/extensions/cl_ext_image_tiling_control.asciidoc b/extensions/cl_ext_image_tiling_control.asciidoc new file mode 100644 index 00000000..87069c16 --- /dev/null +++ b/extensions/cl_ext_image_tiling_control.asciidoc @@ -0,0 +1,219 @@ +// Copyright 2021-2023 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_tiling_control + +== Name Strings + +`cl_ext_image_tiling_control` + +== Contact + +Kevin Petit (kevin.petit 'at' arm.com) + +== Contributors + +Kevin Petit, Arm Ltd. + +Plamen Petkov, Arm Ltd. + +Ben Ashbaugh, Intel + +Balaji Calidas, Qualcomm + +Jeremy Kemp, Google + +Nikhil Joshi, NVidia + + +== Notice + +Copyright (c) 2021-2023 The Khronos Group Inc. + +== Status + +Draft + +== Version + +Built On: {docdate} + +Version: 0.2.0 + +== Dependencies + +This extension is written against the OpenCL Specification version 3.0.12. + +This extension requires OpenCL 3.0. + +== Overview + +This extension gives applications explicit control over how image data is laid out in memory. + +== New API Types + +[source,c] +---- +typedef cl_uint cl_image_tiling_ext; + +#define CL_IMAGE_TILING_LINEAR_EXT 1 +#define CL_IMAGE_TILING_OPTIMAL_EXT 2 + +typedef cl_bitfield cl_device_image_tiling_capabilities_ext; + +#define CL_DEVICE_IMAGE_TILING_DEVICE_ACCESS_EXT (1 << 0) +#define CL_DEVICE_IMAGE_TILING_HOST_ACCESS_EXT (1 << 1) +---- + +== New API Enums + +Accepted value for the _param_name_ parameter to *clGetDeviceInfo*: + +[source,c] +---- +CL_DEVICE_IMAGE_TILING_CAPABILITIES_EXT 0x4234 +---- + +Accepted value for the _properties_ parameter to *clCreateImageWithProperties*: + +[source,c] +---- +CL_MEM_IMAGE_TILING_EXT 0x4235 +---- + +Accepted value for the _param_name_ parameter to *clGetImageInfo*: + +[source,c] +---- +CL_IMAGE_TILING_EXT 0x4236 +---- + +== Modifications to the OpenCL API Specification + +(Modify Section 4.2, *Querying Devices*) :: ++ +-- + +(Add the following to Table 5, _List of supported param_names by *clGetDeviceInfo*_) :: ++ +-- + +[cols="1,1,4",options="header"] +|==== +| cl_device_info +| Return Type +| Description + +| {CL_DEVICE_IMAGE_TILING_CAPABILITIES_EXT} +| {cl_device_image_tiling_capabilities_ext_TYPE} +| Returns the image tiling capabilities supported by the device. + + +- {CL_DEVICE_IMAGE_TILING_DEVICE_ACCESS_EXT} is always set indicating that all + implementations that support `cl_ext_image_tiling_control` must support + device access to tiled images. + +- {CL_DEVICE_IMAGE_TILING_HOST_ACCESS_EXT} is set when it is allowed to pass + {CL_MEM_IMAGE_TILING_EXT} with a value different from {CL_IMAGE_TILING_LINEAR_EXT} + in the _properties_ given to *clCreateImageWithProperties* when creating host-accessible images. + Host-accessible images are all images created without {CL_MEM_HOST_NO_ACCESS}. +|==== + +-- +-- + +(Modify section 5.3.1, *Creating Image Objects*) :: ++ +-- +{CL_MEM_IMAGE_TILING_EXT} can be passed as part of the _properties_ parameter +to *clCreateImageWithProperties* to control the tiling used for the image being +created. The following values are accepted: + + * {CL_IMAGE_TILING_LINEAR_EXT}, which is the default value used if + {CL_MEM_IMAGE_TILING_EXT} is not specified in the _properties_. Image data is + laid out in so-called raster order, one row after the other, one slice or array + layer after the other in memory according to the pitches provided by the application + or calculated. + + * {CL_IMAGE_TILING_OPTIMAL_EXT} requires image data be laid out in an implementation-defined + format which can vary depending on the type of image, its format and/or dimensions. + The will attempt to select the best layout for the image. + +If {CL_MEM_IMAGE_TILING_EXT} is passed and set to a value different from +{CL_IMAGE_TILING_LINEAR_EXT}, {CL_MEM_USE_HOST_PTR} must not be set in _mem_flags_. + +If {CL_MEM_IMAGE_TILING_EXT} is passed and set to a value different from +{CL_IMAGE_TILING_LINEAR_EXT} and {CL_MEM_COPY_HOST_PTR} is set in _mem_flags_, the data +pointed to by _host_ptr_ is laid out using linear tiling and its layout is described +in the same way as for case whe {CL_MEM_IMAGE_TILING_EXT} is not set or set to +{CL_IMAGE_TILING_LINEAR_EXT}. + +When creating an image from a buffer, _image_row_pitch_ and _image_slice_pitch_ +must both be `0` if {CL_MEM_IMAGE_TILING_EXT} is passed and set to +{CL_IMAGE_TILING_OPTIMAL_EXT}. The data in the buffer and its underlying memory +are reused as-is and the exact behaviour is implementation-defined. +-- + +(Modify section 5.3.6, *Mapping Image Objects*) :: ++ +-- +If the image object is created with {CL_MEM_IMAGE_TILING_EXT} set to a value +different from {CL_IMAGE_TILING_LINEAR_EXT}, the implementation may need to +allocate memory and perform a copy as part of the map operation. The pointer +returned to the application will always point to data in linear tiling +laid out according to the returned _image_row_pitch_ and _image_slice_pitch_. +-- + +(Modify section 5.3.7, *Image Object Queries*) :: ++ +-- + +If the image object is created with {CL_MEM_IMAGE_TILING_EXT} set to a value +different from {CL_IMAGE_TILING_LINEAR_EXT}, the value returned for + +* {CL_IMAGE_ROW_PITCH} is the value that would be returned as _image_row_pitch_ + by *clEnqueueMapImage* when mapping the entire image. +* {CL_IMAGE_SLICE_PITCH} is the value that would be returned as _image_slice_pitch_ + by *clEnqueueMapImage* when mapping the entire image. + +The following is added to _Table 22: List of supported param_names by *clGetImageInfo*_: +-- + +[cols="1,1,4",options="header"] +|==== +| Image info +| Return Type +| Description + +| {CL_IMAGE_TILING_EXT} +| {cl_image_tiling_ext_TYPE} +| Return the tiling passed using the {CL_MEM_IMAGE_TILING_EXT} property or + {CL_IMAGE_TILING_LINEAR_EXT} if none was passed at image creation time. +|==== + +== Interactions with Other Extensions + +None. + +== Conformance tests + +None. + +== Issues + +. How can an application get a view of tiled image data? ++ +-- +*RESOLVED*: An application wishing to get visibility of tiled data can do so by +creating images from a buffer and mapping the buffer directly. +-- + +== Version History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|==== +| Version | Date | Author | Changes +| 0.2.0 | 2023-01-17 | Kevin Petit | WIP discussion with other vendors +| 0.1.0 | 2021-11-01 | Kevin Petit | *Initial revision* +|==== + diff --git a/extensions/extensions.txt b/extensions/extensions.txt index df0d0d5e..d6aa5399 100644 --- a/extensions/extensions.txt +++ b/extensions/extensions.txt @@ -41,6 +41,8 @@ include::cl_ext_float_atomics.asciidoc[] include::cl_ext_image_from_buffer.asciidoc[] <<< include::cl_ext_image_requirements_info.asciidoc[] +<<< +include::cl_ext_image_tiling_control.asciidoc[] // Vendor Extensions :leveloffset: 0 diff --git a/xml/cl.xml b/xml/cl.xml index dd960c85..aedd0fe4 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -252,6 +252,8 @@ server's OpenCL/api-docs repository. typedef cl_bitfield cl_device_fp_atomic_capabilities_ext; typedef cl_uint cl_image_requirements_info_ext; typedef cl_bitfield cl_platform_command_buffer_capabilities_khr; + typedef cl_uint cl_image_tiling_ext; + typedef cl_bitfield cl_device_image_tiling_capabilities_ext; Structure types @@ -1361,6 +1363,18 @@ server's OpenCL/api-docs repository. + + + + + + + + + + + + In order to synchronize vendor IDs across Khronos APIs, Vulkan's vk.xml @@ -2235,7 +2249,9 @@ server's OpenCL/api-docs repository. - + + + @@ -7367,5 +7383,28 @@ server's OpenCL/api-docs repository. + + + + + + + + + + + + + + + + + + + + + + + From 345cdd3bc5072204d2b39f517754a615469af2bd Mon Sep 17 00:00:00 2001 From: Kevin Petit Date: Thu, 24 Feb 2022 10:07:12 +0000 Subject: [PATCH 2/2] WIP cl_ext_image_drm_format_modifier Change-Id: I30630ac1232026301356e0265b074b8b41668cb2 Signed-off-by: Kevin Petit --- .../cl_ext_image_drm_format_modifier.asciidoc | 193 ++++++++++++++++++ xml/cl.xml | 30 ++- 2 files changed, 220 insertions(+), 3 deletions(-) create mode 100644 extensions/cl_ext_image_drm_format_modifier.asciidoc diff --git a/extensions/cl_ext_image_drm_format_modifier.asciidoc b/extensions/cl_ext_image_drm_format_modifier.asciidoc new file mode 100644 index 00000000..81e74000 --- /dev/null +++ b/extensions/cl_ext_image_drm_format_modifier.asciidoc @@ -0,0 +1,193 @@ +// 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_drm_format_modifier +:R: pass:q,r[^(R)^] +Khronos{R} OpenCL Working Group + +== Name Strings + +`cl_ext_image_drm_format_modifier` + +== Contact + +Please see the *Issues* list in the Khronos *OpenCL-Docs* repository: + +https://github.com/KhronosGroup/OpenCL-Docs + +== Contributors + +Kevin Petit, Arm Ltd. + +Ahmed Hesham, Arm Ltd. + + +== Notice + + +include::../copyrights.txt[] + +== Status + +Draft spec, NOT APPROVED!! + +== Version + +Built On: {docdate} + +Version: 0.1.0 + +== Dependencies + +This extension is written against the OpenCL Specification version 3.0.10. + +This extension requires OpenCL 3.0. + +This extension requires `cl_ext_image_tiling_control`. + +This extension requires `cl_ext_image_requirements_info`. + +== Overview + +This extension makes it possible to use DRM format modifiers to control the +tiling of images. + +== New API Enums + +New valid value for `cl_image_tiling_ext`: + +[source,c] +---- +#define CL_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT 3 +---- + +New error code returned by *clCreateImageWithProperties*: + +[source,c] +---- +#define CL_IMAGE_FORMAT_REQUIRES_DRM_FORMAT_MODIFIER_EXT -1109 +---- + +Accepted value for the _properties_ parameter to *clCreateImageWithProperties*: + +[source,c] +---- +CL_MEM_IMAGE_DRM_FORMAT_MODIFIER_EXT 0x4237 +---- + +Accepted value for the _param_name_ parameter to *clGetImageInfo*: + +[source,c] +---- +CL_IMAGE_DRM_FORMAT_MODIFIER_EXT 0x4238 +---- + +Accepted value for the _param_name_ parameter to *clGetImageRequirementsInfoEXT*: + +[source,c] +---- +CL_IMAGE_REQUIREMENTS_SUPPORTED_DRM_FORMAT_MODIFIERS_EXT 0x4239 +CL_IMAGE_REQUIREMENTS_DRM_FORMAT_MODIFIER_REQUIRED_EXT 0x423A +---- + +== Modifications to the OpenCL API Specification + +(Modify section 5.3.X, *Querying Image requirements*) :: ++ +-- + +The following is added to _Table XX: 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_SUPPORTED_DRM_FORMAT_MODIFIERS_EXT} +| {cl_ulong_TYPE}[] +| Return an array of supported DRM format modifiers that can be passed via + {CL_MEM_IMAGE_DRM_FORMAT_MODIFIER_EXT} when creating an image using the + parameters passed to {clGetImageRequirementsInfoEXT}. + _image_desc_ is allowed to be `NULL`. When _image_desc_ is `NULL`, each + of the modifiers returned must be correct for all possible values of + _image_desc_. + +| {CL_IMAGE_REQUIREMENTS_DRM_FORMAT_MODIFIER_REQUIRED_EXT} +| {cl_bool_TYPE} +| Returns a boolean specifying whether providing a DRM format modifier + via {CL_MEM_IMAGE_DRM_FORMAT_MODIFIER_EXT} is required when creating an image + using the parameters passed to {clGetImageRequirementsInfoEXT}. + +|==== +-- + + +(Modify section 5.3.1, *Creating Image Objects*) :: ++ +-- +The following additional values for the {CL_MEM_IMAGE_TILING_EXT} property are +accepted: + + * {CL_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT} requires image data be laid out according + to the DRM format modifier passed via the {CL_MEM_IMAGE_DRM_FORMAT_MODIFIER_EXT} + property. Applications are required to provide a value for + {CL_MEM_IMAGE_DRM_FORMAT_MODIFIER_EXT} when they set {CL_MEM_IMAGE_TILING_EXT} to + {CL_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT}. + +{CL_MEM_IMAGE_DRM_FORMAT_MODIFIER_EXT} can be passed as part of the _properties_ +parameter to *clCreateImageWithProperties* to provide the DRM format modifier +that describes the layout of image data when an image is created with +{CL_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT}. + +The following error can be returned by *clCreateImageWithProperties*: + + * {CL_IMAGE_FORMAT_REQUIRES_DRM_FORMAT_MODIFIER_EXT} when a DRM format + modifier is required to create an image with a specific combination of + parameters but was not provided. Applications can use + {CL_IMAGE_REQUIREMENTS_DRM_FORMAT_MODIFIER_REQUIRED_EXT} to determine + whether a DRM format modifier is required or not. +-- + +(Modify section 5.3.7, *Image Object Queries*) :: ++ +-- + +The following is added to _Table 22: List of supported param_names by *clGetImageInfo*_: +-- + +[cols="1,1,4",options="header"] +|==== +| Image info +| Return Type +| Description + +| {CL_IMAGE_DRM_FORMAT_MODIFIER_EXT} +| {cl_ulong_TYPE} +| If the image was created with the {CL_MEM_IMAGE_TILING_EXT} property set + to {CL_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT}, return the value that was passed + for {CL_MEM_IMAGE_DRM_FORMAT_MODIFIER_EXT}, otherwise return 0. +|==== + +== Interactions with Other Extensions + +TODO any? + +== Conformance tests + +TODO + +== Issues + +None. + +== Version History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|==== +| Version | Date | Author | Changes +| 0.1.0 | 2023-11-23 | Kevin Petit | *Initial revision* +|==== + diff --git a/xml/cl.xml b/xml/cl.xml index aedd0fe4..8b2e6375 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -662,7 +662,8 @@ server's OpenCL/api-docs repository. - + + @@ -1367,7 +1368,8 @@ server's OpenCL/api-docs repository. - + + @@ -2252,7 +2254,11 @@ server's OpenCL/api-docs repository. - + + + + + @@ -7406,5 +7412,23 @@ server's OpenCL/api-docs repository. + + + + + + + + + + + + + + + + + +