env/extensions.asciidoc

// Copyright 2017-2024 The Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[[opencl_extensions]]
== OpenCL Extensions

An OpenCL environment may be modified by <<opencl-extension-spec, OpenCL
extensions>>.  For example, some OpenCL extensions may require support
for additional SPIR-V capabilities or instructions, or relax SPIR-V
restrictions.
Some OpenCL extensions may modify the OpenCL environment by requiring
consumption of a SPIR-V module that uses a SPIR-V extension.  In this case,
the implementation will include the OpenCL extension in the host API
`CL_PLATFORM_EXTENSIONS` or `CL_DEVICE_EXTENSIONS` string, but not the
corresponding SPIR-V extension.

This section describes how the OpenCL environment is modified by Khronos
(`khr`) OpenCL extensions.  Other OpenCL extensions, such as multi-vendor
(`ext`) extensions or vendor-specific extensions, describe how they modify
the OpenCL environment in their individual extension specifications.

=== Declaring SPIR-V Extensions

A SPIR-V module declares use of a SPIR-V extension using *OpExtension* and
the name of the SPIR-V extension.  For example:

----
OpExtension "SPV_KHR_extension_name"
---- 

Only use of SPIR-V extensions may be declared in a SPIR-V module using
*OpExtension*; there is never a need to declare use of an OpenCL extension
in a SPIR-V module using *OpExtension*.

=== Full and Embedded Profile Extensions

==== `cl_khr_3d_image_writes`

If the OpenCL environment supports the extension `cl_khr_3d_image_writes`,
then the environment must accept _Image_ operands to *OpImageWrite* that
are declared with with dimensionality _Dim_ equal to *3D*.

==== `cl_khr_depth_images`

If the OpenCL environment supports the extension `cl_khr_depth_images`,
then the environment must accept modules that declare 2D depth image types
using *OpTypeImage* with dimensionality _Dim_ equal to *2D* and _Depth_
equal to  1, indicating a depth image.  2D depth images may optionally be
_Arrayed_, if supported.

Additionally, the following Image Channel Orders may be returned by
*OpImageQueryOrder*:

  * *Depth*

==== `cl_khr_device_enqueue_local_arg_types`

If the OpenCL environment supports the extension
`cl_khr_device_enqueue_local_arg_types`, then then environment will allow
_Invoke_ functions to be passed to *OpEnqueueKernel* with *Workgroup*
memory pointer parameters of any type.

==== `cl_khr_fp16`

If the OpenCL environment supports the extension `cl_khr_fp16`, then the
environment must accept modules that declare the following SPIR-V
capabilities:

  * *Float16*

==== `cl_khr_fp64`

If the OpenCL environment supports the extension `cl_khr_fp64`, then the
environment must accept modules that declare the following SPIR-V
capabilities:

  * *Float64*

==== `cl_khr_gl_depth_images`

If the OpenCL environment supports the extension `cl_khr_gl_depth_images`,
then the following Image Channel Orders may additionally be returned by
*OpImageQueryOrder*:

  * *DepthStencil*

Also, the following Image Channel Data Types may additionally be returned by
*OpImageQueryFormat*:

  * *UnormInt24*

==== `cl_khr_gl_msaa_sharing`

// TODO: How does this affect the *ImageMSArray* capability?  This is currently a *Shader* capability.

If the OpenCL environment supports the extension `cl_khr_gl_msaa_sharing`,
then the environment must accept modules that declare 2D multi-sampled
image types using *OpTypeImage* with dimensionality _Dim_ equal to *2D* and
_MS_ equal to 1, indicating multi-sampled content.  2D multi-sampled images
may optionally be _Arrayed_ or _Depth_ images, if supported.

The 2D multi-sampled images may be used with the following instructions:

  * *OpImageRead*
  * *OpImageQuerySizeLod*
  * *OpImageQueryFormat*
  * *OpImageQueryOrder*
  * *OpImageQuerySamples*

//==== `cl_khr_initialize_memory`
// Do we need to say anything about this extension in this spec?

==== `cl_khr_int64_base_atomics` and `cl_khr_int64_extended_atomics`

If the OpenCL environment supports the extension `cl_khr_int64_base_atomics`
or `cl_khr_int64_extended_atomics`, then the environment must accept modules
that declare the following SPIR-V capabilities:

  * *Int64Atomics*

When the *Int64Atomics* capability is declared, 64-bit integer types are
valid for the _Result Type_ and type of _Value_ for all *Atomic Instructions*.

Note: OpenCL environments that consume SPIR-V must support both
`cl_khr_int64_base_atomics` and `cl_khr_int64_extended_atomics` or neither
of these extensions.

==== `cl_khr_mipmap_image`

If the OpenCL environment supports the extension `cl_khr_mipmap_image`,
then the environment must accept non-zero optional *Lod* _Image Operands_
for the following instructions:

  * *OpImageSampleExplicitLod*
  * *OpImageRead*
  * *OpImageQuerySizeLod*

Note: Implementations that support `cl_khr_mipmap_image` are not guaranteed
to support the *ImageMipmap* capability, since this extension does not
require non-zero optional *Lod* _Image Operands_ for *OpImageWrite*.

==== `cl_khr_mipmap_image_writes`

If the OpenCL environment supports the extension `cl_khr_mipmap_image_writes`,
then the environment must accept non-zero optional *Lod* _Image Operands_
for the following instructions:

  * *OpImageWrite*

Note: An implementation that supports `cl_khr_mipmap_image_writes` must also
support `cl_khr_mipmap_image`, and support for both extensions does
guarantee support for the *ImageMipmap* capability.

==== `cl_khr_subgroups`

If the OpenCL environment supports the extension `cl_khr_subgroups`, then
for all instructions except *OpGroupAsyncCopy* and *OpGroupWaitEvents*
the _Scope_ for _Execution_ may be:

  * *Subgroup*

Additionally, for all instructions except *Atomic Instructions* in an
OpenCL 1.2 environment, the _Scope_ for _Memory_ may be:

  * *Subgroup*

==== `cl_khr_subgroup_named_barrier`

If the OpenCL environment supports the extension
`cl_khr_subgroup_named_barrier`, then the environment must accept modules
that declare the following SPIR-V capabilities:

  * *NamedBarrier*

==== `cl_khr_spirv_no_integer_wrap_decoration`

If the OpenCL environment supports the extension `cl_khr_spirv_no_integer_wrap_decoration`, then the environment must accept modules that declare use of the extension `SPV_KHR_no_integer_wrap_decoration` via *OpExtension*.

If the OpenCL environment supports the extension `cl_khr_spirv_no_integer_wrap_decoration` and use of the SPIR-V extension `SPV_KHR_no_integer_wrap_decoration` is declared in the module via *OpExtension*, then the environment must accept modules that include the *NoSignedWrap* or *NoUnsignedWrap* decorations.

==== `cl_khr_subgroup_extended_types`

If the OpenCL environment supports the extension `cl_khr_subgroup_extended_types`, then additional types are valid for the following for *Groups* instructions with _Scope_ for _Execution_ equal to *Subgroup*:

* *OpGroupBroadcast*
* *OpGroupIAdd*, *OpGroupFAdd*
* *OpGroupSMin*, *OpGroupUMin*, *OpGroupFMin*
* *OpGroupSMax*, *OpGroupUMax*, *OpGroupFMax*

For these instructions, valid types for _Value_ are:

* Scalars of supported types:
** *OpTypeInt* (equivalent to `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`)
** *OpTypeFloat* (equivalent to `half`, `float`, and `double`)

Additionally, for *OpGroupBroadcast*, valid types for _Value_ are:

* *OpTypeVectors* with 2, 3, 4, 8, or 16 _Component Count_ components of supported types:
** *OpTypeInt* (equivalent to `char__n__`, `uchar__n__`, `short__n__`, `ushort__n__`, `int__n__`, `uint__n__`, `long__n__`, and `ulong__n__`)
** *OpTypeFloat* (equivalent to `half__n__`, `float__n__`, and `double__n__`)

==== `cl_khr_subgroup_non_uniform_vote`

If the OpenCL environment supports the extension `cl_khr_subgroup_non_uniform_vote`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities:

* *GroupNonUniform*
* *GroupNonUniformVote*

For instructions requiring these capabilities, _Scope_ for _Execution_ may be:

* *Subgroup*

For the instruction *OpGroupNonUniformAllEqual*, valid types for _Value_ are:

* Scalars of supported types:
** *OpTypeInt* (equivalent to `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`)
** *OpTypeFloat* (equivalent to `half`, `float`, and `double`)

==== `cl_khr_subgroup_ballot`

If the OpenCL environment supports the extension `cl_khr_subgroup_ballot`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities:

* *GroupNonUniformBallot*

For instructions requiring these capabilities, _Scope_ for _Execution_ may be:

* *Subgroup*

For the non-uniform broadcast instruction *OpGroupNonUniformBroadcast*, valid types for _Value_ are:

* Scalars of supported types:
** *OpTypeInt* (equivalent to `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`)
** *OpTypeFloat* (equivalent to `half`, `float`, and `double`)
* *OpTypeVectors* with 2, 3, 4, 8, or 16 _Component Count_ components of supported types:
** *OpTypeInt* (equivalent to `char__n__`, `uchar__n__`, `short__n__`, `ushort__n__`, `int__n__`, `uint__n__`, `long__n__`, and `ulong__n__`)
** *OpTypeFloat* (equivalent to `half__n__`, `float__n__`, and `double__n__`)

For the instruction *OpGroupNonUniformBroadcastFirst*, valid types for _Value_ are:

* Scalars of supported types:
** *OpTypeInt* (equivalent to `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`)
** *OpTypeFloat* (equivalent to `half`, `float`, and `double`)

For the instruction *OpGroupNonUniformBallot*, the valid _Result Type_ is an *OpTypeVector* with four _Component Count_ components of *OpTypeInt*, with _Width_ equal to 32 and _Signedness_ equal to 0 (equivalent to `uint4`).

For the instructions *OpGroupNonUniformInverseBallot*, *OpGroupNonUniformBallotBitExtract*, *OpGroupNonUniformBallotBitCount*, *OpGroupNonUniformBallotFindLSB*, and *OpGroupNonUniformBallotFindMSB*, the valid type for _Value_ is an *OpTypeVector* with four _Component Count_ components of *OpTypeInt*, with _Width_ equal to 32 and _Signedness_ equal to 0 (equivalent to `uint4`).

For built-in variables decorated with *SubgroupEqMask*, *SubgroupGeMask*, *SubgroupGtMask*, *SubgroupLeMask*, or *SubgroupLtMask*, the supported variable type is an *OpTypeVector* with four _Component Count_ components of *OpTypeInt*, with _Width_ equal to 32 and _Signedness_ equal to 0 (equivalent to `uint4`).

==== `cl_khr_subgroup_non_uniform_arithmetic`

If the OpenCL environment supports the extension `cl_khr_subgroup_non_uniform_arithmetic`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities:

* *GroupNonUniformArithmetic*

For instructions requiring these capabilities, _Scope_ for _Execution_ may be:

* *Subgroup*

For the instructions *OpGroupNonUniformLogicalAnd*, *OpGroupNonUniformLogicalOr*, and *OpGroupNonUniformLogicalXor*, the valid type for _Value_ is *OpTypeBool*.

Otherwise, for the *GroupNonUniformArithmetic* scan and reduction instructions, valid types for _Value_ are:

* Scalars of supported types:
** *OpTypeInt* (equivalent to `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`)
** *OpTypeFloat* (equivalent to `half`, `float`, and `double`)

For the *GroupNonUniformArithmetic* scan and reduction instructions, the optional _ClusterSize_ operand must not be present.

==== `cl_khr_subgroup_shuffle`

If the OpenCL environment supports the extension `cl_khr_subgroup_shuffle`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities:

* *GroupNonUniformShuffle*

For instructions requiring these capabilities, _Scope_ for _Execution_ may be:

* *Subgroup*

For the instructions *OpGroupNonUniformShuffle* and *OpGroupNonUniformShuffleXor* requiring these capabilities, valid types for _Value_ are:

* Scalars of supported types:
** *OpTypeInt* (equivalent to `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`)
** *OpTypeFloat* (equivalent to `half`, `float`, and `double`)

==== `cl_khr_subgroup_shuffle_relative`

If the OpenCL environment supports the extension `cl_khr_subgroup_shuffle_relative`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities:

* *GroupNonUniformShuffleRelative*

For instructions requiring these capabilities, _Scope_ for _Execution_ may be:

* *Subgroup*

For the *GroupNonUniformShuffleRelative* instructions, valid types for _Value_ are:

* Scalars of supported types:
** *OpTypeInt* (equivalent to `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`)
** *OpTypeFloat* (equivalent to `half`, `float`, and `double`)

==== `cl_khr_subgroup_clustered_reduce`

If the OpenCL environment supports the extension `cl_khr_subgroup_clustered_reduce`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities:

* *GroupNonUniformClustered*

For instructions requiring these capabilities, _Scope_ for _Execution_ may be:

* *Subgroup*

When the *GroupNonUniformClustered* capability is declared, the *GroupNonUniformArithmetic* scan and reduction instructions may include the optional _ClusterSize_ operand.

==== `cl_khr_spirv_extended_debug_info`

If the OpenCL environment supports the extension `cl_khr_spirv_extended_debug_info`, then the environment must accept modules
that import the `OpenCL.DebugInfo.100` extended instruction set via *OpExtInstImport*.

==== `cl_khr_spirv_linkonce_odr`

If the OpenCL environment supports the extension `cl_khr_spirv_linkonce_odr`, then the environment must accept modules that declare use of the extension `SPV_KHR_linkonce_odr` via *OpExtension*.

If the OpenCL environment supports the extension `cl_khr_spirv_linkonce_odr` and use of the SPIR-V extension `SPV_KHR_linkonce_odr` is declared in the module via *OpExtension*, then the environment must accept modules that include the *LinkOnceODR* linkage type.

==== `cl_khr_extended_bit_ops`

If the OpenCL environment supports the extension `cl_khr_extended_bit_ops`, then the environment must accept modules that declare use of the extension `SPV_KHR_bit_instructions` via *OpExtension*.

If the OpenCL environment supports the extension `cl_khr_extended_bit_ops` and use of the SPIR-V extension `SPV_KHR_bit_instructions` is declared in the module via *OpExtension*, then the environment must accept modules that declare the *BitInstructions* capability.

==== `cl_khr_integer_dot_product`

If the OpenCL environment supports the extension `cl_khr_integer_dot_product`,
then the environment must accept modules that require `SPV_KHR_integer_dot_product` and
declare the following SPIR-V capabilities:

* *DotProductKHR*
* *DotProductInput4x8BitKHR* if `CL_DEVICE_INTEGER_DOT_PRODUCT_INPUT_4x8BIT_KHR` is supported
* *DotProductInput4x8BitPackedKHR*

==== `cl_khr_expect_assume`

If the OpenCL environment supports the extension `cl_khr_expect_assume`, then the environment must accept modules that declare use of the extension `SPV_KHR_expect_assume` via *OpExtension*.

If the OpenCL environment supports the extension `cl_khr_expect_assume` and use of the SPIR-V extension `SPV_KHR_expect_assume` is declared in the module via *OpExtension*, then the environment must accept modules that declare the following SPIR-V capabilities:

* *ExpectAssumeKHR*

==== `cl_khr_subgroup_rotate`

If the OpenCL environment supports the extension `cl_khr_subgroup_rotate`,
then the environment accept modules that require `SPV_KHR_subgroup_rotate` and
declare the following SPIR-V capabilities:

* *GroupNonUniformRotateKHR*

For instructions requiring these capabilities, _Scope_ for _Execution_ may be:

* *Subgroup*

==== `cl_khr_work_group_uniform_arithmetic`

If the OpenCL environment supports the extension `cl_khr_work_group_uniform_arithmetic`, then the environment must accept modules that declare use of the extension `SPV_KHR_uniform_group_instructions` via *OpExtension*.

If the OpenCL environment supports the extension `cl_khr_work_group_uniform_arithmetic` and use of the SPIR-V extension `SPV_KHR_uniform_group_instructions` is declared in the module via *OpExtension*, then the environment must accept modules that declare the following SPIR-V capabilities:

* *GroupUniformArithmeticKHR*

For instructions requiring these capabilities, _Scope_ for _Execution_ may be:

* *Workgroup*

For the instructions *OpGroupLogicalAndKHR*, *OpGroupLogicalOrKHR*, and *OpGroupLogicalXorKHR*, the valid type for _X_ is *OpTypeBool*.

Otherwise, for the *GroupUniformArithmeticKHR* scan and reduction instructions, valid types for _X_ are:

* Scalars of supported types:
** *OpTypeInt* with _Width_ equal to `32` or `64` (equivalent to `int`, `uint`, `long`, and `ulong`)
** *OpTypeFloat* (equivalent to `half`, `float`, and `double`)

=== Embedded Profile Extensions

==== `cles_khr_int64`

If the OpenCL environment supports the extension `cles_khr_int64`, then the
environment must accept modules that declare the following SPIR-V
capabilities:

  * *Int64*