DPC++ Runtime
Runtime libraries for oneAPI DPC++
usm.hpp
Go to the documentation of this file.
1 //==---------------- usm.hpp - SYCL USM ------------------------*- C++ -*---==//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 // ===--------------------------------------------------------------------=== //
8 #pragma once
9 
10 #include <sycl/builtins.hpp>
11 #include <sycl/context.hpp>
12 #include <sycl/detail/common.hpp>
13 #include <sycl/detail/export.hpp>
14 #include <sycl/device.hpp>
15 #include <sycl/property_list.hpp>
16 #include <sycl/queue.hpp>
18 
19 #include <algorithm> // for max
20 #include <cstddef> // for size_t
21 
22 namespace sycl {
23 inline namespace _V1 {
25 // Explicit USM
27 __SYCL_EXPORT void *malloc_device(
28  size_t size, const device &dev, const context &ctxt,
29  const detail::code_location &CodeLoc = detail::code_location::current());
30 __SYCL_EXPORT void *malloc_device(
31  size_t size, const device &dev, const context &ctxt,
32  const property_list &propList,
33  const detail::code_location &CodeLoc = detail::code_location::current());
34 __SYCL_EXPORT void *malloc_device(
35  size_t size, const queue &q,
36  const detail::code_location &CodeLoc = detail::code_location::current());
37 __SYCL_EXPORT void *malloc_device(
38  size_t size, const queue &q, const property_list &propList,
39  const detail::code_location &CodeLoc = detail::code_location::current());
40 
41 __SYCL_EXPORT void *aligned_alloc_device(
42  size_t alignment, size_t size, const device &dev, const context &ctxt,
43  const detail::code_location &CodeLoc = detail::code_location::current());
44 __SYCL_EXPORT void *aligned_alloc_device(
45  size_t alignment, size_t size, const device &dev, const context &ctxt,
46  const property_list &propList,
47  const detail::code_location &CodeLoc = detail::code_location::current());
48 __SYCL_EXPORT void *aligned_alloc_device(
49  size_t alignment, size_t size, const queue &q,
50  const detail::code_location &CodeLoc = detail::code_location::current());
51 __SYCL_EXPORT void *aligned_alloc_device(
52  size_t alignment, size_t size, const queue &q,
53  const property_list &propList,
54  const detail::code_location &CodeLoc = detail::code_location::current());
55 
56 __SYCL_EXPORT void
57 free(void *ptr, const context &ctxt,
58  const detail::code_location &CodeLoc = detail::code_location::current());
59 __SYCL_EXPORT void
60 free(void *ptr, const queue &q,
61  const detail::code_location &CodeLoc = detail::code_location::current());
62 
64 // Restricted USM
66 __SYCL_EXPORT void *malloc_host(
67  size_t size, const context &ctxt,
68  const detail::code_location &CodeLoc = detail::code_location::current());
69 __SYCL_EXPORT void *malloc_host(
70  size_t size, const context &ctxt, const property_list &propList,
71  const detail::code_location &CodeLoc = detail::code_location::current());
72 __SYCL_EXPORT void *malloc_host(
73  size_t size, const queue &q,
74  const detail::code_location &CodeLoc = detail::code_location::current());
75 __SYCL_EXPORT void *malloc_host(
76  size_t size, const queue &q, const property_list &propList,
77  const detail::code_location &CodeLoc = detail::code_location::current());
78 
79 __SYCL_EXPORT void *malloc_shared(
80  size_t size, const device &dev, const context &ctxt,
81  const detail::code_location &CodeLoc = detail::code_location::current());
82 __SYCL_EXPORT void *malloc_shared(
83  size_t size, const device &dev, const context &ctxt,
84  const property_list &propList,
85  const detail::code_location &CodeLoc = detail::code_location::current());
86 __SYCL_EXPORT void *malloc_shared(
87  size_t size, const queue &q,
88  const detail::code_location &CodeLoc = detail::code_location::current());
89 __SYCL_EXPORT void *malloc_shared(
90  size_t size, const queue &q, const property_list &propList,
91  const detail::code_location &CodeLoc = detail::code_location::current());
92 
93 __SYCL_EXPORT void *aligned_alloc_host(
94  size_t alignment, size_t size, const context &ctxt,
95  const detail::code_location &CodeLoc = detail::code_location::current());
96 __SYCL_EXPORT void *aligned_alloc_host(
97  size_t alignment, size_t size, const context &ctxt,
98  const property_list &propList,
99  const detail::code_location &CodeLoc = detail::code_location::current());
100 __SYCL_EXPORT void *aligned_alloc_host(
101  size_t alignment, size_t size, const queue &q,
102  const detail::code_location &CodeLoc = detail::code_location::current());
103 __SYCL_EXPORT void *aligned_alloc_host(
104  size_t alignment, size_t size, const queue &q,
105  const property_list &propList,
106  const detail::code_location &CodeLoc = detail::code_location::current());
107 
108 __SYCL_EXPORT void *aligned_alloc_shared(
109  size_t alignment, size_t size, const device &dev, const context &ctxt,
110  const detail::code_location &CodeLoc = detail::code_location::current());
111 __SYCL_EXPORT void *aligned_alloc_shared(
112  size_t alignment, size_t size, const device &dev, const context &ctxt,
113  const property_list &propList,
114  const detail::code_location &CodeLoc = detail::code_location::current());
115 __SYCL_EXPORT void *aligned_alloc_shared(
116  size_t alignment, size_t size, const queue &q,
117  const detail::code_location &CodeLoc = detail::code_location::current());
118 __SYCL_EXPORT void *aligned_alloc_shared(
119  size_t alignment, size_t size, const queue &q,
120  const property_list &propList,
121  const detail::code_location &CodeLoc = detail::code_location::current());
122 
124 // single form
126 __SYCL_EXPORT void *
127 malloc(size_t size, const device &dev, const context &ctxt, usm::alloc kind,
128  const detail::code_location &CodeLoc = detail::code_location::current());
129 __SYCL_EXPORT void *
130 malloc(size_t size, const device &dev, const context &ctxt, usm::alloc kind,
131  const property_list &propList,
132  const detail::code_location &CodeLoc = detail::code_location::current());
133 __SYCL_EXPORT void *
134 malloc(size_t size, const queue &q, usm::alloc kind,
135  const detail::code_location &CodeLoc = detail::code_location::current());
136 __SYCL_EXPORT void *
137 malloc(size_t size, const queue &q, usm::alloc kind,
138  const property_list &propList,
139  const detail::code_location &CodeLoc = detail::code_location::current());
140 
141 __SYCL_EXPORT void *aligned_alloc(
142  size_t alignment, size_t size, const device &dev, const context &ctxt,
143  usm::alloc kind,
144  const detail::code_location &CodeLoc = detail::code_location::current());
145 __SYCL_EXPORT void *aligned_alloc(
146  size_t alignment, size_t size, const device &dev, const context &ctxt,
147  usm::alloc kind, const property_list &propList,
148  const detail::code_location &CodeLoc = detail::code_location::current());
149 __SYCL_EXPORT void *aligned_alloc(
150  size_t alignment, size_t size, const queue &q, usm::alloc kind,
151  const detail::code_location &CodeLoc = detail::code_location::current());
152 __SYCL_EXPORT void *aligned_alloc(
153  size_t alignment, size_t size, const queue &q, usm::alloc kind,
154  const property_list &propList,
155  const detail::code_location &CodeLoc = detail::code_location::current());
156 
158 // Helper function used to determine if the Alignment argument is a power of 2
160 inline size_t is_not_power_of_two(size_t Alignment) {
161  return (Alignment & (Alignment - 1));
162 }
163 
165 // Template forms
167 template <typename T>
169  size_t Count, const device &Dev, const context &Ctxt,
170  const property_list &PropList = {},
171  const detail::code_location &CodeLoc = detail::code_location::current()) {
172  return static_cast<T *>(aligned_alloc_device(alignof(T), Count * sizeof(T),
173  Dev, Ctxt, PropList, CodeLoc));
174 }
175 
176 template <typename T>
178  size_t Count, const queue &Q, const property_list &PropList = {},
179  const detail::code_location &CodeLoc = detail::code_location::current()) {
180  return malloc_device<T>(Count, Q.get_device(), Q.get_context(), PropList,
181  CodeLoc);
182 }
183 
184 template <typename T>
186  size_t Alignment, size_t Count, const device &Dev, const context &Ctxt,
187  const property_list &PropList = {},
188  const detail::code_location &CodeLoc = detail::code_location::current()) {
190  return nullptr;
191  }
192  return static_cast<T *>(aligned_alloc_device(max(Alignment, alignof(T)),
193  Count * sizeof(T), Dev, Ctxt,
194  PropList, CodeLoc));
195 }
196 
197 template <typename T>
199  size_t Alignment, size_t Count, const queue &Q,
200  const property_list &PropList = {},
201  const detail::code_location &CodeLoc = detail::code_location::current()) {
203  return nullptr;
204  }
205  return aligned_alloc_device<T>(Alignment, Count, Q.get_device(),
206  Q.get_context(), PropList, CodeLoc);
207 }
208 
209 template <typename T>
211  size_t Count, const context &Ctxt, const property_list &PropList = {},
212  const detail::code_location &CodeLoc = detail::code_location::current()) {
213  return static_cast<T *>(aligned_alloc_host(alignof(T), Count * sizeof(T),
214  Ctxt, PropList, CodeLoc));
215 }
216 
217 template <typename T>
219  size_t Count, const queue &Q, const property_list &PropList = {},
220  const detail::code_location &CodeLoc = detail::code_location::current()) {
221  return malloc_host<T>(Count, Q.get_context(), PropList, CodeLoc);
222 }
223 
224 template <typename T>
226  size_t Count, const device &Dev, const context &Ctxt,
227  const property_list &PropList = {},
228  const detail::code_location &CodeLoc = detail::code_location::current()) {
229  return static_cast<T *>(aligned_alloc_shared(alignof(T), Count * sizeof(T),
230  Dev, Ctxt, PropList, CodeLoc));
231 }
232 
233 template <typename T>
235  size_t Count, const queue &Q, const property_list &PropList = {},
236  const detail::code_location &CodeLoc = detail::code_location::current()) {
237  return malloc_shared<T>(Count, Q.get_device(), Q.get_context(), PropList,
238  CodeLoc);
239 }
240 
241 template <typename T>
243  size_t Alignment, size_t Count, const context &Ctxt,
244  const property_list &PropList = {},
245  const detail::code_location &CodeLoc = detail::code_location::current()) {
247  return nullptr;
248  }
249  return static_cast<T *>(aligned_alloc_host(std ::max(Alignment, alignof(T)),
250  Count * sizeof(T), Ctxt, PropList,
251  CodeLoc));
252 }
253 
254 template <typename T>
256  size_t Alignment, size_t Count, const queue &Q,
257  const property_list &PropList = {},
258  const detail::code_location &CodeLoc = detail::code_location::current()) {
260  return nullptr;
261  }
262  return aligned_alloc_host<T>(Alignment, Count, Q.get_context(), PropList,
263  CodeLoc);
264 }
265 
266 template <typename T>
268  size_t Alignment, size_t Count, const device &Dev, const context &Ctxt,
269  const property_list &PropList = {},
270  const detail::code_location &CodeLoc = detail::code_location::current()) {
272  return nullptr;
273  }
274  return static_cast<T *>(aligned_alloc_shared(max(Alignment, alignof(T)),
275  Count * sizeof(T), Dev, Ctxt,
276  PropList, CodeLoc));
277 }
278 
279 template <typename T>
281  size_t Alignment, size_t Count, const queue &Q,
282  const property_list &PropList = {},
283  const detail::code_location &CodeLoc = detail::code_location::current()) {
285  return nullptr;
286  }
287  return aligned_alloc_shared<T>(Alignment, Count, Q.get_device(),
288  Q.get_context(), PropList, CodeLoc);
289 }
290 
291 template <typename T>
293  size_t Count, const device &Dev, const context &Ctxt, usm::alloc Kind,
294  const property_list &PropList = {},
295  const detail::code_location &CodeLoc = detail::code_location::current()) {
296  return static_cast<T *>(aligned_alloc(alignof(T), Count * sizeof(T), Dev,
297  Ctxt, Kind, PropList, CodeLoc));
298 }
299 
300 template <typename T>
302  size_t Count, const queue &Q, usm::alloc Kind,
303  const property_list &PropList = {},
304  const detail::code_location &CodeLoc = detail::code_location::current()) {
305  return malloc<T>(Count, Q.get_device(), Q.get_context(), Kind, PropList,
306  CodeLoc);
307 }
308 
309 template <typename T>
311  size_t Alignment, size_t Count, const device &Dev, const context &Ctxt,
312  usm::alloc Kind, const property_list &PropList = {},
313  const detail::code_location &CodeLoc = detail::code_location::current()) {
315  return nullptr;
316  }
317  return static_cast<T *>(aligned_alloc(max(Alignment, alignof(T)),
318  Count * sizeof(T), Dev, Ctxt, Kind,
319  PropList, CodeLoc));
320 }
321 
322 template <typename T>
324  size_t Alignment, size_t Count, const queue &Q, usm::alloc Kind,
325  const property_list &PropList = {},
326  const detail::code_location &CodeLoc = detail::code_location::current()) {
328  return nullptr;
329  }
330  return aligned_alloc<T>(Alignment, Count, Q.get_device(), Q.get_context(),
331  Kind, PropList, CodeLoc);
332 }
333 
334 // Device copy enhancement APIs, prepare_for and release_from USM.
335 
336 namespace ext::oneapi::experimental {
337 
338 __SYCL_EXPORT void prepare_for_device_copy(const void *Ptr, size_t Size,
339  const context &Context);
340 
341 __SYCL_EXPORT void prepare_for_device_copy(const void *Ptr, size_t Size,
342  const queue &Queue);
343 
344 __SYCL_EXPORT void release_from_device_copy(const void *Ptr,
345  const context &Context);
346 
347 __SYCL_EXPORT void release_from_device_copy(const void *Ptr,
348  const queue &Queue);
349 
350 } // namespace ext::oneapi::experimental
351 
352 } // namespace _V1
353 } // namespace sycl
The context class represents a SYCL context on which kernel functions may be executed.
Definition: context.hpp:51
The SYCL device class encapsulates a single SYCL device on which kernels may be executed.
Definition: device.hpp:64
Objects of the property_list class are containers for the SYCL properties.
Encapsulates a single SYCL queue which schedules kernels on a SYCL device.
Definition: queue.hpp:111
device get_device() const
Definition: queue.cpp:76
context get_context() const
Definition: queue.cpp:74
constexpr alignment_key::value_t< K > alignment
void prepare_for_device_copy(const void *Ptr, size_t Size, const context &Context)
Definition: usm_impl.cpp:688
void release_from_device_copy(const void *Ptr, const context &Context)
Definition: usm_impl.cpp:697
void * aligned_alloc(size_t alignment, size_t size, const device &dev, const context &ctxt, usm::alloc kind, const detail::code_location &CodeLoc=detail::code_location::current())
size_t is_not_power_of_two(size_t Alignment)
Definition: usm.hpp:160
void * aligned_alloc_host(size_t alignment, size_t size, const context &ctxt, const detail::code_location &CodeLoc=detail::code_location::current())
Definition: usm_impl.cpp:433
void * aligned_alloc_shared(size_t alignment, size_t size, const device &dev, const context &ctxt, const detail::code_location &CodeLoc=detail::code_location::current())
Definition: usm_impl.cpp:459
void * malloc_shared(size_t size, const device &dev, const context &ctxt, const detail::code_location &CodeLoc=detail::code_location::current())
Definition: usm_impl.cpp:408
void * aligned_alloc_device(size_t alignment, size_t size, const device &dev, const context &ctxt, const detail::code_location &CodeLoc=detail::code_location::current())
Definition: usm_impl.cpp:345
void * malloc_device(size_t size, const device &dev, const context &ctxt, const detail::code_location &CodeLoc=detail::code_location::current())
Definition: usm_impl.cpp:320
void * malloc(size_t size, const device &dev, const context &ctxt, usm::alloc kind, const detail::code_location &CodeLoc=detail::code_location::current())
void * malloc_host(size_t size, const context &ctxt, const detail::code_location &CodeLoc=detail::code_location::current())
Definition: usm_impl.cpp:383
void free(void *ptr, const context &ctxt, const detail::code_location &CodeLoc=detail::code_location::current())
Definition: usm_impl.cpp:374
Definition: access.hpp:18
static constexpr code_location current(const char *fileName=__CODELOC_FILE_NAME, const char *funcName=__CODELOC_FUNCTION, unsigned long lineNo=__CODELOC_LINE, unsigned long columnNo=__CODELOC_COLUMN) noexcept
Definition: common.hpp:68