DPC++ Runtime
Runtime libraries for oneAPI DPC++
property.hpp
Go to the documentation of this file.
1
//==---------- properties.hpp --- SYCL extension property tooling ----------==//
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
9
// HOW-TO: Add new compile-time property
10
// 1. Add a new enumerator to
11
// `sycl::ext::oneapi::experimental::detail::PropKind` representing the new
12
// property. Increment
13
// `sycl::ext::oneapi::experimental::detail::PropKind::PropKindSize`
14
// 2. Define property key class with `value_t` that must be `property_value`
15
// with the first template argument being the property class itself. The
16
// name of the key class must be the property name suffixed by `_key`, i.e.
17
// for a property `foo` the class should be named `foo_key`.
18
// 3. Add an `inline constexpr` variable in the same namespace as the property
19
// key. The variable should have the same type as `value_t` of the property
20
// class, e.g. for a property `foo`, there should be a definition
21
// `inline constexpr foo_key::value_t foo`.
22
// 4. Specialize `sycl::ext::oneapi::experimental::is_property_key` and
23
// `sycl::ext::oneapi::experimental::is_property_key_of` for the property
24
// key class.
25
// 5. Specialize `sycl::ext::oneapi::experimental::detail::PropertyToKind` for
26
// the new property key class. The specialization should have a `Kind`
27
// member with the value equal to the enumerator added in 1.
28
// 6. Specialize
29
// `sycl::ext::oneapi::experimental::detail::IsCompileTimeProperty` for the
30
// new property key class. This specialization should derive from
31
// `std::true_type`.
32
// 7. If the property needs an LLVM IR attribute, specialize
33
// `sycl::ext::oneapi::experimental::detail::PropertyMetaInfo` for the new
34
// `value_t` of the property key class. The specialization must have a
35
// `static constexpr const char *name` member with a value equal to the
36
// expected LLVM IR attribute name. The common naming scheme for these is
37
// the name of the property with "_" replaced with "-" and "sycl-" appended,
38
// for example a property `foo_bar` would have an LLVM IR attribute name
39
// "sycl-foo-bar". Likewise, the specialization must have a `static
40
// constexpr T value` member where `T` is either an integer, a floating
41
// point, a boolean, an enum, a char, or a `const char *`, or a
42
// `std::nullptr_t`. This will be the value of the generated LLVM IR
43
// attribute. If `std::nullptr_t` is used the attribute will not have a
44
// value.
45
/******************************** EXAMPLE **************************************
46
------------- sycl/include/sycl/ext/oneapi/properties/property.hpp -------------
47
// (1.)
48
enum PropKind : uint32_t {
49
...
50
Bar,
51
PropKindSize = N + 1, // N was the previous value
52
};
53
---------------------- path/to/new/property/file.hpp ---------------------------
54
namespace sycl::ext::oneapi::experimental {
55
56
// (2.)
57
struct bar_key : detail::compile_time_property_key<PropKind::Bar> {
58
using value_t = property_value<bar_key>;
59
};
60
61
// (3.)
62
inline constexpr bar_key::value_t bar;
63
64
// (4.)
65
// Replace SYCL_OBJ with the SYCL object to support the property.
66
template <> struct is_property_key_of<bar_key, SYCL_OBJ> : std::true_type {};
67
68
namespace detail {
69
// (5.)
70
template <> struct PropertyMetaInfo<bar_key::value_t> {
71
static constexpr const char *name = "sycl-bar";
72
static constexpr int value = 5;
73
};
74
75
} // namespace detail
76
} // namespace sycl::ext::oneapi::experimental
77
*******************************************************************************/
78
79
// HOW-TO: Add new runtime property
80
// 1. Add a new enumerator to `sycl::ext::oneapi::detail::PropKind`
81
// representing the new property. Increment
82
// `sycl::ext::oneapi::experimental::detail::PropKind::PropKindSize`
83
// 2. Define property class, inheriting from `detail::run_time_property_key`.
84
// 3. Declare the property key as an alias to the property class. The name of
85
// the key class must be the property name suffixed by `_key`, i.e. for a
86
// property `foo` the class should be named `foo_key`.
87
// 4. Overload the `==` and `!=` operators for the new property class. The
88
// comparison should compare all data members of the property class.
89
// 5. Specialize `sycl::ext::oneapi::experimental::is_property_key_of` for the
90
// property class.
91
/******************************* EXAMPLE ***************************************
92
------------- sycl/include/sycl/ext/oneapi/properties/property.hpp -------------
93
// (1.)
94
enum PropKind : uint32_t {
95
...
96
Foo,
97
PropKindSize = N + 1, // N was the previous value
98
};
99
---------------------- path/to/new/property/file.hpp ---------------------------
100
namespace sycl::ext::oneapi::experimental {
101
102
// (2.)
103
struct foo : detail::run_time_property_key<PropKind::Foo> {
104
foo(int v) : value(v) {}
105
int value;
106
};
107
108
// 3.
109
using foo_key = foo;
110
111
// (4.)
112
inline bool operator==(const foo &lhs, const foo &rhs) {
113
return lhs.value == rhs.value;
114
}
115
inline bool operator!=(const foo &lhs, const foo &rhs) {
116
return !(lhs == rhs);
117
}
118
119
// (5.)
120
// Replace SYCL_OBJ with the SYCL object to support the property.
121
template <> struct is_property_key_of<foo, SYCL_OBJ> : std::true_type {};
122
123
} // namespace sycl::ext::oneapi::experimental
124
*******************************************************************************/
125
126
#pragma once
127
128
#include <iosfwd>
// for nullptr_t
129
#include <stdint.h>
// for uint32_t
130
#include <type_traits>
// for false_type
131
132
namespace
sycl
{
133
inline
namespace
_V1 {
134
namespace
ext {
135
namespace
oneapi {
136
namespace
experimental {
137
namespace
detail {
138
139
// List of all properties.
140
enum
PropKind
: uint32_t {
141
DeviceImageScope
= 0,
142
HostAccess
= 1,
143
InitMode
= 2,
144
ImplementInCSR
= 3,
145
LatencyAnchorID
= 4,
146
LatencyConstraint
= 5,
147
WorkGroupSize
= 6,
148
WorkGroupSizeHint
= 7,
149
SubGroupSize
= 8,
150
DeviceHas
= 9,
151
StreamingInterface
= 10,
// kernel attribute
152
RegisterMapInterface
= 11,
153
Pipelined
= 12,
154
RegisterMap
= 13,
// kernel argument attribute
155
Conduit
= 14,
156
Stable
= 15,
157
BufferLocation
= 16,
158
AddrWidth
= 17,
159
DataWidth
= 18,
160
Latency
= 19,
161
RWMode
= 20,
162
MaxBurst
= 21,
163
WaitRequest
= 22,
164
Alignment
= 23,
165
CacheConfig
= 24,
166
BitsPerSymbol
= 25,
167
FirstSymbolInHigherOrderBit
= 26,
168
PipeProtocol
= 27,
169
ReadyLatency
= 28,
170
UsesValid
= 29,
171
UseRootSync
= 30,
172
RegisterAllocMode
= 31,
173
GRFSize
= 32,
174
GRFSizeAutomatic
= 33,
175
Resource
= 34,
176
NumBanks
= 35,
177
StrideSize
= 36,
178
WordSize
= 37,
179
BiDirectionalPorts
= 38,
180
Clock2x
= 39,
181
RAMStitching
= 40,
182
MaxPrivateCopies
= 41,
183
NumReplicates
= 42,
184
Datapath
= 43,
185
ESIMDL1CacheHint
= 44,
186
ESIMDL2CacheHint
= 45,
187
ESIMDL3CacheHint
= 46,
188
UsmKind
= 47,
189
CacheControlReadHint
= 48,
190
CacheControlReadAssertion
= 49,
191
CacheControlWrite
= 50,
192
BuildOptions
= 51,
193
BuildLog
= 52,
194
FloatingPointControls
= 53,
195
DataPlacement
= 54,
196
ContiguousMemory
= 55,
197
FullGroup
= 56,
198
Naive
= 57,
199
WorkGroupProgress
= 58,
200
SubGroupProgress
= 59,
201
WorkItemProgress
= 60,
202
NDRangeKernel
= 61,
203
SingleTaskKernel
= 62,
204
IndirectlyCallable
= 63,
205
CallsIndirectly
= 64,
206
InputDataPlacement
= 65,
207
OutputDataPlacement
= 66,
208
IncludeFiles
= 67,
209
RegisteredKernelNames
= 68,
210
ClusterLaunch
= 69,
211
FPGACluster
= 70,
212
Balanced
= 71,
213
InvocationCapacity
= 72,
214
ResponseCapacity
= 73,
215
// PropKindSize must always be the last value.
216
PropKindSize
= 74,
217
};
218
219
struct
property_key_base_tag
{};
220
struct
compile_time_property_key_base_tag
:
property_key_base_tag
{};
221
222
template
<PropKind Kind_>
struct
run_time_property_key
:
property_key_base_tag
{
223
protected
:
224
static
constexpr
PropKind
Kind
= Kind_;
225
226
template
<
typename
T>
227
friend
struct
PropertyToKind
;
228
};
229
230
template
<PropKind Kind_>
231
struct
compile_time_property_key
:
compile_time_property_key_base_tag
{
232
protected
:
233
static
constexpr
PropKind
Kind
= Kind_;
234
235
template
<
typename
T>
236
friend
struct
PropertyToKind
;
237
};
238
239
// This trait must be specialized for all properties and must have a unique
240
// constexpr PropKind member named Kind.
241
template
<
typename
PropertyT>
struct
PropertyToKind
{
242
static
constexpr
PropKind
Kind
= PropertyT::Kind;
243
};
244
245
// Get unique ID for property.
246
template
<
typename
PropertyT>
struct
PropertyID
{
247
static
constexpr
int
value
=
248
static_cast<
int
>
(
PropertyToKind<PropertyT>::Kind
);
249
};
250
251
// Trait for identifying runtime properties.
252
template
<
typename
PropertyT>
253
struct
IsRuntimeProperty
254
: std::bool_constant<
255
std::is_base_of_v<property_key_base_tag, PropertyT> &&
256
!std::is_base_of_v<compile_time_property_key_base_tag, PropertyT>> {};
257
258
// Trait for identifying compile-time properties.
259
template
<
typename
PropertyT>
260
struct
IsCompileTimeProperty
261
: std::bool_constant<
262
std::is_base_of_v<property_key_base_tag, PropertyT> &&
263
std::is_base_of_v<compile_time_property_key_base_tag, PropertyT>> {};
264
265
// Trait for property compile-time meta names and values.
266
template
<
typename
PropertyT>
struct
PropertyMetaInfo
{
267
// Some properties don't have meaningful compile-time values.
268
// Default to empty, as those will be ignored anyway.
269
static
constexpr
const
char
*
name
=
""
;
270
static
constexpr std::nullptr_t
value
=
nullptr
;
271
};
272
273
template
<
typename
>
struct
HasCompileTimeEffect
: std::false_type {};
274
275
}
// namespace detail
276
277
template
<
typename
T>
278
struct
is_property_key
279
: std::bool_constant<std::is_base_of_v<detail::property_key_base_tag, T>> {
280
};
281
template
<
typename
,
typename
>
struct
is_property_key_of
: std::false_type {};
282
283
}
// namespace experimental
284
}
// namespace oneapi
285
}
// namespace ext
286
}
// namespace _V1
287
}
// namespace sycl
sycl::_V1::ext::oneapi::experimental::detail::PropKind
PropKind
Definition:
property.hpp:140
sycl::_V1::ext::oneapi::experimental::detail::ESIMDL1CacheHint
@ ESIMDL1CacheHint
Definition:
property.hpp:185
sycl::_V1::ext::oneapi::experimental::detail::UsesValid
@ UsesValid
Definition:
property.hpp:170
sycl::_V1::ext::oneapi::experimental::detail::WorkGroupSize
@ WorkGroupSize
Definition:
property.hpp:147
sycl::_V1::ext::oneapi::experimental::detail::MaxPrivateCopies
@ MaxPrivateCopies
Definition:
property.hpp:182
sycl::_V1::ext::oneapi::experimental::detail::Pipelined
@ Pipelined
Definition:
property.hpp:153
sycl::_V1::ext::oneapi::experimental::detail::Datapath
@ Datapath
Definition:
property.hpp:184
sycl::_V1::ext::oneapi::experimental::detail::IncludeFiles
@ IncludeFiles
Definition:
property.hpp:208
sycl::_V1::ext::oneapi::experimental::detail::InputDataPlacement
@ InputDataPlacement
Definition:
property.hpp:206
sycl::_V1::ext::oneapi::experimental::detail::FloatingPointControls
@ FloatingPointControls
Definition:
property.hpp:194
sycl::_V1::ext::oneapi::experimental::detail::ImplementInCSR
@ ImplementInCSR
Definition:
property.hpp:144
sycl::_V1::ext::oneapi::experimental::detail::BuildLog
@ BuildLog
Definition:
property.hpp:193
sycl::_V1::ext::oneapi::experimental::detail::WorkGroupSizeHint
@ WorkGroupSizeHint
Definition:
property.hpp:148
sycl::_V1::ext::oneapi::experimental::detail::Resource
@ Resource
Definition:
property.hpp:175
sycl::_V1::ext::oneapi::experimental::detail::DeviceHas
@ DeviceHas
Definition:
property.hpp:150
sycl::_V1::ext::oneapi::experimental::detail::CallsIndirectly
@ CallsIndirectly
Definition:
property.hpp:205
sycl::_V1::ext::oneapi::experimental::detail::NumBanks
@ NumBanks
Definition:
property.hpp:176
sycl::_V1::ext::oneapi::experimental::detail::OutputDataPlacement
@ OutputDataPlacement
Definition:
property.hpp:207
sycl::_V1::ext::oneapi::experimental::detail::FullGroup
@ FullGroup
Definition:
property.hpp:197
sycl::_V1::ext::oneapi::experimental::detail::MaxBurst
@ MaxBurst
Definition:
property.hpp:162
sycl::_V1::ext::oneapi::experimental::detail::RWMode
@ RWMode
Definition:
property.hpp:161
sycl::_V1::ext::oneapi::experimental::detail::InitMode
@ InitMode
Definition:
property.hpp:143
sycl::_V1::ext::oneapi::experimental::detail::PipeProtocol
@ PipeProtocol
Definition:
property.hpp:168
sycl::_V1::ext::oneapi::experimental::detail::RAMStitching
@ RAMStitching
Definition:
property.hpp:181
sycl::_V1::ext::oneapi::experimental::detail::BiDirectionalPorts
@ BiDirectionalPorts
Definition:
property.hpp:179
sycl::_V1::ext::oneapi::experimental::detail::CacheControlReadAssertion
@ CacheControlReadAssertion
Definition:
property.hpp:190
sycl::_V1::ext::oneapi::experimental::detail::ResponseCapacity
@ ResponseCapacity
Definition:
property.hpp:214
sycl::_V1::ext::oneapi::experimental::detail::DeviceImageScope
@ DeviceImageScope
Definition:
property.hpp:141
sycl::_V1::ext::oneapi::experimental::detail::SubGroupProgress
@ SubGroupProgress
Definition:
property.hpp:200
sycl::_V1::ext::oneapi::experimental::detail::ESIMDL2CacheHint
@ ESIMDL2CacheHint
Definition:
property.hpp:186
sycl::_V1::ext::oneapi::experimental::detail::AddrWidth
@ AddrWidth
Definition:
property.hpp:158
sycl::_V1::ext::oneapi::experimental::detail::StreamingInterface
@ StreamingInterface
Definition:
property.hpp:151
sycl::_V1::ext::oneapi::experimental::detail::FirstSymbolInHigherOrderBit
@ FirstSymbolInHigherOrderBit
Definition:
property.hpp:167
sycl::_V1::ext::oneapi::experimental::detail::UseRootSync
@ UseRootSync
Definition:
property.hpp:171
sycl::_V1::ext::oneapi::experimental::detail::SingleTaskKernel
@ SingleTaskKernel
Definition:
property.hpp:203
sycl::_V1::ext::oneapi::experimental::detail::IndirectlyCallable
@ IndirectlyCallable
Definition:
property.hpp:204
sycl::_V1::ext::oneapi::experimental::detail::ContiguousMemory
@ ContiguousMemory
Definition:
property.hpp:196
sycl::_V1::ext::oneapi::experimental::detail::WordSize
@ WordSize
Definition:
property.hpp:178
sycl::_V1::ext::oneapi::experimental::detail::LatencyConstraint
@ LatencyConstraint
Definition:
property.hpp:146
sycl::_V1::ext::oneapi::experimental::detail::BufferLocation
@ BufferLocation
Definition:
property.hpp:157
sycl::_V1::ext::oneapi::experimental::detail::RegisteredKernelNames
@ RegisteredKernelNames
Definition:
property.hpp:209
sycl::_V1::ext::oneapi::experimental::detail::ESIMDL3CacheHint
@ ESIMDL3CacheHint
Definition:
property.hpp:187
sycl::_V1::ext::oneapi::experimental::detail::LatencyAnchorID
@ LatencyAnchorID
Definition:
property.hpp:145
sycl::_V1::ext::oneapi::experimental::detail::Clock2x
@ Clock2x
Definition:
property.hpp:180
sycl::_V1::ext::oneapi::experimental::detail::Naive
@ Naive
Definition:
property.hpp:198
sycl::_V1::ext::oneapi::experimental::detail::RegisterAllocMode
@ RegisterAllocMode
Definition:
property.hpp:172
sycl::_V1::ext::oneapi::experimental::detail::CacheControlWrite
@ CacheControlWrite
Definition:
property.hpp:191
sycl::_V1::ext::oneapi::experimental::detail::InvocationCapacity
@ InvocationCapacity
Definition:
property.hpp:213
sycl::_V1::ext::oneapi::experimental::detail::RegisterMap
@ RegisterMap
Definition:
property.hpp:154
sycl::_V1::ext::oneapi::experimental::detail::HostAccess
@ HostAccess
Definition:
property.hpp:142
sycl::_V1::ext::oneapi::experimental::detail::GRFSize
@ GRFSize
Definition:
property.hpp:173
sycl::_V1::ext::oneapi::experimental::detail::BuildOptions
@ BuildOptions
Definition:
property.hpp:192
sycl::_V1::ext::oneapi::experimental::detail::ClusterLaunch
@ ClusterLaunch
Definition:
property.hpp:210
sycl::_V1::ext::oneapi::experimental::detail::DataWidth
@ DataWidth
Definition:
property.hpp:159
sycl::_V1::ext::oneapi::experimental::detail::UsmKind
@ UsmKind
Definition:
property.hpp:188
sycl::_V1::ext::oneapi::experimental::detail::RegisterMapInterface
@ RegisterMapInterface
Definition:
property.hpp:152
sycl::_V1::ext::oneapi::experimental::detail::CacheControlReadHint
@ CacheControlReadHint
Definition:
property.hpp:189
sycl::_V1::ext::oneapi::experimental::detail::SubGroupSize
@ SubGroupSize
Definition:
property.hpp:149
sycl::_V1::ext::oneapi::experimental::detail::StrideSize
@ StrideSize
Definition:
property.hpp:177
sycl::_V1::ext::oneapi::experimental::detail::GRFSizeAutomatic
@ GRFSizeAutomatic
Definition:
property.hpp:174
sycl::_V1::ext::oneapi::experimental::detail::NumReplicates
@ NumReplicates
Definition:
property.hpp:183
sycl::_V1::ext::oneapi::experimental::detail::FPGACluster
@ FPGACluster
Definition:
property.hpp:211
sycl::_V1::ext::oneapi::experimental::detail::CacheConfig
@ CacheConfig
Definition:
property.hpp:165
sycl::_V1::ext::oneapi::experimental::detail::DataPlacement
@ DataPlacement
Definition:
property.hpp:195
sycl::_V1::ext::oneapi::experimental::detail::BitsPerSymbol
@ BitsPerSymbol
Definition:
property.hpp:166
sycl::_V1::ext::oneapi::experimental::detail::Stable
@ Stable
Definition:
property.hpp:156
sycl::_V1::ext::oneapi::experimental::detail::WorkGroupProgress
@ WorkGroupProgress
Definition:
property.hpp:199
sycl::_V1::ext::oneapi::experimental::detail::WaitRequest
@ WaitRequest
Definition:
property.hpp:163
sycl::_V1::ext::oneapi::experimental::detail::Alignment
@ Alignment
Definition:
property.hpp:164
sycl::_V1::ext::oneapi::experimental::detail::Latency
@ Latency
Definition:
property.hpp:160
sycl::_V1::ext::oneapi::experimental::detail::NDRangeKernel
@ NDRangeKernel
Definition:
property.hpp:202
sycl::_V1::ext::oneapi::experimental::detail::ReadyLatency
@ ReadyLatency
Definition:
property.hpp:169
sycl::_V1::ext::oneapi::experimental::detail::WorkItemProgress
@ WorkItemProgress
Definition:
property.hpp:201
sycl::_V1::ext::oneapi::experimental::detail::PropKindSize
@ PropKindSize
Definition:
property.hpp:216
sycl::_V1::ext::oneapi::experimental::detail::Conduit
@ Conduit
Definition:
property.hpp:155
sycl::_V1::ext::oneapi::experimental::detail::Balanced
@ Balanced
Definition:
property.hpp:212
sycl
Definition:
access.hpp:18
sycl::_V1::ext::oneapi::experimental::detail::HasCompileTimeEffect
Definition:
property.hpp:273
sycl::_V1::ext::oneapi::experimental::detail::IsCompileTimeProperty
Definition:
property.hpp:263
sycl::_V1::ext::oneapi::experimental::detail::IsRuntimeProperty
Definition:
property.hpp:256
sycl::_V1::ext::oneapi::experimental::detail::PropertyID
Definition:
property.hpp:246
sycl::_V1::ext::oneapi::experimental::detail::PropertyID::value
static constexpr int value
Definition:
property.hpp:247
sycl::_V1::ext::oneapi::experimental::detail::PropertyMetaInfo
Definition:
property.hpp:266
sycl::_V1::ext::oneapi::experimental::detail::PropertyMetaInfo::value
static constexpr std::nullptr_t value
Definition:
property.hpp:270
sycl::_V1::ext::oneapi::experimental::detail::PropertyMetaInfo::name
static constexpr const char * name
Definition:
property.hpp:269
sycl::_V1::ext::oneapi::experimental::detail::PropertyToKind
Definition:
property.hpp:241
sycl::_V1::ext::oneapi::experimental::detail::PropertyToKind::Kind
static constexpr PropKind Kind
Definition:
property.hpp:242
sycl::_V1::ext::oneapi::experimental::detail::compile_time_property_key_base_tag
Definition:
property.hpp:220
sycl::_V1::ext::oneapi::experimental::detail::compile_time_property_key
Definition:
property.hpp:231
sycl::_V1::ext::oneapi::experimental::detail::compile_time_property_key::Kind
static constexpr PropKind Kind
Definition:
property.hpp:233
sycl::_V1::ext::oneapi::experimental::detail::property_key_base_tag
Definition:
property.hpp:219
sycl::_V1::ext::oneapi::experimental::detail::run_time_property_key
Definition:
property.hpp:222
sycl::_V1::ext::oneapi::experimental::detail::run_time_property_key::Kind
static constexpr PropKind Kind
Definition:
property.hpp:224
sycl::_V1::ext::oneapi::experimental::is_property_key_of
Definition:
property.hpp:281
sycl::_V1::ext::oneapi::experimental::is_property_key
Definition:
property.hpp:279
include
sycl
ext
oneapi
properties
property.hpp
Generated by
1.9.1