Merge branch 'main' into error-code-consistency

bashbaug · bashbaug · commit 999a1e0b2dd2 · 2025-10-19T15:21:59.000-07:00
diff --git a/.github/workflows/presubmit.yml b/.github/workflows/presubmit.yml
@@ -20,7 +20,7 @@ jobs:
     container: khronosgroup/docker-images@sha256:4aab96a03ef292439c9bd0f972adfa29cdf838d0909b1cb4ec2a6d7b2d14a37f
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           submodules: recursive
           # If fetch-depth: 0 is not specified, then
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -22,7 +22,7 @@ jobs:
   
     steps:
       - name: Get Spec Source
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@ff7abcd0c3c05ccf6adc123a8cd1fd4fb30fb493 # v4.2.2
         with:
           submodules: recursive
           # If fetch-depth: 0 is not specified, then
@@ -46,7 +46,7 @@ jobs:
             python3 makeSpec -clean -spec khr+ext OUTDIR=out.release -j 5 api c env ext cxx4opencl
 
       - name: Release Specs
-        uses: softprops/action-gh-release@72f2c25fcb47643c292f7107632f7a47c1df5cd8 # v2.3.2
+        uses: softprops/action-gh-release@6cbd405e2c4e67a21c47fa9e383d020e4e28b836 # v2.3.3
         with:
             draft: true
             files: |
diff --git a/Makefile b/Makefile
@@ -517,6 +517,7 @@ CFEATURES      = c/features.txt
 CFUNCTIONS     = c/functions.txt
 GENSCRIPT      = $(SCRIPTS)/gencl.py
 DICTSCRIPT     = $(SCRIPTS)/gen_dictionaries.py
+EXTIFACESSCRIPT= $(SCRIPTS)/gen_extension_interfaces.py
 VERSIONSCRIPT  = $(SCRIPTS)/gen_version_notes.py
 CFEATSCRIPT    = $(SCRIPTS)/gen_dictionary_from_file.py
 CFUNCSCRIPT    = $(SCRIPTS)/gen_dictionary_from_file.py
@@ -542,11 +543,13 @@ $(APIDEPEND): $(APIXML) $(DICTSCRIPT) $(GENSCRIPT) $(VERSIONSCRIPT)
 
 extinc: $(METADEPEND)
 
-$(METADEPEND): $(APIXML) $(GENSCRIPT)
+$(METADEPEND): $(APIXML) $(GENSCRIPT) $(CFEATSCRIPT) $(EXTIFACESSCRIPT)
 	$(QUIET)$(MKDIR) $(METAPATH)
+	$(QUIET)$(MKDIR) $(METAPATH)/interfaces
 	$(QUIET)$(PYTHON) $(GENSCRIPT) $(GENSCRIPTOPTS) -o $(METAPATH) extinc
 	$(QUIET)$(PYTHON) $(CFEATSCRIPT) -i $(CFEATURES) -o $(METAPATH)/c-feature-dictionary.asciidoc
 	$(QUIET)$(PYTHON) $(CFUNCSCRIPT) -i $(CFUNCTIONS) -o $(METAPATH)/c-function-dictionary.asciidoc
+	$(QUIET)$(PYTHON) $(EXTIFACESSCRIPT) -registry $(APIXML) -o $(METAPATH)/interfaces
 
 # This generates a single file containing asciidoc attributes for each
 # extension in the spec being built.
diff --git a/api/cl_ext_buffer_device_address.asciidoc b/api/cl_ext_buffer_device_address.asciidoc
@@ -44,22 +44,7 @@ This extension is targeted to complement the OpenCL SVM extension by providing
 an additional lower-end step in the spectrum of type of pointers/buffers OpenCL
 can allocate.
 
-=== New Command
-
-  * {clSetKernelArgDevicePointerEXT}
-
-=== New Types
-
-  * {cl_mem_device_address_ext_TYPE}
-
-=== New Enums
-
-  * {cl_mem_properties_TYPE}
-  ** {CL_MEM_DEVICE_PRIVATE_ADDRESS_EXT}
-  * {cl_mem_info_TYPE}
-  ** {CL_MEM_DEVICE_ADDRESS_EXT}
-  * {cl_kernel_exec_info_TYPE}
-  ** {CL_KERNEL_EXEC_INFO_DEVICE_PTRS_EXT}
+include::{generated}/meta/interfaces/cl_ext_buffer_device_address.txt[]
 
 === Version History
 
diff --git a/api/cl_ext_cxx_for_opencl.asciidoc b/api/cl_ext_cxx_for_opencl.asciidoc
@@ -27,10 +27,7 @@ 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}
+include::{generated}/meta/interfaces/cl_ext_cxx_for_opencl.txt[]
 
 === New build option
 
diff --git a/api/cl_ext_image_from_buffer.asciidoc b/api/cl_ext_image_from_buffer.asciidoc
@@ -20,10 +20,7 @@ include::{generated}/meta/{refprefix}cl_ext_image_from_buffer.txt[]
 This extension enables all types of images to be created from an existing buffer
 object.
 
-=== New Enums
-
-  * {cl_image_requirements_info_ext_TYPE}
-  ** {CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT}
+include::{generated}/meta/interfaces/cl_ext_image_from_buffer.txt[]
 
 === Conformance tests
 
diff --git a/api/cl_ext_image_raw10_raw12.asciidoc b/api/cl_ext_image_raw10_raw12.asciidoc
@@ -15,6 +15,8 @@ include::{generated}/meta/{refprefix}cl_ext_image_raw10_raw12.txt[]
 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].
 
+include::{generated}/meta/interfaces/cl_ext_image_raw10_raw12.txt[]
+
 === Version History
 
   * Revision 1.0.0, 2023-05-03
diff --git a/api/cl_ext_image_requirements_info.asciidoc b/api/cl_ext_image_requirements_info.asciidoc
@@ -22,24 +22,7 @@ include::{generated}/meta/{refprefix}cl_ext_image_requirements_info.txt[]
 This extension enables applications to query requirements for an image without
 having to create the image.
 
-=== New Commands
-
-  * {clGetImageRequirementsInfoEXT}
-
-=== New Types
-
-  * {cl_image_requirements_info_ext_TYPE}
-
-=== New Enums
-
-  * {cl_image_requirements_info_ext_TYPE}
-  ** {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT}
-  ** {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT}
-  ** {CL_IMAGE_REQUIREMENTS_SIZE_EXT}
-  ** {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT}
-  ** {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT}
-  ** {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT}
-  ** {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT}
+include::{generated}/meta/interfaces/cl_ext_image_requirements_info.txt[]
 
 === Conformance tests
 
diff --git a/api/cl_ext_image_unorm_int_2_101010.asciidoc b/api/cl_ext_image_unorm_int_2_101010.asciidoc
@@ -20,15 +20,12 @@ image format.
 OpenCL C compilers supporting this extension will define the
 {opencl_c_ext_image_unorm_int_2_101010} feature macro.
 
+include::{generated}/meta/interfaces/cl_ext_image_unorm_int_2_101010.txt[]
+
 === New feature macro
 
   * {opencl_c_ext_image_unorm_int_2_101010}
 
-=== New Enums
-
-  * {cl_channel_type_TYPE}
-  ** {CL_UNORM_INT_2_101010_EXT}
-
 === New OpenCL C channel data type
 
   * `CLK_UNORM_INT_2_101010_EXT`
diff --git a/api/cl_ext_image_unsigned_10x6_12x4_14x2.asciidoc b/api/cl_ext_image_unsigned_10x6_12x4_14x2.asciidoc
@@ -27,20 +27,12 @@ formats:
 OpenCL C compilers supporting this extension will define the
 {opencl_c_ext_image_unsigned_10x6_12x4_14x2} feature macro.
 
+include::{generated}/meta/interfaces/cl_ext_image_unsigned_10x6_12x4_14x2.txt[]
+
 === New feature macro
 
   * {opencl_c_ext_image_unsigned_10x6_12x4_14x2}
 
-=== New Enums
-
-  * {cl_channel_type_TYPE}
-  ** {CL_UNSIGNED_INT10X6_EXT}
-  ** {CL_UNSIGNED_INT12X4_EXT}
-  ** {CL_UNSIGNED_INT14X2_EXT}
-  ** {CL_UNORM_INT10X6_EXT}
-  ** {CL_UNORM_INT12X4_EXT}
-  ** {CL_UNORM_INT14X2_EXT}
-
 === New OpenCL C channel data type
 
   * `CLK_UNSIGNED_INT10X6_EXT`
diff --git a/api/cl_ext_immutable_memory_objects.asciidoc b/api/cl_ext_immutable_memory_objects.asciidoc
@@ -23,10 +23,7 @@ objects that cannot be modified by the implementation after creation. This,
 for example, enables implementation to support image formats for which no write
 operations can be supported.
 
-=== New Enums
-
-  * {cl_mem_flags_TYPE}
-  ** {CL_MEM_IMMUTABLE_EXT}
+include::{generated}/meta/interfaces/cl_ext_immutable_memory_objects.txt[]
 
 === Issues
 
diff --git a/api/cl_khr_icd.asciidoc b/api/cl_khr_icd.asciidoc
@@ -69,7 +69,7 @@ can be appended.
 Functions which do not have an argument from which the vendor implementation
 may be inferred have been deprecated and may be ignored.
 
-New in version 2.0.0, object that are ICD 2 compatible should also contain
+New in version 2.0.0, objects that are ICD 2 compatible should also contain
 a `dispatch_data` field of type `void *` that the loader is free to modify
 for a platform through the {clIcdSetPlatformDispatchDataKHR} new API entry
 point. In order to distinguish ICD 1 and ICD 2 objects, the pointers to
@@ -246,7 +246,7 @@ pointers to {clGetPlatformIDs} and {clUnloadCompiler} in the dispatch
 structure of a platform is set to `CL_ICD2_TAG_KHR` the platform will be
 deemed ICD 2 compatible and dispatch will be managed by the ICD Loader. If the
 `CL_ICD2_TAG_KHR` tag is present but one of the two functions above is
-missing or it the tag is present in only one of the pointers, the ICD Loader
+missing or if the tag is present in only one of the pointers, the ICD Loader
 will ignore the Vendor ICD and continue on to the next.
 
 During initialization, after calling {clIcdGetPlatformIDsKHR} to query the
diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc
@@ -2330,7 +2330,7 @@ endif::cl_khr_external_memory[]
     ** if there are no devices in _context_ that support _image_format_
 ifdef::cl_khr_external_memory_android_hardware_buffer[]
     ** if _properties_ includes an AHardwareBuffer external memory handle and
-    the AHardwareBuffer format is not supported
+    the AHardwareBuffer format is `AHARDWAREBUFFER_FORMAT_BLOB` or not supported
 endif::cl_khr_external_memory_android_hardware_buffer[]
   * {CL_MEM_OBJECT_ALLOCATION_FAILURE}
     ** if there is a failure to allocate memory for the image object
@@ -11319,20 +11319,18 @@ successfully.
 Otherwise, it returns one of the following errors:
 
   * {CL_INVALID_KERNEL} if _kernel_ is a not a valid kernel object.
-  * {CL_INVALID_OPERATION} for {CL_KERNEL_EXEC_INFO_SVM_PTRS} and
-     {CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM} if no devices in
-     the context associated with _kernel_ support SVM.
-ifdef::cl_ext_buffer_device_address[]
-  * {CL_INVALID_OPERATION} for {CL_KERNEL_EXEC_INFO_DEVICE_PTRS_EXT} if no
-  device in the context associated with _kernel_ support the {cl_ext_buffer_device_address_EXT}
-  extension.
-endif::cl_ext_buffer_device_address[]
-  * {CL_INVALID_VALUE} if _param_name_ is not valid, if _param_value_ is
-    `NULL` or if the size specified by _param_value_size_ is not valid.
+  * {CL_INVALID_OPERATION} if _param_name is {CL_KERNEL_EXEC_INFO_SVM_PTRS} and
+    no devices in the context associated with _kernel_ support SVM.
   * {CL_INVALID_OPERATION} if _param_name_ is
     {CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM} and _param_value_ is {CL_TRUE}
     and no devices in the context associated with _kernel_ support fine-grain
     system SVM allocations.
+ifdef::cl_ext_buffer_device_address[]
+  * {CL_INVALID_OPERATION} if _param_name_ is
+    {CL_KERNEL_EXEC_INFO_DEVICE_PTRS_EXT} and no devices in the context
+    associated with _kernel_ support the {cl_ext_buffer_device_address_EXT}
+    extension.
+endif::cl_ext_buffer_device_address[]
   * {CL_INVALID_VALUE} if _param_name_ is not valid, if _param_value_ is
     `NULL` and _param_value_size_ is greater than zero, or if the size specified
     by _param_value_size_ is not valid.
@@ -15169,20 +15167,15 @@ include::{generated}/api/version-notes/clEnqueueCommandBufferKHR.asciidoc[]
     application to wait on this command or query it for profiling
     information.
 
-[NOTE]
-====
-To enqueue a command-buffer it must be in a <<executable, Executable>> state,
-see {clFinalizeCommandBufferKHR}.
-====
-
 // refError
 
 {clEnqueueCommandBufferKHR} returns {CL_SUCCESS} if the command-buffer
 execution was successfully queued, or one of the errors below:
 
   * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid
     command-buffer.
-  * {CL_INVALID_OPERATION} if _command_buffer_ has not been finalized.
+  * {CL_INVALID_OPERATION} if _command_buffer_ is not in the
+    <<executable, Executable>> state.
   * {CL_INVALID_VALUE} if _queues_ is `NULL` and _num_queues_ is > 0, or
     _queues_ is not `NULL` and _num_queues_ is 0.
   * {CL_INVALID_VALUE} if _num_queues_ is > 0 and not the same value as
diff --git a/scripts/gen_extension_interfaces.py b/scripts/gen_extension_interfaces.py
@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+
+# Copyright 2025 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+import argparse
+import os
+import urllib
+import xml.etree.ElementTree as etree
+import urllib.request
+
+def parse_xml(path):
+    file = urllib.request.urlopen(path) if path.startswith("http") else open(path, 'r')
+    with file:
+        tree = etree.parse(file)
+        return tree
+
+def GetHeader():
+    return """// Copyright 2025 The Khronos Group.
+// SPDX-License-Identifier: CC-BY-4.0
+
+"""
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument('-registry', action='store',
+                        default='cl.xml',
+                        help='Use specified registry file instead of cl.xml')
+    parser.add_argument('-o', action='store', dest='directory',
+                        default='.',
+                        help='Create target and related files in specified directory')
+
+    args = parser.parse_args()
+
+    specpath = args.registry
+
+    print('Generating extension interfaces from: ' + specpath)
+
+    spec = parse_xml(specpath)
+
+    for extension in spec.findall('extensions/extension'):
+        extname = extension.get('name')
+        #print(extname)
+        iface_file = open(os.path.join(args.directory, extname + '.txt'), 'w')
+
+        iface_file.write(GetHeader())
+
+        # New commands
+        commands = extension.findall('require/command')
+        if commands:
+            iface_file.write('=== New Commands\n\n')
+            for cmd in commands:
+                iface_file.write('  * {{{}}}\n'.format(cmd.get('name')))
+            iface_file.write('\n')
+
+        # New types
+        types = extension.findall('require/type')
+        if types:
+            iface_file.write('=== New Types\n\n')
+            for ty in types:
+                iface_file.write('  * {{{}_TYPE}}\n'.format(ty.get('name')))
+
+        # New enums
+        first_enum = True
+        requires = extension.findall('require')
+        for req in requires:
+            enums = req.findall('enum')
+            first_for_require = True
+            for e in enums:
+                if first_enum:
+                    iface_file.write('=== New enums\n\n')
+                    first_enum = False
+                if first_for_require:
+                    comment = req.get('comment')
+                    if comment == 'Error codes':
+                        iface_file.write('  * New Error Codes\n')
+                    else:
+                        iface_file.write('  * {{{}_TYPE}}\n'.format(comment))
+                    first_for_require = False
+                iface_file.write('  ** {{{}}}\n'.format(e.get('name')))
+            iface_file.write('\n')
+
+        iface_file.close()
