Merge branch 'main' into cl_khr_kernel_clock

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+ - package-ecosystem: "github-actions"
+ directory: "/"
+ schedule:
+ interval: "monthly"
+ groups:
+ github-actions:
+ patterns:
+ - "*"

.github/workflows/presubmit.yml

@@ -0,0 +1,49 @@
+name: Presubmit
+
+permissions:
+ contents: read
+
+on: [push, pull_request]
+
+jobs:
+ build:
+ name: Build all specs
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+ submodules: recursive
+
+ - name: Install required packages
+ run: |
+ sudo apt-get install -y libpango1.0-dev libwebp-dev ghostscript fonts-lyx jing libavalon-framework-java libbatik-java python3-pyparsing
+ sudo gem install asciidoctor -v 2.0.16
+ sudo gem install coderay -v 1.1.1
+ sudo gem install rouge -v 3.19.0
+ sudo gem install ttfunk -v 1.7.0
+ sudo gem install hexapdf -v 0.27.0
+ sudo gem install asciidoctor-pdf -v 2.3.4
+ sudo gem install asciidoctor-mathematical -v 0.3.5
+ sudo pip install pyparsing
+
+ - name: List git tag
+ run: |
+ git describe --tags --dirty
+
+ - name: Generate core specs (HTML and PDF)
+ run: |
+ python3 makeSpec -clean -spec core OUTDIR=out.core -j 5 api c env ext cxx4opencl
+ 
+ - name: Generate core + extension specs (HTML)
+ run: |
+ python3 makeSpec -clean -spec khr OUTDIR=out.khr -j 12 html
+
+ - name: Generate reference pages
+ run: |
+ python3 makeSpec -spec khr OUTDIR=out.refpages -j 12 manhtmlpages
+
+ - name: Validate XML
+ run: |
+ make -C xml validate

.travis.yml

@@ -1,5 +1,9 @@
 dist: focal
 
+# Only build (and deploy) on travis for tags.
+# Use GitHub actions for other CI.
+if: tag IS present
+
 language: ruby
 
 git:

OpenCL_C.txt

@@ -13912,8 +13912,8 @@ footnote:[{fn-half-supported}], `float`, and `double`
 footnote:[{fn-double-supported}].
 
 ifdef::cl_khr_subgroup_extended_types[]
-NOTE: If the `<<cl_khr_subgroup_extended_types>>` extension is supported,
-the supported `gentype`s also include `char`, `uchar`, `short`, and
+NOTE: If the `<<cl_khr_subgroup_extended_types>>` extension is supported, the
+generic type name `gentype` may additionally be `char`, `uchar`, `short`, and
 `ushort`.
 For the `sub_group_broadcast` function, `gentype` may additionally be one of
 the supported built-in vector data types `char__n__`, `uchar__n__`,

api/cl_khr_command_buffer.asciidoc

@@ -123,9 +123,12 @@ the capability is optional to enable optimizations on command-buffer recording.
 The introduction of the command-buffer abstraction enables functionality
 beyond what the `cl_khr_command_buffer` extension currently provides, i.e.
 the recording of immutable commands to a single queue which can then be
-executed without commands synchronizing outside the command-buffer. It is
-intended that extra functionality expanding on this will be provided as layered
-extensions on top of `cl_khr_command_buffer`.
+executed without commands synchronizing outside the command-buffer. Extra
+functionality expanding on this is provided as layered extensions on top of
+`cl_khr_command_buffer`. The layered extensions that currently exist are:
+
+* `<<cl_khr_command_buffer_multi_device>>`
+* `<<cl_khr_command_buffer_mutable_dispatch>>`
 
 Having `cl_khr_command_buffer` as a minimal base specification means that the
 API defines mechanisms for functionality that is not enabled by this extension,
@@ -138,29 +141,33 @@ support their intended use cases.
 
 The {clCommandNDRangeKernelKHR} entry-point defines a `properties` parameter of
 new type {cl_ndrange_kernel_command_properties_khr_TYPE}. No properties are defined
-in `cl_khr_command_buffer`, but the parameter is intended to enable future
-functionality that would change the characteristics of the kernel command.
+in `cl_khr_command_buffer`, but the parameter enables layered extensions like
+`<<cl_khr_command_buffer_mutable_dispatch>>` to define properties that inform
+the characteristics of the kernel command.
 
 ==== Command Handles
 
 All command recording entry-points define a {cl_mutable_command_khr_TYPE} output
 parameter which provides a handle to the specific command being recorded. Use of
 these output handles is not enabled by the `cl_khr_command_buffer` extension,
-but the handles will allow individual commands in a command-buffer to be
-referenced by the user. In particular, the capability for an application to use
-these handles to modify commands between enqueues of a command-buffer is
-envisaged.
+but the handles allow individual commands in a command-buffer to be
+referenced by the user.
+
+Use of these handles is enabled in `<<cl_khr_command_buffer_mutable_dispatch>>`
+to give the capability for an application to use the handles to modify commands
+between enqueues of a command-buffer.
 
 ==== List of Queues
 
 Only a single command-queue can be associated with a command-buffer in the
-`cl_khr_command_buffer` extension, but the API is designed with the intention
-that a future extension will allow commands to be recorded across multiple
-queues in the same command-buffer, providing replay of heterogeneous task
-graphs.
+`cl_khr_command_buffer` extension, but the API is designed so that the layered
+`<<cl_khr_command_buffer_multi_device>>` extension can relax this constraint
+to allow commands to be recorded across multiple queues in the same
+command-buffer, providing replay of heterogeneous task graphs.
 
-Using multiple queue functionality will result in an error without any layered
-extensions to relax usage of the following API features:
+Using multiple queue functionality will result in an error without
+`<<cl_khr_command_buffer_multi_device>>` to relax usage of the following API
+features:
 
 * When a command-buffer is created the API enables passing a list of queues
  that the command-buffer will record commands to. Only a single queue is
@@ -200,8 +207,8 @@ extensions to relax usage of the following API features:
 
 === New Structures
 
- * {cl_command_buffer_khr}
- * {cl_mutable_command_khr}
+ * {cl_command_buffer_khr_TYPE}
+ * {cl_mutable_command_khr_TYPE}
 
 === New Types
 
@@ -220,19 +227,15 @@ extensions to relax usage of the following API features:
  * {cl_device_info_TYPE}
  ** {CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR}
  ** {CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR}
- * {cl_device_command_buffer_capabilities_khr - bitfield_TYPE}
+ * {cl_device_command_buffer_capabilities_khr_TYPE}
  ** {CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINTF_KHR}
  ** {CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_ENQUEUE_KHR}
  ** {CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR}
  ** {CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR}
  * {cl_command_buffer_properties_khr_TYPE}
  ** {CL_COMMAND_BUFFER_FLAGS_KHR}
- * {cl_command_buffer_flags_khr - bitfield_TYPE}
+ * {cl_command_buffer_flags_khr_TYPE}
  ** {CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR}
- * {Error codes_TYPE}
- ** {CL_INVALID_COMMAND_BUFFER_KHR}
- ** {CL_INVALID_SYNC_POINT_WAIT_LIST_KHR}
- ** {CL_INCOMPATIBLE_COMMAND_QUEUE_KHR}
  * {cl_command_buffer_info_khr_TYPE}
  ** {CL_COMMAND_BUFFER_QUEUES_KHR}
  ** {CL_COMMAND_BUFFER_NUM_QUEUES_KHR}
@@ -246,6 +249,10 @@ extensions to relax usage of the following API features:
  ** {CL_COMMAND_BUFFER_STATE_PENDING_KHR}
  * {cl_command_type_TYPE}
  ** {CL_COMMAND_COMMAND_BUFFER_KHR}
+ * New Error Codes
+ ** {CL_INVALID_COMMAND_BUFFER_KHR}
+ ** {CL_INVALID_SYNC_POINT_WAIT_LIST_KHR}
+ ** {CL_INCOMPATIBLE_COMMAND_QUEUE_KHR}
 
 === Sample Code
 

api/cl_khr_device_uuid.asciidoc

@@ -23,7 +23,7 @@ across processes or APIs.
 
 Accepted value for the _param_name_ parameter to {clGetDeviceInfo}:
 
- * {cl_device_info}
+ * {cl_device_info_TYPE}
  ** {CL_DEVICE_UUID_KHR}
  ** {CL_DRIVER_UUID_KHR}
  ** {CL_DEVICE_LUID_VALID_KHR}

api/cl_khr_egl_event.asciidoc

@@ -54,7 +54,7 @@ context, and to reach into each such context.
  . Should we restrict which CL APIs can be used with this cl_event?
 +
 --
-*RESOLVED* Use is limited to {clEnqueueAcquire}*** calls only.
+*RESOLVED* Use is limited to calls to acquire and release memory objects only.
 --
 
  . What is the desired behaviour for this extension when EGLSyncKHR is of a

api/cl_khr_gl_sharing.asciidoc

@@ -23,7 +23,7 @@ object, using additional attributes described for {clCreateContext}.
 
 An OpenCL image object may be created from an OpenGL texture or renderbuffer
 object as described for {clCreateFromGLTexture} and
-{clCreateFromGLRenderuffer}, respectively.
+{clCreateFromGLRenderbuffer}, respectively.
 
 An OpenCL buffer object may be created from an OpenGL buffer object using
 {clCreateFromGLBuffer}.
@@ -59,7 +59,7 @@ and buffer object images with OpenCL is required by this extension.
  * {cl_gl_context_info_TYPE}
  * {cl_gl_object_type_TYPE}
  * {cl_gl_texture_info_TYPE}
- * {cl_gl_platform_info}
+ * {cl_gl_platform_info_TYPE}
 
 === New Tokens
 

api/cl_khr_semaphore.asciidoc

@@ -93,7 +93,7 @@ In particular, this extension defines:
  * New return values from {clGetEventInfo}
  ** {CL_COMMAND_SEMAPHORE_WAIT_KHR}
  ** {CL_COMMAND_SEMAPHORE_SIGNAL_KHR}
- * New error codes
+ * New Error Codes
  ** {CL_INVALID_SEMAPHORE_KHR}
 
 

api/cl_khr_subgroups.asciidoc

@@ -35,7 +35,7 @@ OpenCL C specification for more information.
 
 === New Types
 
- * {cl_kernel_sub_group_info}
+ * {cl_kernel_sub_group_info_TYPE}
 
 === New Commands
 

api/footnotes.asciidoc

@@ -68,19 +68,6 @@ This value for memory_scope can only be used with atomic_work_item_fence with fl
 Note that the performance of 64-bit integer arithmetic can vary significantly between embedded devices. \
 ]
 
-:fn-kernel-arg-type-const-addr-space: pass:n[ \
-{CL_KERNEL_ARG_TYPE_CONST} is returned for {CL_KERNEL_ARG_TYPE_QUALIFIER} if the argument is declared with the `constant` address space qualifier. \
-]
-
-:fn-kernel-arg-type-qualifier: pass:n[ \
-{CL_KERNEL_ARG_TYPE_CONST} is returned if the argument is a pointer and the referenced type is declared with the const qualifier. \
-For example, a kernel argument declared as `global int const *x` returns {CL_KERNEL_ARG_TYPE_CONST} but a kernel argument declared as `global int * const x` does not. + \
-Similarly, {CL_KERNEL_ARG_TYPE_RESTRICT} will be returned if the pointer type is marked `restrict`. \
-For example, `global int * restrict x` returns {CL_KERNEL_ARG_TYPE_RESTRICT}. + \
-{CL_KERNEL_ARG_TYPE_VOLATILE} is returned for {CL_KERNEL_ARG_TYPE_QUALIFIER} if the argument is a pointer and the referenced type is declared with the volatile qualifier. \
-For example, a kernel argument declared as `global int volatile *x` returns {CL_KERNEL_ARG_TYPE_VOLATILE} but a kernel argument declared as `global int * volatile x` does not. \
-]
-
 :fn-map-count-usage: pass:n[ \
 The map count returned should be considered immediately stale. \
 It is unsuitable for general use in applications. \
@@ -120,7 +107,7 @@ Rather than attempt to share {cl_kernel_TYPE} objects among multiple host thread
 ]
 
 :fn-readimageh: pass:n[ \
-And *read_imageh*, if the `<<cl_khr_fp16>>` extension is supported. \
+And *read_imageh*, if the `cl_khr_fp16` extension is supported. \
 ]
 
 :fn-reference-count-usage: pass:n[ \

api/opencl_architecture.asciidoc

@@ -2232,7 +2232,7 @@ working with version numbers easier.
  {CL_VERSION_PATCH_BITS_anchor} are the number of bits in the
  corresponding field.
  * `CL_VERSION_MAJOR_MASK`, `CL_VERSION_MINOR_MASK`, and
- {CL_VERSION_PATCH_MASK` are bitmasks used to extract the
+ `CL_VERSION_PATCH_MASK` are bitmasks used to extract the
  corresponding packed fields from the version number.
 
 [source,opencl]
@@ -2274,7 +2274,7 @@ corresponding entity (e.g. extension or built-in kernel) name:
 include::{generated}/api/structs/cl_name_version.txt[]
 
  * _version_ is a <<version-numbers, Version Number>>.
- * _name_ is an array of {CL_NAME_VERSION_MAX_NAME_SIZE_anchor} `char`
- containing a null-terminated string whose maximum length is therefore
- {CL_NAME_VERSION_MAX_NAME_SIZE} - 1`.
+ * _name_ is an array of {CL_NAME_VERSION_MAX_NAME_SIZE_anchor} characters
+ containing a null-terminated string, whose maximum length is therefore
+ {CL_NAME_VERSION_MAX_NAME_SIZE} minus one.
 --

api/opencl_platform_layer.asciidoc

@@ -383,35 +383,32 @@ include::{generated}/api/version-notes/CL_DEVICE_TYPE_ACCELERATOR.asciidoc[]
 
 include::{generated}/api/version-notes/CL_DEVICE_TYPE_CUSTOM.asciidoc[]
  | Specialized devices that implement some of the OpenCL runtime APIs but
- do not support all required OpenCL functionality.
+ do not support all of the required OpenCL functionality.
 
 | {CL_DEVICE_TYPE_DEFAULT_anchor}
 
 include::{generated}/api/version-notes/CL_DEVICE_TYPE_DEFAULT.asciidoc[]
  | The default OpenCL device in the platform.
+ One device in the platform must be returned as the {CL_DEVICE_TYPE_DEFAULT}
+ device when passed as the _device_type_ to {clGetDeviceIDs}.
+ {CL_DEVICE_TYPE_DEFAULT} is only used to query OpenCL devices using
+ {clGetDeviceIDs} or to create OpenCL contexts using
+ {clCreateContextFromType}, and will never be returned in {CL_DEVICE_TYPE}
+ for any OpenCL device.
  The default OpenCL device must not be a {CL_DEVICE_TYPE_CUSTOM} device.
 
 | {CL_DEVICE_TYPE_ALL_anchor}
 
 include::{generated}/api/version-notes/CL_DEVICE_TYPE_ALL.asciidoc[]
  | All OpenCL devices available in the platform, except for
  {CL_DEVICE_TYPE_CUSTOM} devices.
+ {CL_DEVICE_TYPE_ALL} is only used to query OpenCL devices using
+ {clGetDeviceIDs} or to create OpenCL contexts using
+ {clCreateContextFromType}, and will never be returned in {CL_DEVICE_TYPE}
+ for any OpenCL device.
 
 |====
 
-The device type is purely informational and has no semantic meaning.
-
-Some devices may be more than one type.
-For example, a {CL_DEVICE_TYPE_CPU} device may also be a
-{CL_DEVICE_TYPE_GPU} device, or a {CL_DEVICE_TYPE_ACCELERATOR} device
-may also be some other, more descriptive device type.
-{CL_DEVICE_TYPE_CUSTOM} devices must not be combined with any other
-device types.
-
-One device in the platform should be a {CL_DEVICE_TYPE_DEFAULT} device.
-The default device should also be a more specific device type, such
-as {CL_DEVICE_TYPE_CPU} or {CL_DEVICE_TYPE_GPU}.
-
 // refError
 
 {clGetDeviceIDs} returns {CL_SUCCESS} if the function is executed
@@ -483,10 +480,13 @@ device except for the following queries:
 
 include::{generated}/api/version-notes/CL_DEVICE_TYPE.asciidoc[]
  | {cl_device_type_TYPE}
- | The type or types of the OpenCL device.
+ | The type of the OpenCL device.
+ The device type is purely informational and has no semantic meaning.
+ The device must report a single device type, which must not be
+ {CL_DEVICE_TYPE_DEFAULT} or {CL_DEVICE_TYPE_ALL}.
 
  Please see the <<device-types-table, Device Types>> table
- for supported device types and device type combinations.
+ for supported device types and device type descriptions.
 
 | {CL_DEVICE_VENDOR_ID_anchor} footnote:[{fn-vendor-id}]