Add definition of cl_icdl extension.

extensions/cl_loader_info.asciidoc

@@ -0,0 +1,164 @@
+// Copyright 2018-2023 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_loader_info
+:R: pass:q,r[^(R)^]
+Khronos{R} OpenCL Working Group
+
+== Name Strings
+
+`cl_loader_info`
+
+== Contact
+
+Please see the *Issues* list in the Khronos *OpenCL-Docs* repository: +
+https://github.com/KhronosGroup/OpenCL-Docs
+
+== Contributors
+
+// spell-checker: disable
+Vincent Danjean, Université Grenoble Alpes +
+Brice Videau, Argonne National Laboratory
+// spell-checker: enable
+
+== Notice
+
+Copyright (c) 2023 The Khronos Group Inc.
+
+== Status
+
+Final Draft
+
+== Version
+
+Built On: {docdate} +
+Version: 1.0.0
+
+== Dependencies
+
+This extension is written against the OpenCL Specification
+Version 1.0, Revision 1.
+
+This extension requires OpenCL 1.0.
+
+== Overview
+
+This extension describes the `cl_loader_info` loader extension which
+defines a simple mechanism through which an OpenCL installable client
+driver loader (ICD Loader) may report loader specific meta-data such
+as version or vendor.
+
+== New API Functions
+
+[source,c]
+----
+cl_int clGetICDLoaderInfoOCLICD(cl_icdl_info  param_name,
+                                size_t        param_value_size,
+                                void         *param_value,
+                                size_t       *param_value_size_ret);
+----
+
+== New API Types
+
+[source,c]
+----
+typedef cl_uint cl_icdl_info;
+----
+
+== New API Enums
+
+Accepted as _param_name_ to the function *clGetICDLoaderInfoOCLICD*:
+
+[source,c]
+----
+#define CL_ICDL_OCL_VERSION 1
+#define CL_ICDL_VERSION     2
+#define CL_ICDL_NAME        3
+#define CL_ICDL_VENDOR      4
+----
+
+Note that for backward compatibility reasons, the enum values do not
+follow OpenCL enum values attribution.
+
+== Modifications to the OpenCL API Specification
+
+[open,refpage='clGetICDLoaderInfoOCLICD',desc='Query information about an OpenCL ICD Loader',type='protos']
+Information concerning an OpenCL ICD Loader can be obtained with the function:
+[source,c]
+----
+cl_int clGetICDLoaderInfoOCLICD(cl_icdl_info  param_name,
+                                size_t        param_value_size,
+                                void         *param_value,
+                                size_t       *param_value_size_ret);
+----
+
+  * _param_name_ is an enumeration constant that identifies the ICD loader
+    information being queried. It can be one of the following values as
+    specified in the <<loader-queries-table, ICD Loader Queries>> table.
+  * _param_value_size_ specifies the size in bytes of memory pointed to by
+    _param_value_.
+    This size in bytes must be ≥ to the size of return type specified in the
+    <<loader-queries-table, ICD Loader Queries>> table.
+  * _param_value_ is a pointer to memory location where appropriate values for a
+    given _param_name_, as specified in the <<loader-queries-table, ICD Loader Queries
+    Queries>> table, will be returned.
+    If _param_value_ is `NULL`, it is ignored.
+  * _param_value_size_ret_ returns the actual size in bytes of data being
+    queried by _param_name_.
+    If _param_value_size_ret_ is `NULL`, it is ignored.
+
+The information that can be queried using *clGetICDLoaderInfoOCLICD* is specified
+in the <<loader-queries-table, ICD Loader Queries>> table.
+
+[[loader-queries-table]]
+.List of supported param_names by <<clGetICDLoaderInfoOCLICD>>
+[width="100%"]
+[cols="30,20,80"]
+[options="header"]
+|====
+| ICD Loader Info | Return Type | Description
+| *CL_ICDL_OCL_VERSION* | char[] | OpenCL version supported by the ICD Loader
+| *CL_ICDL_VERSION* | char[] | ICD Loader version string
+| *CL_ICDL_NAME* | char[] | ICD Loader name string
+| *CL_ICDL_VENDOR* | char[] | ICD Loader vendor string
+|====
+
+*clGetICDLoaderInfoOCLICD* returns *CL_SUCCESS* if the function is
+executed successfully.
+Otherwise, it returns one of the following errors.
+
+  * *CL_INVALID_VALUE* if _param_name_ is not one of the supported values or
+    if size in bytes specified by _param_value_size_ is < size of return
+    type as specified in the <<loader-queries-table, ICD Loader Queries>> table,
+    and _param_value_ is not a `NULL` value.
+
+
+== Conformance tests
+
+. The new *clGetICDLoaderInfoOCLICD* entrypoint must be called and succeed.
+. The value returned for `CL_ICDL_OCL_VERSION` must repect the OpenCL version
+  string format. 
+
+== Issues
+
+. Should this extension be a regular extension?
++
+--
+*RESOLVED*: Yes.  This is a userfacing extension.
+--
+
+== Version History
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|====
+| Version | Date       | Author       | Changes
+| 1.0.0   | 2023-03-01 | Brice Videau | *Initial revision*
+|====

xml/cl.xml

@@ -223,6 +223,7 @@ server's OpenCL/api-docs repository.
         <type category="define">typedef <type>cl_bitfield</type>      <name>cl_mem_alloc_flags_img</name>;</type>
         <type category="define">typedef <type>cl_uint</type>          <name>cl_layer_info</name>;</type>
         <type category="define">typedef <type>cl_uint</type>          <name>cl_layer_api_version</name>;</type>
+        <type category="define">typedef <type>cl_uint</type>          <name>cl_icdl_info</name>;</type>
         <type category="define">typedef struct _cl_icd_dispatch       <name>cl_icd_dispatch</name>;</type>
         <type category="define">typedef <type>cl_bitfield</type>      <name>cl_device_scheduling_controls_capabilities_arm</name>;</type>
         <type category="define">typedef <type>cl_bitfield</type>      <name>cl_device_controlled_termination_capabilities_arm</name>;</type>
@@ -2212,6 +2213,13 @@ server's OpenCL/api-docs repository.
             <unused start="0x4242" end="0x424F"/>
     </enums>
 
+    <enums name="cl_icdl_info" comment="OpenCL ICD Loader info queries.">
+        <enum value="1"             name="CL_ICDL_OCL_VERSION"/>
+        <enum value="2"             name="CL_ICDL_VERSION"/>
+        <enum value="3"             name="CL_ICDL_NAME"/>
+        <enum value="4"             name="CL_ICDL_VENDOR"/>
+    </enums>
+
     <enums start="0x4250" end="0x425F" name="enums.4250" vendor="Intel">
         <enum value="0x4250"        name="CL_DEVICE_IP_VERSION_INTEL"/>
         <enum value="0x4251"        name="CL_DEVICE_ID_INTEL"/>
@@ -4115,6 +4123,13 @@ server's OpenCL/api-docs repository.
             <param><type>cl_uint</type>*                                <name>num_entries_ret</name></param>
             <param>const <type>cl_icd_dispatch</type>**                 <name>layer_dispatch</name></param>
         </command>
+        <command>
+            <proto><type>cl_int</type>                                  <name>clGetICDLoaderInfoOCLICD</name></proto>
+            <param><type>cl_icdl_info</type>                            <name>param_name</name></param>
+            <param><type>size_t</type>                                  <name>param_value_size</name></param>
+            <param><type>void</type>*                                   <name>param_value</name></param>
+            <param><type>size_t</type>*                                 <name>param_value_size_ret</name></param>
+        </command>
         <command>
             <proto><type>cl_int</type>              <name>clGetSupportedGLTextureFormatsINTEL</name></proto>
             <param><type>cl_context</type>          <name>context</name></param>
@@ -5501,6 +5516,23 @@ server's OpenCL/api-docs repository.
                 <command name="clInitLayer"/>
             </require>
         </extension>
+        <extension name="cl_loader_info" supported="opencl">
+            <require>
+                <type name="CL/cl.h"/>
+            </require>
+            <require>
+                <type name="cl_icdl_info"/>
+            </require>
+            <require comment="cl_icdl_info">
+                <enum name="CL_ICDL_OCL_VERSION"/>
+                <enum name="CL_ICDL_VERSION"/>
+                <enum name="CL_ICDL_NAME"/>
+                <enum name="CL_ICDL_VENDOR"/>
+            </require>
+            <require>
+                <command name="clGetICDLoaderInfoOCLICD"/>
+            </require>
+        </extension>
         <extension name="cl_khr_il_program" supported="opencl">
             <require>
                 <type name="CL/cl.h"/>