Skip to content

Commit a70edf4

Browse files
sherry-yuansherry-yuan
authored
Add CL_MEM_ALLOC_BUFFER_LOCATION_INTEL enum (#746)
-------------------------------------------------- This allows the user to specify which device memory to allocate to.
1 parent aa1fc0b commit a70edf4

3 files changed

Lines changed: 193 additions & 3 deletions

File tree

‎extensions/cl_intel_mem_alloc_buffer_location.asciidoc‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
cl_intel_mem_alloc_buffer_location
2+
==================================
3+
4+
// This section needs to be after the document title.
5+
:doctype: book
6+
:toc2:
7+
:toc: left
8+
:encoding: utf-8
9+
:lang: en
10+
11+
:blank: pass:[ +]
12+
13+
// Set the default source code type in this document to C++,
14+
// for syntax highlighting purposes. This is needed because
15+
// docbook uses c++ and html5 uses cpp.
16+
:language: {basebackend@docbook:c++:cpp}
17+
18+
Name Strings
19+
------------
20+
21+
+cl_intel_mem_alloc_buffer_location+
22+
23+
Contact
24+
-------
25+
26+
Peter Colberg, Intel (peter 'dot' colberg 'at' intel 'dot' com)
27+
28+
Contributors
29+
------------
30+
31+
* Sherry Yuan, Intel
32+
* Michael Kinsner, Intel
33+
* Joseph Garvey, Intel
34+
* Ben Ashbaugh, Intel
35+
* Aditi Kumaraswamy, Intel
36+
* Peter Colberg, Intel
37+
* Tanner Young-Schultz, Intel
38+
* Zibai Wang, Intel
39+
40+
Notice
41+
------
42+
43+
Copyright (c) 2020-2021 Intel Corporation. All rights reserved.
44+
45+
Status
46+
------
47+
48+
Final Draft
49+
50+
Version
51+
-------
52+
53+
[width="40%",cols="25,25"]
54+
|========================================
55+
| Last Modified | 2021-12-01
56+
| Revision | 1
57+
|========================================
58+
59+
Dependencies
60+
------------
61+
62+
This extension is written against the OpenCL Specification Version 1.0, Revision 48.
63+
64+
This extension requires OpenCL 3.0 or later, and/or the cl_intel_create_buffer_with_properties extension if user wish to use this property via extension functions.
65+
66+
Overview
67+
--------
68+
69+
On some devices, global memory may be partitioned into disjoint regions. This may be to enable control over specific characteristics such as available bandwidths on memory interfaces, or performance on types of access patterns.
70+
71+
This extension allows a user to explicitly specify the partition/region of global memory in which an allocation should reside, by passing an implementation defined numerical ID that identifies the region to the allocation function.
72+
73+
*Example Usage*
74+
75+
To pass the property into a buffer allocation:
76+
77+
[source,c]
78+
----
79+
cl_mem_properties_intel props[] = {CL_MEM_ALLOC_BUFFER_LOCATION_INTEL, 2, 0};
80+
81+
cl_mem test_mem = clCreateBufferWithPropertiesINTEL(
82+
context, props, flags,
83+
size, NULL,
84+
&status);
85+
----
86+
87+
To pass the property into a usm allocation:
88+
89+
[source,c]
90+
----
91+
cl_mem_properties_intel property[3] = {
92+
CL_MEM_ALLOC_BUFFER_LOCATION_INTEL, 2,
93+
0};
94+
void *ptr = clDeviceMemAllocINTEL(context, device, property, size, alignment, &status);
95+
----
96+
97+
User can query the buffer location of the usm allocation by passing it into *clGetMemAllocInfoINTEL*
98+
99+
[source,c]
100+
----
101+
// Should return 2 given the previous allocation.
102+
clGetMemAllocInfoINTEL(context, ptr, CL_MEM_ALLOC_BUFFER_LOCATION_INTEL, sizeof(cl_uint), param_value, param_value_ret)
103+
----
104+
105+
106+
New API Functions
107+
-----------------
108+
109+
None.
110+
111+
New API Enums
112+
-------------
113+
114+
Accepted property for the _properties_ parameter to *clCreateBufferWithPropertiesINTEL*, *clCreateBufferWithProperties*, *clDeviceMemAllocINTEL*, *clSharedMemAllocINTEL*, *clHostMemAllocINTEL* to specify requested global memory type ID.
115+
116+
It can be passed into *clGetMemAllocInfoINTEL* to get the buffer location of allocated usm memory, as well as *clGetMemObjectInfo* to get buffer location of the buffer. If no property was specified, then the ID corresponding to default global memory is returned.
117+
118+
[source,c]
119+
----
120+
#define CL_MEM_ALLOC_BUFFER_LOCATION_INTEL 0x419E
121+
----
122+
123+
Modifications to the OpenCL API Specification
124+
---------------------------------------------
125+
126+
(Add Table 5.X: *List of supported properties by clCreateBufferWithPropertiesINTEL* to the cl_intel_create_buffer_with_properties extension) ::
127+
+
128+
129+
[cols="1,1,4",options="header",width = "90%"]
130+
|====
131+
| cl_mem_properties_intel enum
132+
| Property value
133+
| Description
134+
135+
| +CL_MEM_ALLOC_BUFFER_LOCATION_INTEL+
136+
| +cl_uint+
137+
| Identifies the ID of global memory partition to which the memory should be allocated. The range of legal values is implementation defined. If the value is not valid, or the implementation is unable to allocate memory in the requested memory type, an `CL_INVALID_PROPERTY` error will be emitted.
138+
|====
139+
140+
[[cl_mem_info_intel]]
141+
.List of supported param_names by clGetMemAllocInfoINTEL
142+
[width="100%",cols="<34%,<33%,<33%",options="header"]
143+
|====
144+
| *cl_mem_info_intel* | Return type | Info. returned in _param_value_
145+
| `CL_MEM_ALLOC_BUFFER_LOCATION_INTEL`
146+
| cl_uint
147+
| Returns buffer location for the Unified Shared Memory allocation.
148+
149+
Return the ID of default global memory if no buffer location property were specified.
150+
|====
151+
152+
Interactions with Other Extensions
153+
----------------------------------
154+
155+
If `cl_intel_unified_shared_memory` is supported then *clDeviceMemAllocINTEL*, *clSharedMemAllocINTEL*, *clHostMemAllocINTEL*, *clGetMemAllocInfoINTEL* also
156+
accepts `CL_MEM_ALLOC_BUFFER_LOCATION_INTEL` for _cl_mem_properties_intel_.
157+
158+
If `cl_intel_create_buffer_with_properties` is supported then *clCreateBufferWithPropertiesINTEL* also
159+
accepts `CL_MEM_ALLOC_BUFFER_LOCATION_INTEL` for _cl_mem_properties_intel_.
160+
161+
Issues
162+
------
163+
164+
None.
165+
166+
Revision History
167+
----------------
168+
169+
[cols="5,15,15,70"]
170+
[grid="rows"]
171+
[options="header"]
172+
|========================================
173+
|Rev|Date|Author|Changes
174+
|1|2021-12-01|Sherry Yuan|*Initial public release*
175+
|========================================

‎extensions/cl_intel_unified_shared_memory.asciidoc‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,6 @@ typedef cl_uint cl_mem_info_intel;
236236
#define CL_MEM_ALLOC_SIZE_INTEL 0x419C
237237
#define CL_MEM_ALLOC_DEVICE_INTEL 0x419D
238238
/* CL_MEM_ALLOC_FLAGS_INTEL - defined above */
239-
/* Enum values 0x419E-0x419F are reserved for future queries. */
240239
----
241240

242241
Enumeration type and values describing the type of Unified Shared Memory allocation.
@@ -721,7 +720,6 @@ Otherwise, it will return one of the following error values:
721720
| Returns allocation flags for the Unified Shared Memory allocation.
722721

723722
Returns `0` if no allocation flags were specified for the Unified Shared Memory allocation and for `CL_MEM_TYPE_UNKNOWN_INTEL` allocations.
724-
725723
|====
726724

727725
==== Using Unified Shared Memory with Kernels
@@ -1014,6 +1012,11 @@ Otherwise, it will return one of the following errors:
10141012
* `CL_OUT_OF_RESOURCES` if there is a failure to allocate resources required by the OpenCL implementation on the device.
10151013
* `CL_OUT_OF_HOST_MEMORY` if there is a failure to allocate resources required by the OpenCL implementation on the host.
10161014

1015+
== Interactions with Other Extensions
1016+
1017+
If `cl_intel_mem_alloc_buffer_location` is supported then *clDeviceMemAllocINTEL*, *clSharedMemAllocINTEL*, *clHostMemAllocINTEL*, *clGetMemAllocInfoINTEL* also
1018+
accepts `CL_MEM_ALLOC_BUFFER_LOCATION_INTEL` for _cl_mem_properties_intel_.
1019+
10171020
== Issues
10181021

10191022
. Is there a minimum supported granularity for concurrent access? For example, might it be possible to concurrently access different pages of an allocation, but not different bytes within the same page?

‎xml/cl.xml‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2056,7 +2056,8 @@ server's OpenCL/api-docs repository.
20562056
<enum value="0x419B" name="CL_MEM_ALLOC_BASE_PTR_INTEL"/>
20572057
<enum value="0x419C" name="CL_MEM_ALLOC_SIZE_INTEL"/>
20582058
<enum value="0x419D" name="CL_MEM_ALLOC_DEVICE_INTEL"/>
2059-
<unused start="0x419E" end="0x419F"/>
2059+
<enum value="0x419E" name="CL_MEM_ALLOC_BUFFER_LOCATION_INTEL"/>
2060+
<unused start="0x419F" end="0x419F"/>
20602061
</enums>
20612062

20622063
<enums start="0x41A0" end="0x41DF" name="enums.41A0" vendor="Qualcomm">
@@ -6401,6 +6402,17 @@ server's OpenCL/api-docs repository.
64016402
<enum name="CL_MEM_CHANNEL_INTEL"/>
64026403
</require>
64036404
</extension>
6405+
<extension name="cl_intel_mem_alloc_buffer_location" supported="opencl">
6406+
<require>
6407+
<type name="CL/cl.h"/>
6408+
</require>
6409+
<require comment="cl_mem_properties_intel">
6410+
<enum name="CL_MEM_ALLOC_BUFFER_LOCATION_INTEL"/>
6411+
</require>
6412+
<require comment="cl_mem_alloc_info_intel">
6413+
<enum name="CL_MEM_ALLOC_BUFFER_LOCATION_INTEL"/>
6414+
</require>
6415+
</extension>
64046416
<extension name="cl_arm_scheduling_controls" supported="opencl">
64056417
<require comment="Types">
64066418
<type name="cl_device_scheduling_controls_capabilities_arm"/>

0 commit comments

Comments
 (0)