Skip to content

Commit

Permalink
generate and use an extension dictionary (#1131)
Browse files Browse the repository at this point in the history
* generate and use an extension dictionary

* change cl_khr_kernel_clock to use asciidoctor attributes
  • Loading branch information
bashbaug authored Apr 3, 2024
1 parent 75df78c commit c285aa9
Show file tree
Hide file tree
Showing 90 changed files with 909 additions and 804 deletions.
332 changes: 166 additions & 166 deletions OpenCL_C.txt

Large diffs are not rendered by default.

20 changes: 10 additions & 10 deletions api/appendix_c.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -389,54 +389,54 @@ include::{generated}/api/version-notes/CL_FLT_EPSILON.asciidoc[]
| {CL_DBL_DIG_anchor}

include::{generated}/api/version-notes/CL_DBL_DIG.asciidoc[]
Also see `<<cl_khr_fp64>>`.
Also see {cl_khr_fp64_EXT}.
| Number of decimal digits of precision for the type {cl_double_TYPE}
| {CL_DBL_MANT_DIG_anchor}

include::{generated}/api/version-notes/CL_DBL_MANT_DIG.asciidoc[]
Also see `<<cl_khr_fp64>>`.
Also see {cl_khr_fp64_EXT}.
| Number of digits in the mantissa of type {cl_double_TYPE}
| {CL_DBL_MAX_10_EXP_anchor}

include::{generated}/api/version-notes/CL_DBL_MAX_10_EXP.asciidoc[]
Also see `<<cl_khr_fp64>>`.
Also see {cl_khr_fp64_EXT}.
| Maximum positive integer such that 10 raised to this power minus one can
be represented as a normalized floating-point number of type {cl_double_TYPE}
| {CL_DBL_MAX_EXP_anchor}

include::{generated}/api/version-notes/CL_DBL_MAX_EXP.asciidoc[]
Also see `<<cl_khr_fp64>>`.
Also see {cl_khr_fp64_EXT}.
| Maximum exponent value of type {cl_double_TYPE}
| {CL_DBL_MIN_10_EXP_anchor}

include::{generated}/api/version-notes/CL_DBL_MIN_10_EXP.asciidoc[]
Also see `<<cl_khr_fp64>>`.
Also see {cl_khr_fp64_EXT}.
| Minimum negative integer such that 10 raised to this power minus one can
be represented as a normalized floating-point number of type {cl_double_TYPE}
| {CL_DBL_MIN_EXP_anchor}

include::{generated}/api/version-notes/CL_DBL_MIN_EXP.asciidoc[]
Also see `<<cl_khr_fp64>>`.
Also see {cl_khr_fp64_EXT}.
| Minimum exponent value of type {cl_double_TYPE}
| {CL_DBL_RADIX_anchor}

include::{generated}/api/version-notes/CL_DBL_RADIX.asciidoc[]
Also see `<<cl_khr_fp64>>`.
Also see {cl_khr_fp64_EXT}.
| Base value of type {cl_double_TYPE}
| {CL_DBL_MAX_anchor}

include::{generated}/api/version-notes/CL_DBL_MAX.asciidoc[]
Also see `<<cl_khr_fp64>>`.
Also see {cl_khr_fp64_EXT}.
| Maximum value of type {cl_double_TYPE}
| {CL_DBL_MIN_anchor}

include::{generated}/api/version-notes/CL_DBL_MIN.asciidoc[]
Also see `<<cl_khr_fp64>>`.
Also see {cl_khr_fp64_EXT}.
| Minimum value of type {cl_double_TYPE}
| {CL_DBL_EPSILON_anchor}

include::{generated}/api/version-notes/CL_DBL_EPSILON.asciidoc[]
Also see `<<cl_khr_fp64>>`.
Also see {cl_khr_fp64_EXT}.
| Minimum positive floating-point number of type {cl_double_TYPE} such that
`1.0 {plus} {CL_DBL_EPSILON} != 1` is true.
| {CL_NAN_anchor}
Expand Down
118 changes: 59 additions & 59 deletions api/appendix_e.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -74,11 +74,11 @@ The following features are added to the OpenCL C programming language
_section 6.12.3_.
** *async_work_group_strided_copy* defined in section _6.15.11_.
** *vec_step*, *shuffle* and *shuffle2* defined in section _6.15.13_.
* `<<cl_khr_byte_addressable_store>>` extension is a core feature.
* `<<cl_khr_global_int32_base_atomics>>`,
`<<cl_khr_global_int32_extended_atomics>>`,
`<<cl_khr_local_int32_base_atomics>>` and
`<<cl_khr_local_int32_extended_atomics>>` extensions are core features.
* {cl_khr_byte_addressable_store_EXT} extension is a core feature.
* {cl_khr_global_int32_base_atomics_EXT},
{cl_khr_global_int32_extended_atomics_EXT},
{cl_khr_local_int32_base_atomics_EXT} and
{cl_khr_local_int32_extended_atomics_EXT} extensions are core features.
The built-in atomic function names are changed to use the *atomic_*
prefix instead of *atom_*.
* Macros `CL_VERSION_1_0` and `CL_VERSION_1_1`.
Expand All @@ -97,13 +97,13 @@ The following features in OpenCL 1.0 are deprecated (see glossary) in OpenCL
* The `-cl-strict-aliasing` build option has been deprecated.
It is no longer required after defining type-based aliasing rules.
// Bugzilla 5593 and 6068
* The `<<cl_khr_select_fprounding_mode>>` extension is deprecated and its
* The {cl_khr_select_fprounding_mode_EXT} extension is deprecated and its
use is no longer recommended.

The following new extensions are added to _section 9_ in OpenCL 1.1:

* `<<cl_khr_gl_event>>` for creating a CL event object from a GL sync object.
* `<<cl_khr_d3d10_sharing>>` for sharing memory objects with Direct3D 10.
* {cl_khr_gl_event_EXT} for creating a CL event object from a GL sync object.
* {cl_khr_d3d10_sharing_EXT} for sharing memory objects with Direct3D 10.

The following modifications are made to the OpenCL ES Profile described in
_section 10_ in OpenCL 1.1:
Expand Down Expand Up @@ -146,7 +146,7 @@ runtime (_sections 4 and 5_):
a kernel.
* {clEnqueueMarkerWithWaitList} and {clEnqueueBarrierWithWaitList} APIs.
* {clUnloadPlatformCompiler} to request that a single platform's compiler is
unloaded. This is compatible with the `<<cl_khr_icd>>` extension if that is
unloaded. This is compatible with the {cl_khr_icd_EXT} extension if that is
supported, unlike {clUnloadCompiler}.

The following features are added to the OpenCL C programming language
Expand Down Expand Up @@ -183,7 +183,7 @@ The following APIs in OpenCL 1.1 are deprecated (see glossary) in OpenCL
// Bugzilla 5391 - cl_khr_icd specification
* {clUnloadCompiler} and {clGetExtensionFunctionAddress} APIs are deprecated.
The {clUnloadPlatformCompiler} and {clGetExtensionFunctionAddressForPlatform}
APIs provide equivalent functionality are compatible with the `<<cl_khr_icd>>`
APIs provide equivalent functionality are compatible with the {cl_khr_icd_EXT}
extension.

The following queries are deprecated (see glossary) in OpenCL 1.2:
Expand Down Expand Up @@ -465,14 +465,14 @@ Changes from *v3.0.5*:

* Fixed the calculation in "mapping work-items onto an ND-range".
* Added new extensions:
** `<<cl_khr_extended_versioning>>`
** `<<cl_khr_subgroup_extended_types>>`
** `<<cl_khr_subgroup_non_uniform_vote>>`
** `<<cl_khr_subgroup_ballot>>`
** `<<cl_khr_subgroup_non_uniform_arithmetic>>`
** `<<cl_khr_subgroup_shuffle>>`
** `<<cl_khr_subgroup_shuffle_relative>>`
** `<<cl_khr_subgroup_clustered_reduce>>`
** {cl_khr_extended_versioning_EXT}
** {cl_khr_subgroup_extended_types_EXT}
** {cl_khr_subgroup_non_uniform_vote_EXT}
** {cl_khr_subgroup_ballot_EXT}
** {cl_khr_subgroup_non_uniform_arithmetic_EXT}
** {cl_khr_subgroup_shuffle_EXT}
** {cl_khr_subgroup_shuffle_relative_EXT}
** {cl_khr_subgroup_clustered_reduce_EXT}

Changes from *v3.0.6*:

Expand All @@ -481,38 +481,38 @@ Changes from *v3.0.6*:
* Clarified the table structure in the backwards compatibility appendix.
* Clarified that `-cl-unsafe-math-optimizations` also implies `-cl-denorms-are-zero`.
* Added new extensions:
** `<<cl_khr_extended_bit_ops>>`
** `<<cl_khr_pci_bus_info>>`
** `<<cl_khr_spirv_extended_debug_info>>`
** `<<cl_khr_spirv_linkonce_odr>>`
** `<<cl_khr_suggested_local_work_size>>`
** {cl_khr_extended_bit_ops_EXT}
** {cl_khr_pci_bus_info_EXT}
** {cl_khr_spirv_extended_debug_info_EXT}
** {cl_khr_spirv_linkonce_odr_EXT}
** {cl_khr_suggested_local_work_size_EXT}

Changes from *v3.0.7*:

* Clarified optionality support for double-precision literals.
* Removed unnecessary phrase from sub-group mask function descriptions.
* Added _input_slice_pitch_ error condition for read and write image APIs.
* Added new extension:
** `<<cl_khr_integer_dot_product>>`
** {cl_khr_integer_dot_product_EXT}

Changes from *v3.0.8*:

* Added a missing error condition for {clGetKernelSuggestedLocalWorkSizeKHR}.
* Clarified requirements for {CL_DEVICE_DOUBLE_FP_CONFIG} prior to OpenCL 2.0.
* Clarified the behavior of ballot operations for remainder sub-groups.
* Added new extensions:
** `<<cl_khr_integer_dot_product>>` (version 2)
** `<<cl_khr_semaphore>>` (provisional)
** `<<cl_khr_external_semaphore>>` (provisional)
** `<<cl_khr_external_semaphore_dx_fence>>` (provisional)
** `<<cl_khr_external_semaphore_opaque_fd>>` (provisional)
** `<<cl_khr_external_semaphore_sync_fd>>` (provisional)
** `<<cl_khr_external_semaphore_win32>>` (provisional)
** `<<cl_khr_external_memory>>` (provisional)
** `<<cl_khr_external_memory_dma_buf>>` (provisional)
** `<<cl_khr_external_memory_dx>>` (provisional)
** `<<cl_khr_external_memory_opaque_fd>>` (provisional)
** `<<cl_khr_external_memory_win32>>` (provisional)
** {cl_khr_integer_dot_product_EXT} (version 2)
** {cl_khr_semaphore_EXT} (provisional)
** {cl_khr_external_semaphore_EXT} (provisional)
** {cl_khr_external_semaphore_dx_fence_EXT} (provisional)
** {cl_khr_external_semaphore_opaque_fd_EXT} (provisional)
** {cl_khr_external_semaphore_sync_fd_EXT} (provisional)
** {cl_khr_external_semaphore_win32_EXT} (provisional)
** {cl_khr_external_memory_EXT} (provisional)
** {cl_khr_external_memory_dma_buf_EXT} (provisional)
** {cl_khr_external_memory_dx_EXT} (provisional)
** {cl_khr_external_memory_opaque_fd_EXT} (provisional)
** {cl_khr_external_memory_win32_EXT} (provisional)

Changes from *v3.0.9*:

Expand All @@ -521,10 +521,10 @@ Changes from *v3.0.9*:
* Clarified that {clCompileProgram} is valid for programs created from SPIR.
* Documented the possible state of a kernel object after a failed call to {clSetKernelArg}.
* Added new extensions:
** `<<cl_khr_async_work_group_copy_fence>>` (final)
** `<<cl_khr_extended_async_copies>>` (final)
** `<<cl_khr_expect_assume>>`
** `<<cl_khr_command_buffer>>` (provisional)
** {cl_khr_async_work_group_copy_fence_EXT} (final)
** {cl_khr_extended_async_copies_EXT} (final)
** {cl_khr_expect_assume_EXT}
** {cl_khr_command_buffer_EXT} (provisional)

Changes from *v3.0.10*:

Expand All @@ -537,38 +537,38 @@ Changes from *v3.0.10*:
* Clarified that the extended versioning extension is a core OpenCL 3.0 feature.
* Clarified sub-group clustered reduction behavior when the cluster size is not an integer constant or a power of two.
* Added new extensions:
** `<<cl_khr_subgroup_rotate>>`
** `<<cl_khr_work_group_uniform_arithmetic>>`
** {cl_khr_subgroup_rotate_EXT}
** {cl_khr_work_group_uniform_arithmetic_EXT}

Changes from *v3.0.11*:

* Added a definition for a valid object and requirements for testing for valid objects.
* Added a maximum limit for the number of arguments supported by a kernel.
* Clarified requirements for comparability and uniqueness of object handles.
* Clarified behavior for invalid device-side enqueue `clk_event_t` handles.
* Clarified `<<cl_khr_command_buffer>>` interactions with other extensions.
* Clarified {cl_khr_command_buffer_EXT} interactions with other extensions.
* Specified error behavior when a command buffer is finalized multiple times.
* Added new extension:
** `<<cl_khr_command_buffer_mutable_dispatch>>` (provisional)
** {cl_khr_command_buffer_mutable_dispatch_EXT} (provisional)

Changes from *v3.0.12*:

* Fixed the accuracy requirements description for half-precision math functions (those prefixed by `half_`).
* Clarified that the semaphore type must always be provided when creating a semaphore.
* Removed an unnecessary and contradictory error condition when creating a semaphore.
* Added an issue regarding non-linear image import to the `<<cl_khr_external_memory>>` extension.
* Added missing calls to {clBuildProgram} to the `<<cl_khr_command_buffer>>` and `<<cl_khr_command_buffer_mutable_dispatch>>` sample code.
* Added an issue regarding non-linear image import to the {cl_khr_external_memory_EXT} extension.
* Added missing calls to {clBuildProgram} to the {cl_khr_command_buffer_EXT} and {cl_khr_command_buffer_mutable_dispatch_EXT} sample code.
* Fixed a copy-paste error in the extensions quick reference appendix.
* Fixed typos and improved formatting consistency in the extensions spec.

Changes from *v3.0.13*:

* Corrected the precision for `cross` and `dot` to be based on `HALF_EPSILON` in `<<cl_khr_fp16>>`, see {khronos-opencl-pr}/893[#893].
* Added a context query for command-buffers to `<<cl_khr_command_buffer>>`, see {khronos-opencl-pr}/899[#899].
* Updated the semaphore wait and signal rules for binary semaphores in `<<cl_khr_semaphore>>`, see {khronos-opencl-pr}/882[#882].
* Removed redundant error conditions from `<<cl_khr_external_semaphore>>` and `<<cl_khr_external_memory>>`, see {khronos-opencl-pr}/903[#903] and {khronos-opencl-pr}/904[#904].
* Corrected the precision for `cross` and `dot` to be based on `HALF_EPSILON` in {cl_khr_fp16_EXT}, see {khronos-opencl-pr}/893[#893].
* Added a context query for command-buffers to {cl_khr_command_buffer_EXT}, see {khronos-opencl-pr}/899[#899].
* Updated the semaphore wait and signal rules for binary semaphores in {cl_khr_semaphore_EXT}, see {khronos-opencl-pr}/882[#882].
* Removed redundant error conditions from {cl_khr_external_semaphore_EXT} and {cl_khr_external_memory_EXT}, see {khronos-opencl-pr}/903[#903] and {khronos-opencl-pr}/904[#904].
* Added new extension:
** `<<cl_khr_command_buffer_multi_device>>` (provisional)
** {cl_khr_command_buffer_multi_device_EXT} (provisional)

Changes from *v3.0.14*:

Expand All @@ -578,28 +578,28 @@ Changes from *v3.0.14*:
* Clarified that {clSetCommandQueueProperty} is only required for OpenCL 1.0 devices and may return an error otherwise, see {khronos-opencl-pr}/980[#980].
* Clarified that the application must ensure the free function passed to {clEnqueueSVMFree} is thread safe, see {khronos-opencl-pr}/1016[#1016].
* Clarified that the application must ensure the user function passed to {clEnqueueNativeKernel} is thread safe, see {khronos-opencl-pr}/1026[#1026].
* `<<cl_khr_command_buffer>>` (provisional):
* {cl_khr_command_buffer_EXT} (provisional):
** Removed the "invalid" command buffer state, see {khronos-opencl-pr}/885[#885].
** Added support for recording SVM memory copies and memory fills in a command buffer, see {khronos-opencl-pr}/915[#915].
* `<<cl_khr_command_buffer_multi_device>>` (provisional):
* {cl_khr_command_buffer_multi_device_EXT} (provisional):
** Clarified that the sync devices query should only return root devices, see {khronos-opencl-pr}/925[#925].
* `<<cl_khr_external_memory>>` (provisional):
* {cl_khr_external_memory_EXT} (provisional):
** Disallowed specifying a device handle list without also specifying an external memory handle, see {khronos-opencl-pr}/922[#922].
** Added a query to determine the handle types an implementation will assume have a linear memory layout, see {khronos-opencl-pr}/940[#940].
** Added an external memory-specific device handle list enum, see {khronos-opencl-pr}/956[#956].
** Clarified that implementations may acquire information about an image from an external memory handle when the image is created, see {khronos-opencl-pr}/970[#970].
* `<<cl_khr_external_semaphore>>` (provisional):
* {cl_khr_external_semaphore_EXT} (provisional):
** Added the ability to re-import "sync fd" handles into an existing semaphore, see {khronos-opencl-pr}/939[#939].
** Clarified that a semaphore may only export one handle type, and that a semaphore created from an external handle cannot also export a handle, see {khronos-opencl-pr}/975[#975].
** Clarified that `<<cl_khr_external_semaphore>>` requires support for `<<cl_khr_semaphore>>`, see {khronos-opencl-pr}/976[#976].
** Clarified that {cl_khr_external_semaphore_EXT} requires support for {cl_khr_semaphore_EXT}, see {khronos-opencl-pr}/976[#976].
** Added a query to determine if a semaphore may export an external handle, see {khronos-opencl-pr}/997[#997].
* `<<cl_khr_semaphore>>` (provisional):
* {cl_khr_semaphore_EXT} (provisional):
** Added an semaphore-specific device handle list enum, see {khronos-opencl-pr}/956[#956].
** Restricted semaphores to a single associated device, see {khronos-opencl-pr}/996[#996].
* `<<cl_khr_subgroup_rotate>>`:
* {cl_khr_subgroup_rotate_EXT}:
** Clarified that only rotating within a subgroup is supported, see {khronos-opencl-pr}/967[#967].

Changes from *v3.0.15*:

* Added new extensions:
** `<<cl_khr_kernel_clock>>` (provisional)
** {cl_khr_kernel_clock_EXT} (provisional)
6 changes: 3 additions & 3 deletions api/appendix_h.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -313,7 +313,7 @@ When creating a 2D image from a buffer is not supported:

| {clGetDeviceInfo}, passing +
{CL_DEVICE_EXTENSIONS}
| Will not describe support for the `<<cl_khr_image2d_from_buffer>>` extension if _device_ does not support creating a 2D image from a buffer.
| Will not describe support for the {cl_khr_image2d_from_buffer_EXT} extension if _device_ does not support creating a 2D image from a buffer.

| {clCreateImage} or +
{clCreateImageWithProperties}, passing +
Expand Down Expand Up @@ -424,7 +424,7 @@ When sub-groups are not supported:

| {clGetDeviceInfo}, passing +
{CL_DEVICE_EXTENSIONS}
| Will not describe support for the `<<cl_khr_subgroups>>` extension if _device_ does not support sub-groups.
| Will not describe support for the {cl_khr_subgroups_EXT} extension if _device_ does not support sub-groups.

| {clGetKernelSubGroupInfo}
| Returns {CL_INVALID_OPERATION} if _device_ does not support sub-groups.
Expand Down Expand Up @@ -468,7 +468,7 @@ When writing to 3D image objects is not supported:

| {clGetDeviceInfo}, passing +
{CL_DEVICE_EXTENSIONS}
| Will not describe support for the `<<cl_khr_3d_image_writes>>` extension if _device_ does not support writing to 3D image objects.
| Will not describe support for the {cl_khr_3d_image_writes_EXT} extension if _device_ does not support writing to 3D image objects.

| {clGetSupportedImageFormats}, passing +
{CL_MEM_OBJECT_IMAGE3D} and one of +
Expand Down
2 changes: 1 addition & 1 deletion api/cl_khr_3d_image_writes.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_3d_image_writes.txt[]

=== Description

`cl_khr_3d_image_writes` adds built-in OpenCL C functions that allow a
{cl_khr_3d_image_writes_EXT} adds built-in OpenCL C functions that allow a
kernel to write to 3D image objects in addition to 2D image objects.

See the link:{OpenCLCSpecURL}#cl_khr_3d_image_writes[3D Image Writes]
Expand Down
2 changes: 1 addition & 1 deletion api/cl_khr_async_work_group_copy_fence.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_async_work_group_copy_fence.txt[]

=== Description

`cl_khr_async_work_group_copy_fence` adds a new built-in OpenCL C function
{cl_khr_async_work_group_copy_fence_EXT} adds a new built-in OpenCL C function
to establish a memory synchronization ordering of asynchronous copies.

See the link:{OpenCLCSpecURL}#cl_khr_async_work_group_copy_fence[Async
Expand Down
2 changes: 1 addition & 1 deletion api/cl_khr_byte_addressable_store.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ include::{generated}/meta/{refprefix}cl_khr_byte_addressable_store.txt[]

=== Description

`cl_khr_byte_addressable_store` relaxes restrictions on pointers to `char`,
{cl_khr_byte_addressable_store_EXT} relaxes restrictions on pointers to `char`,
`uchar`, `char2`, `uchar2`, `short`, `ushort` and `half` that were present
in _Section 6.8m: Restrictions_ of the OpenCL 1.0 specification.
With this extension, applications are able to read from and write to
Expand Down
Loading

0 comments on commit c285aa9

Please sign in to comment.