Skip to content

Commit 962417d

Browse files
authored
[SYCL][Doc] Define buffer_location property for USM allocations (#5665)
This serves as a temporary solution to supporting usm buffer location, and it is the easiest to implement. Align with changes in #5634 A more complex workaround is to define a new malloc API that accept sycl::ext::oneapi::experimental::properties as its property argument of malloc. The full solution is to define a malloc api that takes sycl::ext::oneapi::experimental::properties as property argument and returns annotated_ptr
1 parent e5f9a94 commit 962417d

File tree

1 file changed

+135
-0
lines changed

1 file changed

+135
-0
lines changed
Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
= sycl_ext_intel_runtime_buffer_location
2+
3+
:source-highlighter: coderay
4+
:coderay-linenums-mode: table
5+
6+
// This section needs to be after the document title.
7+
:doctype: book
8+
:toc2:
9+
:toc: left
10+
:encoding: utf-8
11+
:lang: en
12+
:dpcpp: pass:[DPC++]
13+
14+
// Set the default source code type in this document to C++,
15+
// for syntax highlighting purposes. This is needed because
16+
// docbook uses c++ and html5 uses cpp.
17+
:language: {basebackend@docbook:c++:cpp}
18+
19+
== Notice
20+
21+
[%hardbreaks]
22+
Copyright (C) 2022-2022 Intel Corporation. All rights reserved.
23+
24+
Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are trademarks
25+
of The Khronos Group Inc. OpenCL(TM) is a trademark of Apple Inc. used by
26+
permission by Khronos.
27+
28+
== Contact
29+
30+
To report problems with this extension, please open a new issue at:
31+
32+
https://github.com/intel/llvm/issues
33+
34+
== Dependencies
35+
36+
This extension is written against the SYCL 2020 revision 4 specification. All
37+
references below to the "core SYCL specification" or to section numbers in the
38+
SYCL specification refer to that revision.
39+
40+
== Status
41+
This is a proposed extension specification, intended to gather community
42+
feedback. Interfaces defined in this specification may not be implemented yet
43+
or may be in a preliminary state. The specification itself may also change in
44+
incompatible ways before it is finalized. *Shipping software products should
45+
not rely on APIs defined in this specification.*
46+
47+
== Overview
48+
49+
This document propose a new buffer_location runtime property that can be
50+
passed to `malloc_device`.
51+
52+
On targets that provide more than one type of global memory, this provide
53+
users the flexibility of choosing which memory the device usm should be
54+
allocated to.
55+
56+
== Specification
57+
58+
=== Feature test macro
59+
60+
This extension provides a feature-test macro as described in the core SYCL
61+
specification. An implementation supporting this extension must predefine the
62+
macro `SYCL_EXT_INTEL_RUNTIME_BUFFER_LOCATION` to one of the values defined in the table
63+
below. Applications can test for the existence of this macro to determine if
64+
the implementation supports this feature, or applications can test the macro's
65+
value to determine which of the extension's features the implementation
66+
supports.
67+
68+
[%header,cols="1,5"]
69+
|===
70+
|Value
71+
|Description
72+
73+
|1
74+
|The APIs of this experimental extension are not versioned, so the
75+
feature-test macro always has this value.
76+
|===
77+
78+
== Examples
79+
80+
[source,c++]
81+
----
82+
array = (int *)sycl::malloc_device<int>(
83+
N, q,
84+
sycl::property_list{sycl::ext::intel::experimental::property::usm::buffer_location(2)});
85+
86+
sycl::queue q;
87+
q.parallel_for(sycl::range<1>(N), [=] (sycl::id<1> i){
88+
data[i] *= 2;
89+
}).wait();
90+
----
91+
92+
93+
=== Changes to runtime properties
94+
95+
This extension adds the new property
96+
`sycl::ext::intel::experimental::property::usm::buffer_location` which
97+
applications can pass in the property_list parameter to all overloads of the
98+
`sycl::malloc_device()`, `sycl::malloc_shared()`, and `sycl::malloc_host()`
99+
functions. However, this property has no effect when passed to
100+
`sycl::malloc_shared()` or `sycl::malloc_host()`. Following is a synopsis of
101+
this property.
102+
103+
[source,c++]
104+
----
105+
namespace sycl::ext::intel::experimental::property::usm {
106+
107+
class buffer_location {
108+
public:
109+
buffer_location(int location);
110+
int get_buffer_location() const;
111+
};
112+
113+
} // namespace sycl::ext::intel::experimental::property::usm
114+
----
115+
116+
On targets that provide more than one type of global memory, `buffer_location`
117+
allows user to specify which of the global memory to allocate memory to. This
118+
provide user the flexibility to choose the global memory that satisfy
119+
requirements for bandwidth and throughput.
120+
121+
This property is ignored for non-FPGA devices. Attempting to use this
122+
extension on other devices or backends will result in no effect.
123+
124+
125+
== Issues
126+
127+
== Revision History
128+
129+
[cols="5,15,15,70"]
130+
[grid="rows"]
131+
[options="header"]
132+
|========================================
133+
|Rev|Date|Author|Changes
134+
|1|2022-03-01|Sherry Yuan|*Initial public draft*
135+
|========================================

0 commit comments

Comments
 (0)