Merge branch 'main' into external_memory_win32_name_handle

KhronosGroup · Sep 3, 2024 · 7f1ec6f · 7f1ec6f
2 parents a59a5ab + cf73406
commit 7f1ec6f
Show file tree

Hide file tree

Showing 58 changed files with 1,764 additions and 618 deletions.
diff --git a/.github/workflows/presubmit.yml b/.github/workflows/presubmit.yml
@@ -3,47 +3,58 @@ name: Presubmit
 permissions:
   contents: read
 
-on: [push, pull_request]
+# Controls when the action will run.
+on:
+  push:
+  workflow_dispatch:
+  pull_request:
 
+# These jobs are potentially parallelizeable
 jobs:
   build:
-    name: Build all specs
+    name: Build spec artifacts
     runs-on: ubuntu-latest
+    # Refer to the build container by its SHA instead of the name, to
+    # prevent caching problems when updating the image.
+    # container: khronosgroup/docker-images:asciidoctor-spec.20240702
+    container: khronosgroup/docker-images@sha256:4aab96a03ef292439c9bd0f972adfa29cdf838d0909b1cb4ec2a6d7b2d14a37f
 
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 0
           submodules: recursive
+          # If fetch-depth: 0 is not specified, then
+          #     git describe --tags --dirty
+          # below fails.
+          # This could also affect SPECREVISION in the Makefile.
+          fetch-depth: 0
 
-      - name: Install required packages
+      # Ownerships in the working directory are odd.
+      # . is owned by UID 1001, while repo files are owned by root.
+      # This leads to many odd messages like
+      #     fatal: detected dubious ownership in repository at '/__w/OpenCL-Docs/OpenCL-Docs'
+      # The 'git config' is a brute-force workaround.
+      - name: Git safe directory workaround
         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
+            git config --global --add safe.directory '*'
+            ls -lda . .. .git Makefile
+
+      - name: Validate XML
         run: |
-          git describe --tags --dirty
+          make -C xml validate
 
       - 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)
+          python3 makeSpec -clean -spec core OUTDIR=out.core -j 5 -O api c env ext cxx4opencl
+
+      - name: Generate core + KHR extension specs (HTML)
         run: |
-          python3 makeSpec -clean -spec khr OUTDIR=out.khr -j 12 html
+          python3 makeSpec -clean -spec khr OUTDIR=out.khr -j -O html
 
-      - name: Generate reference pages
+      - name: Generate core + KHR + EXT extension specs (HTML)
         run: |
-          python3 makeSpec -spec khr OUTDIR=out.refpages -j 12 manhtmlpages
+          python3 makeSpec -clean -spec khr+ext OUTDIR=out.khr+ext -j -O html
 
-      - name: Validate XML
+      - name: Generate reference pages
         run: |
-          make -C xml validate
+          python3 makeSpec -spec khr OUTDIR=out.refpages -j -O manhtmlpages
diff --git a/Makefile b/Makefile
@@ -14,6 +14,7 @@ EXTOPTIONS := $(foreach ext,$(EXTS),-extension $(ext))
 
 QUIET	    ?=
 VERYQUIET   ?= @
+PYTHON	    ?= python3
 ASCIIDOCTOR ?= asciidoctor
 RM	    = rm -f
 RMRF	    = rm -rf
@@ -72,8 +73,8 @@ SPECREVISION = $(shell echo `git describe --tags --dirty`)
 # This used to be a dependency in the spec html/pdf targets,
 # but that's likely to lead to merge conflicts. Just regenerate
 # when pushing a new spec for review to the sandbox.
-SPECREMARK = from git branch: $(shell echo `git symbolic-ref --short HEAD`) \
-	     commit: $(shell echo `git log -1 --format="%H"`)
+SPECREMARK = from git branch: $(shell echo `git symbolic-ref --short HEAD 2> /dev/null || echo Git branch not available`) \
+	     commit: $(shell echo `git log -1 --format="%H" 2> /dev/null || echo Git commit not available`)
 endif
 # The C++ for OpenCL document revision scheme is aligned with its release date.
 # Revision naming scheme is as follows:
@@ -116,7 +117,7 @@ ADOCCOMMONOPTS	      = -a apispec="$(CURDIR)/api" \
 			-a cspec="$(CURDIR)/c" \
 			-a images="$(CURDIR)/images" \
 			$(ATTRIBOPTS) $(NOTEOPTS) $(VERBOSE) $(ADOCEXTS)
-ADOCOPTS	      = -d book $(ADOCCOMMONOPTS)
+ADOCOPTS	      = --failure-level ERROR -d book $(ADOCCOMMONOPTS)
 
 # Asciidoctor options to build refpages
 #
@@ -511,9 +512,11 @@ $(MANHTMLDIR)/intro.html: $(REFPATH)/intro.txt $(MANCOPYRIGHT)
 
 REGISTRY       = $(ROOTDIR)/xml
 APIXML	       = $(REGISTRY)/cl.xml
+CFEATURES      = c/features.txt
 GENSCRIPT      = $(SCRIPTS)/gencl.py
 DICTSCRIPT     = $(SCRIPTS)/gen_dictionaries.py
 VERSIONSCRIPT  = $(SCRIPTS)/gen_version_notes.py
+CFEATSCRIPT    = $(SCRIPTS)/gen_c_feature_dictionary.py
 GENSCRIPTOPTS  = $(VERSIONOPTIONS) $(EXTOPTIONS) $(GENSCRIPTEXTRA) -registry $(APIXML)
 GENSCRIPTEXTRA =
 
@@ -539,12 +542,14 @@ extinc: $(METADEPEND)
 $(METADEPEND): $(APIXML) $(GENSCRIPT)
 	$(QUIET)$(MKDIR) $(METAPATH)
 	$(QUIET)$(PYTHON) $(GENSCRIPT) $(GENSCRIPTOPTS) -o $(METAPATH) extinc
+	$(QUIET)$(PYTHON) $(CFEATSCRIPT) -features $(CFEATURES) -o $(METAPATH)/c-feature-dictionary.asciidoc
 
 # This generates a single file containing asciidoc attributes for each
 # extension in the spec being built.
 attribs: $(ATTRIBFILE)
 
 $(ATTRIBFILE):
+	$(QUIET)$(MKDIR) $(dir $@)
 	for attrib in $(EXTS) ; do \
 	    echo ":$${attrib}:" ; \
 	done > $@

diff --git a/OpenCL_C.txt b/OpenCL_C.txt
@@ -5845,7 +5845,7 @@ the application.
 | `FLT_RADIX`                 | {CL_FLT_RADIX}
 | `FLT_MAX`                   | {CL_FLT_MAX}
 | `FLT_MIN`                   | {CL_FLT_MIN}
-| `FLT_EPSILSON`              | {CL_FLT_EPSILON}
+| `FLT_EPSILON`               | {CL_FLT_EPSILON}
 |====
 
 The following macros shall expand to integer constant expressions whose
@@ -5916,7 +5916,7 @@ the application.
 | `DBL_MIN_EXP`              | {CL_DBL_MIN_EXP}
 | `DBL_MAX`                  | {CL_DBL_MAX}
 | `DBL_MIN`                  | {CL_DBL_MIN}
-| `DBL_EPSILSON`             | {CL_DBL_EPSILON}
+| `DBL_EPSILON`              | {CL_DBL_EPSILON}
 |====
 
 The following constants are also available.
@@ -5986,7 +5986,7 @@ the application.
 | `HALF_RADIX`               | {CL_HALF_RADIX}
 | `HALF_MAX`                 | {CL_HALF_MAX}
 | `HALF_MIN`                 | {CL_HALF_MIN}
-| `HALF_EPSILSON`            | {CL_HALF_EPSILON}
+| `HALF_EPSILON`             | {CL_HALF_EPSILON}
 |====
 
 The following constants are also available.
@@ -17300,15 +17300,15 @@ used in the conversions described below.
 When approximate rounding is used instead of the preferred rounding, the
 result of the conversion must satisfy the bound given below.
 
-`half` {rightarrow` {CL_UNORM_INT8} (8-bit unsigned integer)
+`half` {rightarrow} {CL_UNORM_INT8} (8-bit unsigned integer)
 
 [none]
   * Let f~exact~ = *max*(`0`, *min*(`f * 255`, `255`))
   * Let f~preferred~ = *convert_uchar_sat_rte*(`f * 255.0f`)
   * Let f~approx~ = *convert_uchar_sat_<impl-rounding-mode>*(`f * 255.0f`)
   * *fabs*(f~exact~ - f~approx~) must be \<= 0.6
 
-`half` {rightarrow` {CL_UNORM_INT_101010} (10-bit unsigned integer)
+`half` {rightarrow} {CL_UNORM_INT_101010} (10-bit unsigned integer)
 
 [none]
   * Let f~exact~ = *max*(`0`, *min*(`f * 1023`, `1023`))
@@ -17317,7 +17317,7 @@ result of the conversion must satisfy the bound given below.
   * Let f~approx~ = *convert_ushort_sat_<impl-rounding-mode>*(`f * 1023.0f`)
   * *fabs*(f~exact~ - f~approx~) must be \<= 0.6
 
-`half` {rightarrow` {CL_UNORM_INT16} (16-bit unsigned integer)
+`half` {rightarrow} {CL_UNORM_INT16} (16-bit unsigned integer)
 
 [none]
   * Let f~exact~ = *max*(`0`, *min*(`f * 65535`, `65535`))
@@ -17326,15 +17326,15 @@ result of the conversion must satisfy the bound given below.
     65535.0f`)
   * *fabs*(f~exact~ - f~approx~) must be \<= 0.6
 
-`half` {rightarrow` {CL_SNORM_INT8} (8-bit signed integer)
+`half` {rightarrow} {CL_SNORM_INT8} (8-bit signed integer)
 
 [none]
   * Let f~exact~ = *max*(`-128`, *min*(`f * 127`, `127`))
   * Let f~preferred~ = *convert_char_sat_rte*(`f * 127.0f`)
   * Let f~approx~ = *convert_char_sat_<impl_rounding_mode>*(`f * 127.0f`)
   * *fabs*(f~exact~ - f~approx~) must be \<= 0.6
 
-`half` {rightarrow` {CL_SNORM_INT16} (16-bit signed integer)
+`half` {rightarrow} {CL_SNORM_INT16} (16-bit signed integer)
 
 [none]
   * Let f~exact~ = *max*(`-32768`, *min*(`f * 32767`, `32767`))

diff --git a/api/appendix_e.asciidoc b/api/appendix_e.asciidoc
@@ -377,7 +377,7 @@ device:
     capabilities of a device.
   * {CL_DEVICE_PIPE_SUPPORT} to determine whether a device supports
     pipe memory objects.
-  * {CL_DEVICE_PREFERRED_WORK_GROUP_SIZE_MULTIPLE} to determine the
+  * {CL_DEVICE_PREFERRED_WORK_GROUP_SIZE_MULTIPLE} to determine
     the preferred work-group size multiple for a device.
 
 OpenCL 3.0 adds new queries to conveniently and precisely

diff --git a/api/appendix_h.asciidoc b/api/appendix_h.asciidoc
@@ -334,7 +334,7 @@ When sRGB images are not supported:
 |*Behavior*
 
 | {clGetSupportedImageFormats}
-| Will not return return any image formats with `image_channel_order` equal to an sRGB image channel order if no devices in _context_ support sRGB images.
+| Will not return any image formats with `image_channel_order` equal to an sRGB image channel order if no devices in _context_ support sRGB images.
 
 |====
 

diff --git a/api/cl_ext_cxx_for_opencl.asciidoc b/api/cl_ext_cxx_for_opencl.asciidoc
@@ -0,0 +1,59 @@
+// Copyright 2018-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}cl_ext_cxx_for_opencl.txt[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2020-08-25
+*IP Status*::
+    No known IP claims.
+*Contributors*::
+  - Kevin Petit, Arm Ltd. +
+  - Sven Van Haastregt, Arm Ltd. +
+  - Anastasia Stulova, Arm Ltd. +
+  - Marco Antognini, Arm Ltd. +
+  - Neil Hickey, Arm Ltd. +
+  - Alastair Murray, Codeplay +
+
+=== Description
+
+This extension adds support for building programs written using the C++ for
+OpenCL kernel language documented in the *OpenCL-Docs* repository
+(https://github.com/KhronosGroup/OpenCL-Docs)
+with stable versions published in releases of the repository.
+
+This extension also enables applications to query the version of the language
+supported by the device compiler.
+
+=== New Enums
+
+  * {cl_device_info_TYPE}
+  ** {CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT}
+
+=== New build option
+
+This extension adds support for a new `CLC++` value to be passed to the
+`-cl-std` build option accepted by {clBuildProgram} and {clCompileProgram}.
+
+=== Preprocessor Macros
+
+This extension defines a new language, instead of extending an existing
+language. As such, there will be no preprocessor `#define` matching the
+extension name string. Instead, dedicated preprocessor macros conveying
+language version information are available as described in the C++ for
+OpenCL Programming Language Documentation, section 2.2.2.2 "Predefined
+macros".
+
+=== Conformance tests
+
+. Test that a program can successfully be compiled with `-cl-std=CLC++`.
+. Test with a program compiled with `-cl-std=CLC++` that the value of the
+  +__OPENCL_CPP_VERSION__+ macro agrees with the version returned by
+  `CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT`.
+
+=== Version History
+
+  * Revision 1.0.0, 2020-08-24
+  ** Initial version.
diff --git a/api/cl_ext_device_fission.asciidoc b/api/cl_ext_device_fission.asciidoc
@@ -0,0 +1,20 @@
+// Copyright 2018-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}cl_ext_device_fission.txt[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2024-07-17
+*IP Status*::
+    No known IP claims.
+
+=== Description
+
+Precursor to the functionality described in <<platform-device-partitioning>>.
+
+=== Version History
+
+  * Revision 1.0.0, 2024-07-17
+  ** First version.
diff --git a/api/cl_ext_float_atomics.asciidoc b/api/cl_ext_float_atomics.asciidoc
@@ -0,0 +1,21 @@
+// Copyright 2018-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}cl_ext_float_atomics.txt[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2020-08-12
+*IP Status*::
+    No known IP claims.
+
+=== Description
+
+The latest published specification for this extension is available on
+the https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_float_atomics.html[OpenCL registry].
+
+=== Version History
+
+  * Revision 1.0.0, 2020-08-12
+  ** First version.
diff --git a/api/cl_ext_image_from_buffer.asciidoc b/api/cl_ext_image_from_buffer.asciidoc
@@ -0,0 +1,21 @@
+// Copyright 2018-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}cl_ext_image_from_buffer.txt[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2022-01-25
+*IP Status*::
+    No known IP claims.
+
+=== Description
+
+The latest published specification for this extension is available on
+the https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_image_from_buffer.html[OpenCL registry].
+
+=== Version History
+
+  * Revision 1.0.0, 2022-01-25
+  ** First version.
diff --git a/api/cl_ext_image_raw10_raw12.asciidoc b/api/cl_ext_image_raw10_raw12.asciidoc
@@ -0,0 +1,21 @@
+// Copyright 2018-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}cl_ext_image_raw10_raw12.txt[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2023-05-03
+*IP Status*::
+    No known IP claims.
+
+=== Description
+
+The latest published specification for this extension is available on
+the https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_image_raw10_raw12.html[OpenCL registry].
+
+=== Version History
+
+  * Revision 1.0.0, 2023-05-03
+  ** First version.
diff --git a/api/cl_ext_image_requirements_info.asciidoc b/api/cl_ext_image_requirements_info.asciidoc
@@ -0,0 +1,21 @@
+// Copyright 2018-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}cl_ext_image_requirements_info.txt[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2022-01-18
+*IP Status*::
+    No known IP claims.
+
+=== Description
+
+The latest published specification for this extension is available on
+the https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_image_requirements_info.html[OpenCL registry].
+
+=== Version History
+
+  * Revision 0.5.0, 2022-01-18
+  ** First version.