Skip to content

Commit d1aaa33

Browse files
KerilkKerilk
authored
Add definition of cl_icdl extension. (#886)
* Add definition of cl_icdl extension. * Fix typo. * Updated extension proposal to be a regular extension. * Removed comment leftover comment section. * Adjust table for better rendering in html.
1 parent 84054c2 commit d1aaa33

2 files changed

Lines changed: 196 additions & 0 deletions

File tree

‎extensions/cl_loader_info.asciidoc‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
// Copyright 2018-2023 The Khronos Group. This work is licensed under a
2+
// Creative Commons Attribution 4.0 International License; see
3+
// http://creativecommons.org/licenses/by/4.0/
4+
5+
:data-uri:
6+
:icons: font
7+
include::../config/attribs.txt[]
8+
:source-highlighter: coderay
9+
10+
= cl_loader_info
11+
:R: pass:q,r[^(R)^]
12+
Khronos{R} OpenCL Working Group
13+
14+
== Name Strings
15+
16+
`cl_loader_info`
17+
18+
== Contact
19+
20+
Please see the *Issues* list in the Khronos *OpenCL-Docs* repository: +
21+
https://github.com/KhronosGroup/OpenCL-Docs
22+
23+
== Contributors
24+
25+
// spell-checker: disable
26+
Vincent Danjean, Université Grenoble Alpes +
27+
Brice Videau, Argonne National Laboratory
28+
// spell-checker: enable
29+
30+
== Notice
31+
32+
Copyright (c) 2023 The Khronos Group Inc.
33+
34+
== Status
35+
36+
Final Draft
37+
38+
== Version
39+
40+
Built On: {docdate} +
41+
Version: 1.0.0
42+
43+
== Dependencies
44+
45+
This extension is written against the OpenCL Specification
46+
Version 1.0, Revision 1.
47+
48+
This extension requires OpenCL 1.0.
49+
50+
== Overview
51+
52+
This extension describes the `cl_loader_info` loader extension which
53+
defines a simple mechanism through which an OpenCL installable client
54+
driver loader (ICD Loader) may report loader specific meta-data such
55+
as version or vendor.
56+
57+
== New API Functions
58+
59+
[source,c]
60+
----
61+
cl_int clGetICDLoaderInfoOCLICD(cl_icdl_info param_name,
62+
size_t param_value_size,
63+
void *param_value,
64+
size_t *param_value_size_ret);
65+
----
66+
67+
== New API Types
68+
69+
[source,c]
70+
----
71+
typedef cl_uint cl_icdl_info;
72+
----
73+
74+
== New API Enums
75+
76+
Accepted as _param_name_ to the function *clGetICDLoaderInfoOCLICD*:
77+
78+
[source,c]
79+
----
80+
#define CL_ICDL_OCL_VERSION 1
81+
#define CL_ICDL_VERSION 2
82+
#define CL_ICDL_NAME 3
83+
#define CL_ICDL_VENDOR 4
84+
----
85+
86+
Note that for backward compatibility reasons, the enum values do not
87+
follow OpenCL enum values attribution.
88+
89+
== Modifications to the OpenCL API Specification
90+
91+
[open,refpage='clGetICDLoaderInfoOCLICD',desc='Query information about an OpenCL ICD Loader',type='protos']
92+
Information concerning an OpenCL ICD Loader can be obtained with the function:
93+
[source,c]
94+
----
95+
cl_int clGetICDLoaderInfoOCLICD(cl_icdl_info param_name,
96+
size_t param_value_size,
97+
void *param_value,
98+
size_t *param_value_size_ret);
99+
----
100+
101+
* _param_name_ is an enumeration constant that identifies the ICD loader
102+
information being queried. It can be one of the following values as
103+
specified in the <<loader-queries-table, ICD Loader Queries>> table.
104+
* _param_value_size_ specifies the size in bytes of memory pointed to by
105+
_param_value_.
106+
This size in bytes must be ≥ to the size of return type specified in the
107+
<<loader-queries-table, ICD Loader Queries>> table.
108+
* _param_value_ is a pointer to memory location where appropriate values for a
109+
given _param_name_, as specified in the <<loader-queries-table, ICD Loader Queries
110+
Queries>> table, will be returned.
111+
If _param_value_ is `NULL`, it is ignored.
112+
* _param_value_size_ret_ returns the actual size in bytes of data being
113+
queried by _param_name_.
114+
If _param_value_size_ret_ is `NULL`, it is ignored.
115+
116+
The information that can be queried using *clGetICDLoaderInfoOCLICD* is specified
117+
in the <<loader-queries-table, ICD Loader Queries>> table.
118+
119+
[[loader-queries-table]]
120+
.List of supported param_names by <<clGetICDLoaderInfoOCLICD>>
121+
[width="100%"]
122+
[cols="30,20,80"]
123+
[options="header"]
124+
|====
125+
| ICD Loader Info | Return Type | Description
126+
| *CL_ICDL_OCL_VERSION* | char[] | OpenCL version supported by the ICD Loader
127+
| *CL_ICDL_VERSION* | char[] | ICD Loader version string
128+
| *CL_ICDL_NAME* | char[] | ICD Loader name string
129+
| *CL_ICDL_VENDOR* | char[] | ICD Loader vendor string
130+
|====
131+
132+
*clGetICDLoaderInfoOCLICD* returns *CL_SUCCESS* if the function is
133+
executed successfully.
134+
Otherwise, it returns one of the following errors.
135+
136+
* *CL_INVALID_VALUE* if _param_name_ is not one of the supported values or
137+
if size in bytes specified by _param_value_size_ is < size of return
138+
type as specified in the <<loader-queries-table, ICD Loader Queries>> table,
139+
and _param_value_ is not a `NULL` value.
140+
141+
142+
== Conformance tests
143+
144+
. The new *clGetICDLoaderInfoOCLICD* entrypoint must be called and succeed.
145+
. The value returned for `CL_ICDL_OCL_VERSION` must repect the OpenCL version
146+
string format.
147+
148+
== Issues
149+
150+
. Should this extension be a regular extension?
151+
+
152+
--
153+
*RESOLVED*: Yes. This is a userfacing extension.
154+
--
155+
156+
== Version History
157+
158+
[cols="5,15,15,70"]
159+
[grid="rows"]
160+
[options="header"]
161+
|====
162+
| Version | Date | Author | Changes
163+
| 1.0.0 | 2023-03-01 | Brice Videau | *Initial revision*
164+
|====

‎xml/cl.xml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,7 @@ server's OpenCL/api-docs repository.
223223
<type category="define">typedef <type>cl_bitfield</type> <name>cl_mem_alloc_flags_img</name>;</type>
224224
<type category="define">typedef <type>cl_uint</type> <name>cl_layer_info</name>;</type>
225225
<type category="define">typedef <type>cl_uint</type> <name>cl_layer_api_version</name>;</type>
226+
<type category="define">typedef <type>cl_uint</type> <name>cl_icdl_info</name>;</type>
226227
<type category="define">typedef struct _cl_icd_dispatch <name>cl_icd_dispatch</name>;</type>
227228
<type category="define">typedef <type>cl_bitfield</type> <name>cl_device_scheduling_controls_capabilities_arm</name>;</type>
228229
<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.
22122213
<unused start="0x4242" end="0x424F"/>
22132214
</enums>
22142215

2216+
<enums name="cl_icdl_info" comment="OpenCL ICD Loader info queries.">
2217+
<enum value="1" name="CL_ICDL_OCL_VERSION"/>
2218+
<enum value="2" name="CL_ICDL_VERSION"/>
2219+
<enum value="3" name="CL_ICDL_NAME"/>
2220+
<enum value="4" name="CL_ICDL_VENDOR"/>
2221+
</enums>
2222+
22152223
<enums start="0x4250" end="0x425F" name="enums.4250" vendor="Intel">
22162224
<enum value="0x4250" name="CL_DEVICE_IP_VERSION_INTEL"/>
22172225
<enum value="0x4251" name="CL_DEVICE_ID_INTEL"/>
@@ -4115,6 +4123,13 @@ server's OpenCL/api-docs repository.
41154123
<param><type>cl_uint</type>* <name>num_entries_ret</name></param>
41164124
<param>const <type>cl_icd_dispatch</type>** <name>layer_dispatch_ret</name></param>
41174125
</command>
4126+
<command>
4127+
<proto><type>cl_int</type> <name>clGetICDLoaderInfoOCLICD</name></proto>
4128+
<param><type>cl_icdl_info</type> <name>param_name</name></param>
4129+
<param><type>size_t</type> <name>param_value_size</name></param>
4130+
<param><type>void</type>* <name>param_value</name></param>
4131+
<param><type>size_t</type>* <name>param_value_size_ret</name></param>
4132+
</command>
41184133
<command>
41194134
<proto><type>cl_int</type> <name>clGetSupportedGLTextureFormatsINTEL</name></proto>
41204135
<param><type>cl_context</type> <name>context</name></param>
@@ -5501,6 +5516,23 @@ server's OpenCL/api-docs repository.
55015516
<command name="clInitLayer"/>
55025517
</require>
55035518
</extension>
5519+
<extension name="cl_loader_info" supported="opencl">
5520+
<require>
5521+
<type name="CL/cl.h"/>
5522+
</require>
5523+
<require>
5524+
<type name="cl_icdl_info"/>
5525+
</require>
5526+
<require comment="cl_icdl_info">
5527+
<enum name="CL_ICDL_OCL_VERSION"/>
5528+
<enum name="CL_ICDL_VERSION"/>
5529+
<enum name="CL_ICDL_NAME"/>
5530+
<enum name="CL_ICDL_VENDOR"/>
5531+
</require>
5532+
<require>
5533+
<command name="clGetICDLoaderInfoOCLICD"/>
5534+
</require>
5535+
</extension>
55045536
<extension name="cl_khr_il_program" supported="opencl">
55055537
<require>
55065538
<type name="CL/cl.h"/>

0 commit comments

Comments
 (0)