Skip to content

Commit a58b2ef

Browse files
Steffen LarsenAerialMantis
Steffen Larsen
authored and
AerialMantis
committed
CP025: Property list generalization
1 parent 52a31a6 commit a58b2ef

File tree

1 file changed

+236
-0
lines changed

1 file changed

+236
-0
lines changed

‎general_property_lists/general_property_lists.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
| Proposal ID | CP025 |
2+
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
3+
| Name | Properties for context, program, sampler, and accessor: Expanding use of property lists |
4+
| Date of Creation | 23 January 2020 |
5+
| Target | SYCL 1.2.1 extension |
6+
| Current Status | Draft |
7+
| Original author | Steffen Larsen steffen.larsen@codeplay.com |
8+
| Contributors | Steffen Larsen steffen.larsen@codeplay.com, Stuart Adams stuart.adams@codeplay.com, Gordon Brown gordon@codeplay.com, Ruyman Reyes ruyman@codeplay.com |
9+
10+
# Properties for context, program, sampler, and accessor: Expanding use of property lists
11+
12+
## Overview
13+
14+
With the move towards a [generalizing SYCL](https://github.com/KhronosGroup/SYCL-Shared/blob/master/proposals/sycl_generalization.md),
15+
future backends may have use of parameters passed to their parent SYCL object.
16+
However, with only `buffer`, `image`, and `queue` exposing constructors with a
17+
`property_list` parameter, the extensibility of the parameter space of all other
18+
user-constructible SYCL objects is limited.
19+
20+
This proposal extends the constructors for `context`, `program`, `sampler`, and
21+
`accessor` with an additional `property_list` parameter.
22+
23+
## Specification changes
24+
25+
Section 4.3.4 of the 1.2.1 SYCL specifications (Rev 6) is changed to mention
26+
`context`, `program`, `sampler`, and `accessor` as providing a `property_list`
27+
parameter in their constructors. This is in addition to the existing mention of
28+
`buffer`, `image`, and `queue`.
29+
30+
## Interface changes
31+
32+
The constructors for `context`, `program`, `sampler`, and `accessor`
33+
are extended to have a `property_list` parameter, similar to `buffer`, `image`, and
34+
`queue`.
35+
36+
### Context changes
37+
38+
```cpp
39+
namespace cl {
40+
namespace sycl {
41+
class context {
42+
public:
43+
context(const property_list &propList = {});
44+
45+
explicit context(async_handler asyncHandler,
46+
const property_list &propList = {});
47+
48+
context(const device &dev, const property_list &propList = {});
49+
50+
context(const device &dev, async_handler asyncHandler,
51+
const property_list &propList = {});
52+
53+
context(const platform &plt, const property_list &propList = {});
54+
55+
context(const platform &plt, async_handler asyncHandler,
56+
const property_list &propList = {});
57+
58+
context(const vector_class<device> &deviceList,
59+
const property_list &propList = {});
60+
61+
context(const vector_class<device> &deviceList,
62+
async_handler asyncHandler, const property_list &propList = {});
63+
64+
...
65+
};
66+
} // namespace sycl
67+
} // namespace cl
68+
```
69+
70+
### Program changes
71+
72+
```cpp
73+
namespace cl {
74+
namespace sycl {
75+
class program {
76+
public:
77+
explicit program(const context &context,
78+
const property_list &propList = {});
79+
80+
program(const context &context, vector_class<device> deviceList,
81+
const property_list &propList = {});
82+
83+
program(vector_class<program> &programList, string_class linkOptions = "",
84+
const property_list &propList = {});
85+
86+
...
87+
};
88+
} // namespace sycl
89+
} // namespace cl
90+
```
91+
92+
### Sampler changes
93+
94+
```cpp
95+
namespace cl {
96+
namespace sycl {
97+
class sampler {
98+
public:
99+
sampler(coordinate_normalization_mode normalizationMode,
100+
addressing_mode addressingMode, filterin_mode filteringMode,
101+
const property_list &propList = {});
102+
103+
...
104+
};
105+
} // namespace sycl
106+
} // namespace cl
107+
```
108+
109+
### Accessor changes
110+
111+
The following changes apply to both placeholder and non-placeholder accessors.
112+
113+
#### Buffer accessor changes
114+
115+
```cpp
116+
namespace cl {
117+
namespace sycl {
118+
template <typename dataT, int dimensions, access::mode accessmode,
119+
access::target accessTarget = access::target::global_buffer,
120+
access::placeholder isPlaceholder = access::placeholder::false_t>
121+
class accessor {
122+
public:
123+
...
124+
125+
/* Available only when: ((isPlaceholder == access::placeholder::false_t &&
126+
accessTarget == access::target::host_buffer) || (isPlaceholder ==
127+
access::placeholder::true_t && (accessTarget == access::target::global_buffer
128+
|| accessTarget == access::target::constant_buffer))) && dimensions == 0 */
129+
template <typename AllocatorT>
130+
accessor(buffer<dataT, 1, AllocatorT> &bufferRef,
131+
const property_list &propList = {});
132+
133+
/* Available only when: (isPlaceholder == access::placeholder::false_t &&
134+
(accessTarget == access::target::global_buffer || accessTarget ==
135+
access::target::constant_buffer)) && dimensions == 0 */
136+
template <typename AllocatorT>
137+
accessor(buffer<dataT, 1, AllocatorT> &bufferRef,
138+
handler &commandGroupHandlerRef, const property_list &propList = {});
139+
140+
/* Available only when: ((isPlaceholder == access::placeholder::false_t &&
141+
accessTarget == access::target::host_buffer) || (isPlaceholder ==
142+
access::placeholder::true_t && (accessTarget == access::target::global_buffer
143+
|| accessTarget == access::target::constant_buffer))) && dimensions > 0 */
144+
template <typename AllocatorT>
145+
accessor(buffer<dataT, dimensions, AllocatorT> &bufferRef,
146+
const property_list &propList = {});
147+
148+
/* Available only when: (isPlaceholder == access::placeholder::false_t &&
149+
(accessTarget == access::target::global_buffer || accessTarget ==
150+
access::target::constant_buffer)) && dimensions > 0 */
151+
template <typename AllocatorT>
152+
accessor(buffer<dataT, dimensions, AllocatorT> &bufferRef,
153+
handler &commandGroupHandlerRef, const property_list &propList = {});
154+
155+
/* Available only when: (isPlaceholder == access::placeholder::false_t &&
156+
accessTarget == access::target::host_buffer) || (isPlaceholder ==
157+
access::placeholder::true_t && (accessTarget == access::target::global_buffer
158+
|| accessTarget == access::target::constant_buffer)) && dimensions > 0 */
159+
template <typename AllocatorT>
160+
accessor(buffer<dataT, dimensions, AllocatorT> &bufferRef,
161+
range<dimensions> accessRange, id<dimensions> accessOffset = {},
162+
const property_list &propList = {});
163+
164+
/* Available only when: (isPlaceholder == access::placeholder::false_t &&
165+
(accessTarget == access::target::global_buffer || accessTarget ==
166+
access::target::constant_buffer)) && dimensions > 0 */
167+
template <typename AllocatorT>
168+
accessor(buffer<dataT, dimensions, AllocatorT> &bufferRef,
169+
handler &commandGroupHandlerRef, range<dimensions> accessRange,
170+
id<dimensions> accessOffset = {}, const property_list &propList = {});
171+
172+
...
173+
};
174+
} // namespace sycl
175+
} // namespace cl
176+
```
177+
178+
#### Image accessor changes
179+
180+
```cpp
181+
namespace cl {
182+
namespace sycl {
183+
template <typename dataT, int dimensions, access::mode accessmode,
184+
access::target accessTarget = access::target::global_buffer,
185+
access::placeholder isPlaceholder = access::placeholder::false_t>
186+
class accessor {
187+
public:
188+
...
189+
190+
/* Available only when: accessTarget == access::target::host_image */
191+
template <typename AllocatorT>
192+
accessor(image<dimensions, AllocatorT> &imageRef,
193+
const property_list &propList = {});
194+
195+
/* Available only when: accessTarget == access::target::image */
196+
template <typename AllocatorT>
197+
accessor(image<dimensions, AllocatorT> &imageRef,
198+
handler &commandGroupHandlerRef, const property_list &propList = {});
199+
200+
/* Available only when: accessTarget == access::target::image_array &&
201+
dimensions < 3 */
202+
template <typename AllocatorT>
203+
accessor(image<dimensions + 1, AllocatorT> &imageRef,
204+
handler &commandGroupHandlerRef, const property_list &propList = {});
205+
206+
...
207+
};
208+
} // namespace sycl
209+
} // namespace cl
210+
```
211+
212+
#### Local accessor changes
213+
214+
```cpp
215+
namespace cl {
216+
namespace sycl {
217+
template <typename dataT, int dimensions, access::mode accessmode,
218+
access::target accessTarget = access::target::global_buffer,
219+
access::placeholder isPlaceholder = access::placeholder::false_t>
220+
class accessor {
221+
public:
222+
...
223+
224+
/* Available only when: dimensions == 0 */
225+
accessor(handler &commandGroupHandlerRef,
226+
const property_list &propList = {});
227+
228+
/* Available only when: dimensions > 0 */
229+
accessor(range<dimensions> allocationSize, handler &commandGroupHandlerRef,
230+
const property_list &propList = {});
231+
232+
...
233+
};
234+
} // namespace sycl
235+
} // namespace cl
236+
```

0 commit comments

Comments
 (0)