publish cl_khr_spirv_queries (#1385)

* initial extension draft for cl_khr_spirv_queries

* clarify that all returned strings are const and should not be modified
move the meaning of the queries to the SPIR-V environment spec

* update the XML file to record that the extension is ratified

Author: bashbaug

api/cl_khr_spirv_queries.asciidoc

@@ -0,0 +1,29 @@
+// Copyright 2025 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}cl_khr_spirv_queries.txt[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2025-06-04
+*IP Status*::
+    No known IP claims.
+
+=== Description
+
+{cl_khr_spirv_queries_EXT} adds queries to determine the SPIR-V extended
+instruction sets, SPIR-V extensions, and SPIR-V capabilities that are supported
+by an OpenCL device.
+
+=== New Enums
+
+  * {cl_device_info_TYPE}
+  ** {CL_DEVICE_SPIRV_EXTENDED_INSTRUCTION_SETS_KHR}
+  ** {CL_DEVICE_SPIRV_EXTENSIONS_KHR}
+  ** {CL_DEVICE_SPIRV_CAPABILITIES_KHR}
+
+=== Version History
+
+  * Revision 1.0.0, 2025-06-04
+  ** Initial version.

api/opencl_platform_layer.asciidoc

@@ -738,6 +738,30 @@ ifdef::cl_khr_extended_versioning[or {cl_name_version_khr_TYPE}[]]
         For an OpenCL 2.1 or 2.2 device, at least one version of SPIR-V must
         be reported.
 
+ifdef::cl_khr_spirv_queries[]
+| {CL_DEVICE_SPIRV_EXTENDED_INSTRUCTION_SETS_KHR_anchor}
+
+include::{generated}/api/version-notes/CL_DEVICE_SPIRV_EXTENDED_INSTRUCTION_SETS_KHR.asciidoc[]
+  | const {char_TYPE}*[]
+      | Returns an array of null-terminated strings, where each string describes
+        a SPIR-V extended instruction set that is supported by the device.
+
+| {CL_DEVICE_SPIRV_EXTENSIONS_KHR_anchor}
+
+include::{generated}/api/version-notes/CL_DEVICE_SPIRV_EXTENSIONS_KHR.asciidoc[]
+  | const {char_TYPE}*[]
+      | Returns an array of null-terminated strings, where each string describes
+        a SPIR-V extension that is supported by the device.
+
+| {CL_DEVICE_SPIRV_CAPABILITIES_KHR_anchor}
+
+include::{generated}/api/version-notes/CL_DEVICE_SPIRV_CAPABILITIES_KHR.asciidoc[]
+  | {cl_uint_TYPE}[]
+      | Returns an array of SPIR-V token values, where each value describes a
+        SPIR-V capability that is supported by the device.
+
+endif::cl_khr_spirv_queries[]
+
 | {CL_DEVICE_IMAGE2D_MAX_WIDTH_anchor}
 
 include::{generated}/api/version-notes/CL_DEVICE_IMAGE2D_MAX_WIDTH.asciidoc[]

env/extensions.asciidoc

@@ -403,6 +403,15 @@ For the *OpReadClockKHR* instruction requiring this capability, supported values
 
 For unsupported _Scope_ values, the behavior of *OpReadClockKHR* is undefined.
 
+==== `cl_khr_spirv_queries`
+
+If the OpenCL environment supports the extension `cl_khr_spirv_queries`, then:
+
+* For each of the strings returned by the query `CL_DEVICE_SPIRV_EXTENDED_INSTRUCTION_SETS_KHR`, it is valid to import the SPIR-V extended instruction set in a SPIR-V module using *OpExtInstImport*.
+* For each of the strings returned by the query `CL_DEVICE_SPIRV_EXTENSIONS_KHR`, it is valid to declare use of the SPIR-V extension in a SPIR-V module using *OpExtension*.
+* For each of the capabilities returned by the query `CL_DEVICE_SPIRV_CAPABILITIES_KHR`, it is valid to declare the SPIR-V capability in a SPIR-V module using *OpCapability*.
+Some capabilities may additionally require a specific SPIR-V version, or a SPIR-V extension to be declared via *OpExtension*.
+
 === Embedded Profile Extensions
 
 ==== `cles_khr_int64`

xml/cl.xml

@@ -1823,7 +1823,10 @@ server's OpenCL/api-docs repository.
         <enum value="0x12B6"        name="CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT"/>
         <enum value="0x12B7"        name="CL_COMMAND_BUFFER_MUTABLE_DISPATCH_ASSERTS_KHR"/>
         <enum value="0x12B8"        name="CL_MUTABLE_DISPATCH_ASSERTS_KHR"/>
-            <unused start="0x12B9" end="0x1FFF" comment="Reserved for core API tokens"/>
+        <enum value="0x12B9"        name="CL_DEVICE_SPIRV_EXTENDED_INSTRUCTION_SETS_KHR"/>
+        <enum value="0x12BA"        name="CL_DEVICE_SPIRV_EXTENSIONS_KHR"/>
+        <enum value="0x12BB"        name="CL_DEVICE_SPIRV_CAPABILITIES_KHR"/>
+            <unused start="0x12BC" end="0x1FFF" comment="Reserved for core API tokens"/>
     </enums>
 
     <enums start="0x2000" end="0x201F" name="enums.2000" vendor="Khronos" comment="Reserved for interop with other APIs">
@@ -7614,5 +7617,15 @@ server's OpenCL/api-docs repository.
                 <enum name="CL_UNORM_INT14X2_EXT"/>
             </require>
         </extension>
+        <extension name="cl_khr_spirv_queries" revision="1.0.0" supported="opencl" ratified="opencl">
+            <require>
+                <type name="CL/cl.h"/>
+            </require>
+            <require comment="cl_device_info">
+                <enum name="CL_DEVICE_SPIRV_EXTENDED_INSTRUCTION_SETS_KHR"/>
+                <enum name="CL_DEVICE_SPIRV_EXTENSIONS_KHR"/>
+                <enum name="CL_DEVICE_SPIRV_CAPABILITIES_KHR"/>
+            </require>
+        </extension>
     </extensions>
 </registry>