From a26e00b504534607646f0844777791663bab1b00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Tue, 13 Aug 2024 17:42:02 +0100 Subject: [PATCH] Begin integration of EXT extensions into the unified specification (#1213) * 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 * Update api/cl_ext_cxx_for_opencl.asciidoc Co-authored-by: Ewan Crawford * remove dangling links in cl_ext_migrate_memobject appendix Change-Id: I13b4860dfcd3d6d865b269847c5876bf75516e87 * add links to latest published ext specs Change-Id: Ifddbbc47ddb0ac9be6327d9925682b96829d0946 --------- Signed-off-by: Kevin Petit Co-authored-by: Ewan Crawford --- .github/workflows/presubmit.yml | 6 +- api/cl_ext_cxx_for_opencl.asciidoc | 59 ++++++++ api/cl_ext_device_fission.asciidoc | 20 +++ api/cl_ext_float_atomics.asciidoc | 21 +++ api/cl_ext_image_from_buffer.asciidoc | 21 +++ api/cl_ext_image_raw10_raw12.asciidoc | 21 +++ api/cl_ext_image_requirements_info.asciidoc | 21 +++ api/cl_ext_migrate_memobject.asciidoc | 20 +++ api/opencl_platform_layer.asciidoc | 10 ++ api/opencl_runtime_layer.asciidoc | 11 ++ extensions/cl_ext_cxx_for_opencl.asciidoc | 152 -------------------- extensions/extensions.txt | 2 - makeSpec | 9 +- scripts/extdependency.py | 8 ++ xml/cl.xml | 14 +- 15 files changed, 230 insertions(+), 165 deletions(-) create mode 100644 api/cl_ext_cxx_for_opencl.asciidoc create mode 100644 api/cl_ext_device_fission.asciidoc create mode 100644 api/cl_ext_float_atomics.asciidoc create mode 100644 api/cl_ext_image_from_buffer.asciidoc create mode 100644 api/cl_ext_image_raw10_raw12.asciidoc create mode 100644 api/cl_ext_image_requirements_info.asciidoc create mode 100644 api/cl_ext_migrate_memobject.asciidoc delete mode 100644 extensions/cl_ext_cxx_for_opencl.asciidoc diff --git a/.github/workflows/presubmit.yml b/.github/workflows/presubmit.yml index 6a2d54b3..8d446b60 100644 --- 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 new file mode 100644 index 00000000..51ead70c --- /dev/null +++ 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 new file mode 100644 index 00000000..8b038ef6 --- /dev/null +++ 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 <>. + +=== 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 new file mode 100644 index 00000000..473feb40 --- /dev/null +++ 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 new file mode 100644 index 00000000..6bd6fa9b --- /dev/null +++ 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 new file mode 100644 index 00000000..d7d36b55 --- /dev/null +++ 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 new file mode 100644 index 00000000..6de78085 --- /dev/null +++ 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. diff --git a/api/cl_ext_migrate_memobject.asciidoc b/api/cl_ext_migrate_memobject.asciidoc new file mode 100644 index 00000000..b987f48f --- /dev/null +++ b/api/cl_ext_migrate_memobject.asciidoc @@ -0,0 +1,20 @@ +// 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}. + +=== 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 index ceb6e319..2b1ae266 100644 --- 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 <> version 1.2. diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 1e7c9712..4925edd6 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -8427,6 +8427,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 @@ -9519,6 +9523,13 @@ IMPORTANT: Debugging options are <> 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 diff --git a/extensions/cl_ext_cxx_for_opencl.asciidoc b/extensions/cl_ext_cxx_for_opencl.asciidoc deleted file mode 100644 index 12bd4406..00000000 --- a/extensions/cl_ext_cxx_for_opencl.asciidoc +++ /dev/null @@ -1,152 +0,0 @@ -// Copyright 2018-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/ - -:data-uri: -:icons: font -include::../config/attribs.txt[] -:source-highlighter: coderay - -= cl_ext_cxx_for_opencl -:R: pass:q,r[^(R)^] -Khronos{R} OpenCL Working Group - -== Name Strings - -`cl_ext_cxx_for_opencl` - -== Contact - -Please see the *Issues* list in the Khronos *OpenCL-Docs* repository: + -https://github.com/KhronosGroup/OpenCL-Docs - -== 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 + - -== Notice - -include::../copyrights.txt[] - -== Version - -Built On: {docdate} + -Version: 1.0.0 - -== Dependencies - -This extension is written against the OpenCL Specification -Version 3.0.3. - -This extension requires OpenCL 3.0 with OpenCL C 2.0 support or OpenCL 2.x and -`cl_khr_extended_versioning`. - -== Overview - -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 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*. - -== New API Enums - -Accepted value for the _param_name_ parameter to *clGetDeviceInfo*: - -[source,c] ----- -CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT 0x4230 ----- - -== 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". - - -== Modifications to the OpenCL API Specification - -(Modify Section 4.2, *Querying Devices*) :: -+ --- - -(Add the following to Table 4.3, _Device Queries_) :: -+ --- - -[cols="1,1,4",options="header"] -|==== -| cl_device_info -| Return Type -| Description - -| `CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT` -| `cl_version` -| Returns the version of the C++ for OpenCL language supported by the - device compiler. - -|==== - --- --- - -(Modify Section 5.8.1, *Creating Program Objects*) :: -+ --- -Add the following text to the description for *clCreateProgramWithSource*: - -The source code specified by _strings_ may also be a C++ for OpenCL program source -or header. --- - -(Modify section to 5.8.6, *Compiler Options*) :: -+ --- - -(Add subsection, *C++ for OpenCL*) :: -+ --- -Applications may pass `-cl-std=CLC\++` to *clCompileProgram* and *clBuildProgram* -for programs created using *clCreateProgramFromSource* to request the program -be built as C++ for OpenCL. --- - --- - -== 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`. - -== Issues - -None. - -== Version History - -[cols="5,15,15,70"] -[grid="rows"] -[options="header"] -|==== -| Version | Date | Author | Changes -| 1.0.0 | 2020-08-25 | Kevin Petit | *Initial revision* -|==== - diff --git a/extensions/extensions.txt b/extensions/extensions.txt index 1e1e9804..d28468b9 100644 --- a/extensions/extensions.txt +++ b/extensions/extensions.txt @@ -34,8 +34,6 @@ Khronos{R} OpenCL Working Group == Multi-Vendor Extensions :leveloffset: 2 <<< -include::cl_ext_cxx_for_opencl.asciidoc[] -<<< include::cl_ext_float_atomics.asciidoc[] <<< include::cl_ext_image_from_buffer.asciidoc[] diff --git a/makeSpec b/makeSpec index 4c3decf3..ac17ffb3 100755 --- a/makeSpec +++ b/makeSpec @@ -42,7 +42,7 @@ if __name__ == '__main__': default='gen', help='Path to directory containing generated files') parser.add_argument('-spec', action='store', - choices=[ 'core', 'khr', 'all' ], + choices=[ 'core', 'khr', 'khr+ext', 'all' ], default='core', help='Type of spec to generate') parser.add_argument('-registry', action='store', @@ -79,8 +79,8 @@ if __name__ == '__main__': # extension appendices yet. if results.spec == 'all': - results.spec = 'khr' - print("WARNING: 'all' argument to -results interpreted as 'khr' at present", file=sys.stderr) + results.spec = 'khr+ext' + print("WARNING: 'all' argument to -results interpreted as 'khr+ext' at present", file=sys.stderr) if results.spec == 'core': title = '' @@ -88,6 +88,9 @@ if __name__ == '__main__': elif results.spec == 'khr': title = 'with all KHR extensions' exts = set(deps.khrExtensions()) + elif results.spec == 'khr+ext': + title = 'with all KHR and EXT extensions' + exts = set(deps.khrAndextExtensions()) elif results.spec == 'all': title = 'with all registered extensions' exts = set(deps.allExtensions()) diff --git a/scripts/extdependency.py b/scripts/extdependency.py index 69dbec3c..59bfc838 100755 --- a/scripts/extdependency.py +++ b/scripts/extdependency.py @@ -106,6 +106,7 @@ def __init__(self, self.allExts = set() self.khrExts = set() + self.extExts = set() self.ratifiedExts = set() self.graph = DiGraph() self.extensions = {} @@ -133,6 +134,9 @@ def __init__(self, if conventions.KHR_prefix in name: self.khrExts.add(name) + if conventions.EXT_prefix in name: + self.extExts.add(name) + if api_name in ratified.split(','): self.ratifiedExts.add(name) @@ -159,6 +163,10 @@ def khrExtensions(self): """Returns a set of all KHR extensions in the graph""" return self.khrExts + def khrAndextExtensions(self): + """Returns a set of all KHR and EXT extensions in the graph""" + return self.khrExts | self.extExts + def ratifiedExtensions(self): """Returns a set of all ratified extensions in the graph""" return self.ratifiedExts diff --git a/xml/cl.xml b/xml/cl.xml index 53b9a9be..e0784300 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -5782,7 +5782,7 @@ server's OpenCL/api-docs repository. - + @@ -5826,7 +5826,7 @@ server's OpenCL/api-docs repository. - + @@ -6764,7 +6764,7 @@ server's OpenCL/api-docs repository. - + @@ -7248,7 +7248,7 @@ server's OpenCL/api-docs repository. - + @@ -7286,7 +7286,7 @@ server's OpenCL/api-docs repository. - + @@ -7377,7 +7377,7 @@ server's OpenCL/api-docs repository. - + @@ -7417,7 +7417,7 @@ server's OpenCL/api-docs repository. - +