Skip to content

Commit 8335ff5

Browse files
committed
Add more details on motivation of the extension
-------------------------------------------------------------- 1. Remove notes 2. Specify which malloc api accept the property 3. Add more detaile ddescription, and expected behavior when used on non fpga device
1 parent bc2bbfa commit 8335ff5

File tree

1 file changed

+10
-13
lines changed

1 file changed

+10
-13
lines changed

sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -45,21 +45,13 @@ change incompatibly in future versions of {dpcpp} without prior notice.
4545
*Shipping software products should not rely on APIs defined in this
4646
specification.*
4747

48-
[NOTE]
49-
====
50-
This extension is currently implemented in {dpcpp} only for FPGA devices. Attempting to use this extension on other devices or backends may result in no effect.
51-
52-
This serves as a temporary workaround for usm allocation to accept buffer location properties, and the formal solution will come in the future.
53-
====
5448

5549
== Overview
5650

5751
This document propose a new buffer_location runtime property that can be passed to `malloc_device`.
5852

5953
On targets that provide more than one type of global memory, this provide users the flexibility of choosing which memory the device usm should be allocated to.
6054

61-
This information is not a hint; it is a functional requirement of the program that must be respected.
62-
6355
== Specification
6456

6557
=== Feature test macro
@@ -86,20 +78,20 @@ supports.
8678

8779
[source,c++]
8880
----
89-
array = (int *)malloc_device<int>(
90-
N * sizeof(int), q,
91-
property_list{sycl::ext::intel::experimental::property::usm::buffer_location(2)});
81+
array = (int *)sycl::malloc_device<int>(
82+
N, q,
83+
sycl::property_list{sycl::ext::intel::experimental::property::usm::buffer_location(2)});
9284
9385
sycl::queue q;
94-
q.parallel_for(range<1>(N), [=] (id<1> i){
86+
q.parallel_for(sycl::range<1>(N), [=] (sycl::id<1> i){
9587
data[i] *= 2;
9688
}).wait();
9789
----
9890

9991

10092
=== Changes to runtime properties
10193

102-
To pass the runtime properties into malloc API, a new buffer properties is introduced.
94+
This extension adds the new property `sycl::ext::intel::experimental::property::usm::buffer_location`` which applications can pass in the property_list parameter to all overloads of the `sycl::malloc_device()`, `sycl::malloc_shared()`, `sycl::malloc_host()` function. However, this property has no effect when passed to `sycl::malloc_shared()`, `sycl::malloc_host()`. Following is a synopsis of this property.
10395

10496
[source,c++]
10597
----
@@ -114,6 +106,11 @@ class buffer_location {
114106
} // namespace sycl::ext::intel::experimental::property::usm
115107
----
116108

109+
On targets that provide more than one type of global memory, `buffer_location` allows user to specify which of the global memory to allocate memory to. This provide user the flexibility to choose the global memory that satisfy requirements for bandwodth and throughput.
110+
111+
This property is ignored for non-FPGA devices. Attempting to use this extension on other devices or backends will result in no effect.
112+
113+
117114
== Issues
118115

119116
== Revision History

0 commit comments

Comments
 (0)