Begin integration of EXT extensions into the unified specification

- Add a khr+ext spec type to makeSpec and cover in CI - Document the version and dependencies of all EXT extensions in the XML - Integrate cl_ext_cxx_for_opencl into the unified specification - Add placeholder descriptions for all EXT extensions linking to either core/KHR features that supersede old extensions that were never part of the specification or the OpenCL Extensions document. This enables us to integrate EXT extensions incrementally and integrate future EXT extensions directly into the unified specification. Change-Id: Ic634ce000ad3ebfb56e56bce91f9c0de3e786383 Signed-off-by: Kevin Petit <[email protected]>
kpet · Jul 17, 2024 · c74335c · c74335c
1 parent 6be4f45
commit c74335c
Show file tree

Hide file tree

Showing 15 changed files with 241 additions and 165 deletions.
diff --git a/.github/workflows/presubmit.yml b/.github/workflows/presubmit.yml
@@ -47,10 +47,14 @@ jobs:
         run: |
           python3 makeSpec -clean -spec core OUTDIR=out.core -j 5 -O api c env ext cxx4opencl
 
-      - name: Generate core + extension specs (HTML)
+      - name: Generate core + KHR extension specs (HTML)
         run: |
           python3 makeSpec -clean -spec khr OUTDIR=out.khr -j -O html
 
+      - name: Generate core + KHR + EXT extension specs (HTML)
+        run: |
+          python3 makeSpec -clean -spec khr+ext OUTDIR=out.khr+ext -j -O html
+
       - name: Generate reference pages
         run: |
           python3 makeSpec -spec khr OUTDIR=out.refpages -j -O manhtmlpages
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,20 @@
+// 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
+
+This extension is described in the OpenCL Extensions document.
+
+=== 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,20 @@
+// 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
+
+This extension is described in the OpenCL Extensions document.
+
+=== 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,20 @@
+// 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
+
+This extension is described in the OpenCL Extensions document.
+
+=== 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,20 @@
+// 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
+
+This extension is described in the OpenCL Extensions document.
+
+=== Version History
+
+  * Revision 0.5.0, 2022-01-18
+  ** First version.
diff --git a/api/cl_ext_migrate_memobject.asciidoc b/api/cl_ext_migrate_memobject.asciidoc
@@ -0,0 +1,35 @@
+// Copyright 2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}cl_ext_migrate_memobject.txt[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2024-07-17
+*IP Status*::
+    No known IP claims.
+
+=== Description
+
+Precursor to {clEnqueueMigrateMemObjects}.
+
+=== New Commands
+
+  * {clEnqueueMigrateMemObjectEXT}
+
+=== New Types
+
+  * {cl_mem_migration_flags_ext_TYPE}
+
+=== New Enums
+
+  * {cl_mem_migration_flags_ext_TYPE}
+  ** {CL_MIGRATE_MEM_OBJECT_HOST_EXT}
+  * {cl_command_type_TYPE}
+  ** {CL_COMMAND_MIGRATE_MEM_OBJECT_EXT}
+
+=== Version History
+
+  * Revision 1.0.0, 2024-07-17
+  ** Initial version.
diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc
@@ -2083,6 +2083,15 @@ include::{generated}/api/version-notes/CL_DEVICE_TERMINATE_CAPABILITY_KHR.asciid
       {CL_DEVICE_TERMINATE_CAPABILITY_CONTEXT_KHR_anchor} - Indicates that
       context termination is supported.
 endif::cl_khr_terminate_context[]
+
+ifdef::cl_ext_cxx_for_opencl[]
+| {CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT_anchor}
+
+include::{generated}/api/version-notes/CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT.asciidoc[]
+  | {cl_version_TYPE}
+    | Returns the version of the C++ for OpenCL language supported by the
+      device compiler.
+endif::cl_ext_cxx_for_opencl[]
 |====
 
 ifdef::cl_khr_integer_dot_product[]
@@ -2630,6 +2639,7 @@ Otherwise it may return
 endif::cl_khr_d3d11_sharing[]
 
 
+[[platform-device-partitioning]]
 == Partitioning a Device
 
 NOTE: Partitioning devices is <<unified-spec, missing before>> version 1.2.

diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc
@@ -8426,6 +8426,10 @@ header or implementation-defined source for custom devices that support an
 online compiler.
 OpenCL {cpp} is not supported as an online-compiled kernel language through
 this interface.
+ifdef::cl_ext_cxx_for_opencl[]
+If the {cl_ext_cxx_for_opencl_EXT} extension is supported, the source code
+specified by _strings_ may also be a C++ for OpenCL program source or header.
+endif::cl_ext_cxx_for_opencl[]
 
 // refError
 
@@ -9518,6 +9522,13 @@ IMPORTANT: Debugging options are <<unified-spec, missing before>> version 2.0.
     built-in functions that allow you to enqueue commands on a device (refer
     to OpenCL kernel languages specifications).
 
+ifdef::cl_ext_cxx_for_opencl[]
+==== C++ for OpenCL
+
+Applications may pass `-cl-std=CLC\++` to {clCompileProgram} or {clBuildProgram}
+for programs created using {clCreateProgramFromSource} to request the program
+be built as C++ for OpenCL.
+endif::cl_ext_cxx_for_opencl[]
 
 [[linker-options]]
 === Linker Options