Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP cl_ext_image_tiling_control #710

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

WIP cl_ext_image_tiling_control #710

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
83bc37f
WIP cl_ext_image_tiling_control
kpet Jan 17, 2023
d40b664
Integrate cl_ext_image_tiling_control into unified spec
kpet Jan 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions api/cl_ext_image_tiling_control.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
// Copyright 2021-2025 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}cl_ext_image_tiling_control.txt[]

=== Other Extension Metadata

*Last Modified Date*::
2025-01-06
*IP Status*::
No known IP claims.
*Contributors*::
- Kevin Petit, Arm Ltd.
- Plamen Petkov, Arm Ltd.
- Ben Ashbaugh, Intel
- Balaji Calidas, Qualcomm
- Jeremy Kemp, Google
- Nikhil Joshi, NVIDIA

=== Description

This extension gives applications explicit control over how image data is laid out in memory.

=== New Types

* {cl_image_tiling_ext_TYPE}
* {cl_device_image_tiling_capabilities_ext_TYPE}

=== New Enums

* {cl_device_info_TYPE}
** {CL_DEVICE_IMAGE_TILING_CAPABILITIES_EXT}
* {cl_mem_properties_TYPE}
** {CL_MEM_IMAGE_TILING_EXT}
* {cl_image_info_TYPE}
** {CL_IMAGE_TILING_EXT}
* {cl_image_tiling_ext_TYPE}
** {CL_IMAGE_TILING_LINEAR_EXT}
** {CL_IMAGE_TILING_OPTIMAL_EXT}
* {cl_device_image_tiling_capabilities_ext_TYPE}
** {CL_DEVICE_IMAGE_TILING_DEVICE_ACCESS_EXT}
** {CL_DEVICE_IMAGE_TILING_HOST_ACCESS_EXT}

=== 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

* Revision 0.1.0, 2021-11-01
** Initial revision
* Revision 0.2.0, 2025-01-06
** WIP discussion with other vendors
18 changes: 18 additions & 0 deletions api/opencl_platform_layer.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2097,6 +2097,24 @@ include::{generated}/api/version-notes/CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_
| Returns the version of the C++ for OpenCL language supported by the
device compiler.
endif::cl_ext_cxx_for_opencl[]

ifdef::cl_ext_image_tiling_control[]
| {CL_DEVICE_IMAGE_TILING_CAPABILITIES_EXT_anchor}

include::{generated}/api/version-notes/CL_DEVICE_IMAGE_TILING_CAPABILITIES_EXT.asciidoc[]
| {cl_device_image_tiling_capabilities_ext_TYPE}
| Returns the image tiling capabilities supported by the device. +

{CL_DEVICE_IMAGE_TILING_DEVICE_ACCESS_EXT_anchor} is always set indicating
that all implementations that support {cl_ext_image_tiling_control_EXT}
must support device access to tiled images.

{CL_DEVICE_IMAGE_TILING_HOST_ACCESS_EXT_anchor} 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this work? If you want raw host access to tiled data, you would create a buffer from the image. Wouldn't the buffer inherit the no host access flag? Couldn't the image be host-inaccessible for reasons other than tiling?

Host-accessible images are all images created without {CL_MEM_HOST_NO_ACCESS}.
endif::cl_ext_image_tiling_control[]
|====

ifdef::cl_khr_integer_dot_product[]
Expand Down
60 changes: 60 additions & 0 deletions api/opencl_runtime_layer.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1996,6 +1996,39 @@ The following restrictions apply when mipmapped images are created with
images, depth images or multi-sampled (i.e. msaa) images.
endif::cl_khr_mipmap_image[]

ifdef::cl_ext_image_tiling_control[]
*Tiling Control*

{CL_MEM_IMAGE_TILING_EXT_anchor} 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_anchor}, which is the default value used if
{CL_MEM_IMAGE_TILING_EXT} is not specified in the _properties_. Image data
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should me disallow the use if this propery when importing external memory? This may contradict an external import.

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_anchor} 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 implementation 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.
endif::cl_ext_image_tiling_control[]

*Image Data in Host Memory*

For a 3D image or 2D image array, the image data specified by _host_ptr_ is
Expand Down Expand Up @@ -4091,6 +4124,14 @@ execution status of the map command.
When the map command is completed, the application can access the contents
of the mapped region using the pointer returned by {clEnqueueMapImage}.

ifdef::cl_ext_image_tiling_control[]
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_.
endif::cl_ext_image_tiling_control[]

// refError

{clEnqueueMapImage} will return a pointer to the mapped region.
Expand Down Expand Up @@ -4344,8 +4385,27 @@ include::{generated}/api/version-notes/CL_IMAGE_D3D11_SUBRESOURCE_KHR.asciidoc[]
specified when _image_ was created.
endif::cl_khr_d3d11_sharing[]

ifdef::cl_ext_image_tiling_control[]
| {CL_IMAGE_TILING_EXT_anchor}

include::{generated}/api/version-notes/CL_IMAGE_TILING_EXT.asciidoc[]
| {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.
endif::cl_ext_image_tiling_control[]

|====

ifdef::cl_ext_image_tiling_control[]
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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If an externally imported image is tiled, should we return optimal?

* {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.
endif::cl_ext_image_tiling_control[]

// refError

{clGetImageInfo} returns {CL_SUCCESS} if the function is executed
Expand Down
40 changes: 39 additions & 1 deletion xml/cl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,8 @@ server's OpenCL/api-docs repository.
<type category="define">typedef <type>cl_bitfield</type> <name>cl_platform_command_buffer_capabilities_khr</name>;</type>
<type category="define">typedef <type>cl_bitfield</type> <name>cl_mutable_dispatch_asserts_khr</name></type>
<type category="define">typedef <type>cl_bitfield</type> <name>cl_device_kernel_clock_capabilities_khr</name>;</type>
<type category="define">typedef <type>cl_uint</type> <name>cl_image_tiling_ext</name>;</type>
<type category="define">typedef <type>cl_bitfield</type> <name>cl_device_image_tiling_capabilities_ext</name>;</type>

<comment>Structure types</comment>
<type category="struct" name="cl_dx9_surface_info_khr">
Expand Down Expand Up @@ -1383,6 +1385,17 @@ server's OpenCL/api-docs repository.
<enum bitpos="2" name="CL_DEVICE_KERNEL_CLOCK_SCOPE_SUB_GROUP_KHR"/>
<unused start="3" end="63"/>
</enums>
<enums name="cl_image_tiling_ext" vendor="Multiple">
<unused start="0" end="0"/>
<enum value="1" name="CL_IMAGE_TILING_LINEAR_EXT"/>
<enum value="2" name="CL_IMAGE_TILING_OPTIMAL_EXT"/>
<unused start="3" end="0xFFFFFFFF"/>
Comment on lines +1389 to +1392
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, is this intentionally a separate value range, parallel to everything else?

</enums>
<enums name="cl_device_image_tiling_capabilities_ext" vendor="Multiple" type="bitmask">
<enum bitpos="0" name="CL_DEVICE_IMAGE_TILING_DEVICE_ACCESS_EXT"/>
<enum bitpos="1" name="CL_DEVICE_IMAGE_TILING_HOST_ACCESS_EXT"/>
<unused start="2" end="63"/>
</enums>

<enums start="0x10000" end="0x1FFFF" name="cl_khronos_vendor_id" vendor="Khronos">
<comment>
Expand Down Expand Up @@ -2261,7 +2274,9 @@ server's OpenCL/api-docs repository.
<enum value="0x4231" name="CL_DEVICE_SINGLE_FP_ATOMIC_CAPABILITIES_EXT"/>
<enum value="0x4232" name="CL_DEVICE_DOUBLE_FP_ATOMIC_CAPABILITIES_EXT"/>
<enum value="0x4233" name="CL_DEVICE_HALF_FP_ATOMIC_CAPABILITIES_EXT"/>
<unused start="0x4234" end="0x4236" comment="Reserved for cl_ext_image_tiling_control"/>
<enum value="0x4234" name="CL_DEVICE_IMAGE_TILING_CAPABILITIES_EXT"/>
<enum value="0x4235" name="CL_MEM_IMAGE_TILING_EXT"/>
<enum value="0x4236" name="CL_IMAGE_TILING_EXT"/>
<unused start="0x4237" end="0x423A" comment="Reserved for cl_ext_image_drm_modifier"/>
<unused start="0x423B" end="0x423F"/>
</enums>
Expand Down Expand Up @@ -7497,5 +7512,28 @@ server's OpenCL/api-docs repository.
<enum name="CL_UNORM_INT_2_101010_EXT"/>
</require>
</extension>
<extension name="cl_ext_image_tiling_control" revision="0.2.0" depends="CL_VERSION_3_0" supported="opencl">
<require>
<type name="cl_image_tiling_ext"/>
<type name="cl_device_image_tiling_capabilities_ext"/>
</require>
<require comment="cl_image_tiling_ext">
<enum name="CL_IMAGE_TILING_LINEAR_EXT"/>
<enum name="CL_IMAGE_TILING_OPTIMAL_EXT"/>
</require>
<require comment="cl_device_info">
<enum name="CL_DEVICE_IMAGE_TILING_CAPABILITIES_EXT"/>
</require>
<require comment="cl_device_image_tiling_capabilities_ext">
<enum name="CL_DEVICE_IMAGE_TILING_HOST_ACCESS_EXT"/>
<enum name="CL_DEVICE_IMAGE_TILING_DEVICE_ACCESS_EXT"/>
</require>
<require comment="cl_mem_properties">
<enum name="CL_MEM_IMAGE_TILING_EXT"/>
</require>
<require comment="cl_image_info">
<enum name="CL_IMAGE_TILING_EXT"/>
</require>
</extension>
</extensions>
</registry>
Loading