Skip to content

Commit 86fe52c

Browse files
ivvenevtivvenevt
authored
Spec source and XML changes for the cl_intel_kernel_allocations_info extension (KhronosGroup#1522)
* Spec source and XML changes for the cl_intel_kernel_allocations_info extension Signed-off-by: Igor Venevtsev <igor.venevtsev@intel.com> * Spec source and XML changes for the cl_intel_kernel_allocations_info extension Signed-off-by: Igor Venevtsev <igor.venevtsev@intel.com> * Spec source and XML changes for the cl_intel_kernel_allocations_info extension Signed-off-by: Igor Venevtsev <igor.venevtsev@intel.com> --------- Signed-off-by: Igor Venevtsev <igor.venevtsev@intel.com>
1 parent b1cf656 commit 86fe52c

3 files changed

Lines changed: 211 additions & 1 deletion

File tree

‎extensions/cl_intel_kernel_allocations_info.asciidoc‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
= cl_intel_kernel_allocations_info
2+
3+
// This section needs to be after the document title.
4+
:doctype: book
5+
:toc2:
6+
:toc: left
7+
:encoding: utf-8
8+
:lang: en
9+
10+
:blank: pass:[ +]
11+
12+
// Set the default source code type in this document to C++,
13+
// for syntax highlighting purposes. This is needed because
14+
// docbook uses c++ and html5 uses cpp.
15+
:language: {basebackend@docbook:c++:cpp}
16+
17+
== Name Strings
18+
19+
`cl_intel_kernel_allocations_info`
20+
21+
== Contact
22+
23+
Igor Venevtsev, Intel (igor 'dot' venevtsev 'at' intel 'dot' com)
24+
25+
== Contributors
26+
27+
// spell-checker: disable
28+
Ben Ashbaugh, Intel +
29+
Igor Venevtsev, Intel +
30+
// spell-checker: enable
31+
32+
== Notice
33+
34+
Copyright (c) 2026 Intel Corporation. All rights reserved.
35+
36+
== Status
37+
38+
Shipping
39+
40+
== Version
41+
42+
Built On: {docdate} +
43+
Revision: 1.0.0
44+
45+
== Dependencies
46+
47+
This extension is written against the OpenCL API Specification Version 3.0.19
48+
49+
This extension requires `cl_intel_unified_shared_memory` extension
50+
for `cl_unified_shared_memory_type_intel` memory types enum.
51+
52+
== Overview
53+
54+
The goal of the extension is to report in unified form GPU memory ranges used by kernel,
55+
both explicit like kernel arguments and implicit ones made by driver like printf surface,
56+
scratch surface, etc. This information later can be used for some kernel instrumentation
57+
to detect out-of-bound accesses, kernel profiling and so on.
58+
There is a 2-step process to obtain this information. The first step is to find the count
59+
of memory allocations owned by kernel, so the buffer is large enough to store this number
60+
of `cl_kernel_allocation_info_intel` structs must be allocated later.
61+
This is done by providing an input allocation infos pointer with `nullptr` value.
62+
After allocating a storage array of this size, the user then provides the valid size
63+
and storage location to retrieve the data.
64+
65+
Information about memory allocation owned by kernel returned in
66+
`cl_kernel_allocation_info_intel` struct. In case of internal allocation
67+
(not a kernel argument) `arg_index` will be set to -1.
68+
69+
The following pseudo-code shows how to print information about kernel allocations:
70+
71+
[source, c++]
72+
----
73+
size_t sz = 0;
74+
clGetKernelWorkGroupInfo(kernel, device,
75+
CL_KERNEL_ALLOCATIONS_INFO_INTEL,
76+
0, nullptr, &sz);
77+
78+
size_t numAllocs = sz / sizeof(cl_kernel_allocation_info_intel);
79+
std::vector<cl_kernel_allocation_info_intel> allocInfos(numAllocs);
80+
clGetKernelWorkGroupInfo(kernel, device,
81+
CL_KERNEL_ALLOCATIONS_INFO_INTEL,
82+
sz, allocInfos.data(), nullptr);
83+
84+
auto toStr = [](cl_unified_shared_memory_type_intel type) {
85+
switch (type) {
86+
default: return "CL_MEM_TYPE_UNKNOWN_INTEL";
87+
#define CASE(_X_) case _X_ : return #_X_;
88+
CASE(CL_MEM_TYPE_UNKNOWN_INTEL);
89+
CASE(CL_MEM_TYPE_HOST_INTEL);
90+
CASE(CL_MEM_TYPE_DEVICE_INTEL);
91+
CASE(CL_MEM_TYPE_SHARED_INTEL);
92+
#undef CASE
93+
}
94+
};
95+
96+
for (uint32_t i = 0; i < numAllocs; ++i) {
97+
std::cout << "Allocation " << i << ": " << std::hex << "0x" << allocInfos[i].base << ", size: " << std::dec << allocInfos[i].size
98+
<< " arg_index: " << allocInfos[i].arg_index << " type: " << toStr(allocInfos[i].type) << "n";
99+
}
100+
----
101+
102+
Possible output:
103+
104+
[source, bash]
105+
----
106+
Allocation 0: 0x14d9ff00000, size: 65536 arg_index: 0 type: CL_MEM_TYPE_SHARED_INTEL
107+
Allocation 1: 0x14d9fef0000, size: 65536 arg_index: 2 type: CL_MEM_TYPE_SHARED_INTEL
108+
Allocation 2: 0x14d9ff20000, size: 4194304 arg_index: -1 type: CL_MEM_TYPE_UNKNOWN_INTEL
109+
Allocation 3: 0xffff80010010b000, size: 4096 arg_index: -1 type: CL_MEM_TYPE_UNKNOWN_INTEL
110+
----
111+
112+
== New API Functions
113+
114+
None.
115+
116+
== New API Enums
117+
118+
Accepted value for the _param_name_ parameter to
119+
*clGetKernelWorkGroupInfo* to query kernel allocationis information:
120+
121+
[source,c]
122+
----
123+
#define CL_KERNEL_ALLOCATIONS_INFO_INTEL 0x425A
124+
----
125+
126+
== New API Types
127+
128+
Returned as the query result value *clGetKernelWorkGroupInfo* for `CL_KERNEL_ALLOCATIONS_INFO_INTEL`:
129+
130+
[source]
131+
----
132+
typedef struct _cl_kernel_allocation_info_intel {
133+
void* base;
134+
size_t size;
135+
cl_unified_shared_memory_type_intel type;
136+
cl_int arg_index;
137+
} cl_kernel_allocation_info_intel;
138+
----
139+
140+
== Modifications to the OpenCL API Specification
141+
142+
=== Section 5.9.4 - Kernel Object Queries:
143+
144+
Add to Table 29 - List of supported param_names by
145+
*clGetKernelWorkGroupInfo*:
146+
147+
[caption="Table 29. "]
148+
.List of supported param_names by clGetKernelWorkGroupInfo
149+
[width="100%",cols="<30%,<20%,<50%",options="header"]
150+
|====
151+
| *cl_kernel_info* | Return Type | Info. returned in _param_value_
152+
| `CL_KERNEL_ALLOCATIONS_INFO_INTEL`
153+
| `cl_kernel_allocation_info_intel[]`
154+
| Returns an array of `cl_kernel_allocation_info_intel` structures describing kernel memory allocations information.
155+
Each structure consists of:
156+
157+
`base`: Base address of the allocation.
158+
159+
`size`: Size of allocation in bytes.
160+
161+
`type`: Type of allocation as described in `cl_unified_shared_memory_type_intel` enum.
162+
In case of internal (not a kernel argument) allocation `CL_MEM_TYPE_UNKNOWN_INTEL` will be returned.
163+
164+
`arg_index`: Kernel argument index corresponding to allocation.
165+
In case of internal (not a kernel argument) allocation `-1` will be returned.
166+
|====
167+
168+
169+
== Revision History
170+
171+
[cols="5,15,15,70"]
172+
[grid="rows"]
173+
[options="header"]
174+
|========================================
175+
|Rev|Date|Author|Changes
176+
|1.0.0|2026-01-20|Igor Venevtsev|First public version
177+
|========================================
178+
179+
//************************************************************************
180+
//Other formatting suggestions:
181+
//
182+
//* Use *bold* text for host APIs, or [source] syntax highlighting.
183+
//* Use `mono` text for device APIs, or [source] syntax highlighting.
184+
//* Use `mono` text for extension names, types, or enum values.
185+
//* Use _italics_ for parameters.
186+
//************************************************************************

‎extensions/extensions.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,8 @@ include::cl_intel_create_buffer_with_properties.asciidoc[]
8989
<<<
9090
include::cl_intel_device_attribute_query.asciidoc[]
9191
<<<
92+
include::cl_intel_kernel_allocations_info.asciidoc[]
93+
<<<
9294
include::cl_intel_mem_alloc_buffer_location.asciidoc[]
9395
<<<
9496
include::cl_intel_mem_channel_property.asciidoc[]

‎xml/cl.xml‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -335,6 +335,12 @@ server's OpenCL/api-docs repository.
335335
<member><type>cl_uint</type> <name>count</name></member>
336336
<member><type>char</type> <name>name</name>[<enum>CL_QUEUE_FAMILY_MAX_NAME_SIZE_INTEL</enum>]</member>
337337
</type>
338+
<type category="struct" name="cl_kernel_allocation_info_intel">
339+
<member><type>void</type>* <name>base</name></member>
340+
<member><type>size_t</type> <name>size</name></member>
341+
<member><type>cl_unified_shared_memory_type_intel</type> <name>type</name></member>
342+
<member><type>cl_int</type> <name>arg_index</name></member>
343+
</type>
338344

339345
<type category="define">#define <name>CL_VERSION_MAJOR_MASK</name> ((1 &lt;&lt; CL_VERSION_MAJOR_BITS) - 1)</type>
340346
<type category="define">#define <name>CL_VERSION_MINOR_MASK</name> ((1 &lt;&lt; CL_VERSION_MINOR_BITS) - 1)</type>
@@ -2476,7 +2482,9 @@ server's OpenCL/api-docs repository.
24762482
<enum value="0x4254" name="CL_DEVICE_NUM_EUS_PER_SUB_SLICE_INTEL"/>
24772483
<enum value="0x4255" name="CL_DEVICE_NUM_THREADS_PER_EU_INTEL"/>
24782484
<enum value="0x4256" name="CL_DEVICE_FEATURE_CAPABILITIES_INTEL"/>
2479-
<unused start="0x4257" end="0x425F"/>
2485+
<unused start="0x4257" end="0x4259"/>
2486+
<enum value="0x425A" name="CL_KERNEL_ALLOCATIONS_INFO_INTEL"/>
2487+
<unused start="0x425B" end="0x425F"/>
24802488
</enums>
24812489

24822490
<enums start="0x4260" end="0x426F" name="enums.4260" vendor="Codeplay">
@@ -8031,5 +8039,19 @@ server's OpenCL/api-docs repository.
80318039
<enum name="CL_COMMAND_QUEUE_SCHEDULING_WORK_GROUP_EXECUTE_COUNT_IMG"/>
80328040
</require>
80338041
</extension>
8042+
<extension name="cl_intel_kernel_allocations_info" revision="1.0.0" supported="opencl">
8043+
<require>
8044+
<type name="CL/cl.h"/>
8045+
</require>
8046+
<require>
8047+
<type name="cl_unified_shared_memory_type_intel"/>
8048+
</require>
8049+
<require>
8050+
<type name="cl_kernel_allocation_info_intel"/>
8051+
</require>
8052+
<require comment="cl_kernel_workgroup_info">
8053+
<enum name="CL_KERNEL_ALLOCATIONS_INFO_INTEL"/>
8054+
</require>
8055+
</extension>
80348056
</extensions>
80358057
</registry>

0 commit comments

Comments
 (0)