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 {
58
using value_t = property_value<bar_key>;
59
};
60
61
// (3.)
62
inline constexpr bar_key::value_t bar;
63
64
// (4.)
65
template <> struct is_property_key<bar_key> : std::true_type {};
66
// Replace SYCL_OBJ with the SYCL object to support the property.
67
template <> struct is_property_key_of<bar_key, SYCL_OBJ> : std::true_type {};
68
69
namespace detail {
70
71
// (5.)
72
template <> struct PropertyToKind<bar_key> {
73
static constexpr PropKind Kind = PropKind::Bar;
74
};
75
76
// (6.)
77
template <> struct IsCompileTimeProperty<bar_key> : std::true_type {};
78
79
// (7.)
80
template <> struct PropertyMetaInfo<bar_key::value_t> {
81
static constexpr const char *value = "sycl-bar";
82
static constexpr int value = 5;
83
};
84
85
} // namespace detail
86
} // namespace sycl::ext::oneapi::experimental
87
*******************************************************************************/
88
89
// HOW-TO: Add new runtime property
90
// 1. Add a new enumerator to `sycl::ext::oneapi::detail::PropKind`
91
// representing the new property. Increment
92
// `sycl::ext::oneapi::experimental::detail::PropKind::PropKindSize`
93
// 2. Define property class.
94
// 3. Declare the property key as an alias to the property class. The name of
95
// the key class must be the property name suffixed by `_key`, i.e. for a
96
// property `foo` the class should be named `foo_key`.
97
// 4. Overload the `==` and `!=` operators for the new property class. The
98
// comparison should compare all data members of the property class.
99
// 5. Specialize `sycl::ext::oneapi::experimental::is_property_key` and
100
// `sycl::ext::oneapi::experimental::is_property_key_of` for the property
101
// class.
102
// 6. Specialize `sycl::ext::oneapi::detail::PropertyToKind` for the new
103
// property class. The specialization should have a `Kind` member with the
104
// value equal to the enumerator added in 1.
105
// 7. Specialize `sycl::ext::oneapi::experimental::detail::IsRuntimeProperty`
106
// for the new property class. This specialization should derive from
107
// `std::true_type`.
108
/******************************* EXAMPLE ***************************************
109
------------- sycl/include/sycl/ext/oneapi/properties/property.hpp -------------
110
// (1.)
111
enum PropKind : uint32_t {
112
...
113
Foo,
114
PropKindSize = N + 1, // N was the previous value
115
};
116
---------------------- path/to/new/property/file.hpp ---------------------------
117
namespace sycl::ext::oneapi::experimental {
118
119
// (2.)
120
struct foo {
121
foo(int v) : value(v) {}
122
int value;
123
};
124
125
// 3.
126
using foo_key = foo;
127
128
// (4.)
129
inline bool operator==(const foo &lhs, const foo &rhs) {
130
return lhs.value == rhs.value;
131
}
132
inline bool operator!=(const foo &lhs, const foo &rhs) {
133
return !(lhs == rhs);
134
}
135
136
// (5.)
137
template <> struct is_property_key<foo> : std::true_type {};
138
// Replace SYCL_OBJ with the SYCL object to support the property.
139
template <> struct is_property_key_of<foo, SYCL_OBJ> : std::true_type {};
140
141
namespace detail {
142
143
// (6.)
144
template <> struct PropertyToKind<foo> {
145
static constexpr PropKind Kind = PropKind::Foo;
146
};
147
148
// (7.)
149
template <> struct IsRuntimeProperty<foo> : std::true_type {};
150
151
} // namespace detail
152
} // namespace sycl::ext::oneapi::experimental
153
*******************************************************************************/
154
155
#pragma once
156
157
namespace
sycl
{
158
__SYCL_INLINE_VER_NAMESPACE
(_V1) {
159
namespace
ext {
160
namespace
oneapi {
161
namespace
experimental {
162
namespace
detail {
163
164
// List of all properties.
165
enum
PropKind
: uint32_t {
166
DeviceImageScope
= 0,
167
HostAccess
= 1,
168
InitMode
= 2,
169
ImplementInCSR
= 3,
170
LatencyAnchorID
= 4,
171
LatencyConstraint
= 5,
172
WorkGroupSize
= 6,
173
WorkGroupSizeHint
= 7,
174
SubGroupSize
= 8,
175
DeviceHas
= 9,
176
StreamingInterface
= 10,
// kernel attribute
177
RegisterMapInterface
= 11,
178
Pipelined
= 12,
179
RegisterMap
= 13,
// kernel argument attribute
180
Conduit
= 14,
181
Stable
= 15,
182
BufferLocation
= 16,
183
AddrWidth
= 17,
184
DataWidth
= 18,
185
Latency
= 19,
186
RWMode
= 20,
187
MaxBurst
= 21,
188
WaitRequest
= 22,
189
// PropKindSize must always be the last value.
190
PropKindSize
= 23,
191
};
192
193
// This trait must be specialized for all properties and must have a unique
194
// constexpr PropKind member named Kind.
195
template
<
typename
PropertyT>
struct
PropertyToKind
{};
196
197
// Get unique ID for property.
198
template
<
typename
PropertyT>
struct
PropertyID
{
199
static
constexpr
int
value =
200
static_cast<
int
>
(
PropertyToKind<PropertyT>::Kind
);
201
};
202
203
// Trait for identifying runtime properties.
204
template
<
typename
PropertyT>
struct
IsRuntimeProperty
: std::false_type {};
205
206
// Trait for identifying compile-time properties.
207
template
<
typename
PropertyT>
struct
IsCompileTimeProperty
: std::false_type {};
208
209
// Trait for property compile-time meta names and values.
210
template
<
typename
PropertyT>
struct
PropertyMetaInfo
{
211
// Some properties don't have meaningful compile-time values.
212
// Default to empty, as those will be ignored anyway.
213
static
constexpr
const
char
*name =
""
;
214
static
constexpr std::nullptr_t value =
nullptr
;
215
};
216
217
}
// namespace detail
218
219
template
<
typename
>
struct
is_property_key
: std::false_type {};
220
template
<
typename
,
typename
>
struct
is_property_key_of
: std::false_type {};
221
222
}
// namespace experimental
223
}
// namespace oneapi
224
}
// namespace ext
225
}
// __SYCL_INLINE_VER_NAMESPACE(_V1)
226
}
// namespace sycl
__SYCL_INLINE_VER_NAMESPACE
#define __SYCL_INLINE_VER_NAMESPACE(X)
Definition:
defines_elementary.hpp:11
sycl::_V1::ext::oneapi::experimental::detail::PropKind
PropKind
Definition:
property.hpp:165
sycl::_V1::ext::oneapi::experimental::detail::WorkGroupSize
@ WorkGroupSize
Definition:
property.hpp:172
sycl::_V1::ext::oneapi::experimental::detail::Pipelined
@ Pipelined
Definition:
property.hpp:178
sycl::_V1::ext::oneapi::experimental::detail::ImplementInCSR
@ ImplementInCSR
Definition:
property.hpp:169
sycl::_V1::ext::oneapi::experimental::detail::WorkGroupSizeHint
@ WorkGroupSizeHint
Definition:
property.hpp:173
sycl::_V1::ext::oneapi::experimental::detail::DeviceHas
@ DeviceHas
Definition:
property.hpp:175
sycl::_V1::ext::oneapi::experimental::detail::MaxBurst
@ MaxBurst
Definition:
property.hpp:187
sycl::_V1::ext::oneapi::experimental::detail::RWMode
@ RWMode
Definition:
property.hpp:186
sycl::_V1::ext::oneapi::experimental::detail::InitMode
@ InitMode
Definition:
property.hpp:168
sycl::_V1::ext::oneapi::experimental::detail::DeviceImageScope
@ DeviceImageScope
Definition:
property.hpp:166
sycl::_V1::ext::oneapi::experimental::detail::AddrWidth
@ AddrWidth
Definition:
property.hpp:183
sycl::_V1::ext::oneapi::experimental::detail::StreamingInterface
@ StreamingInterface
Definition:
property.hpp:176
sycl::_V1::ext::oneapi::experimental::detail::LatencyConstraint
@ LatencyConstraint
Definition:
property.hpp:171
sycl::_V1::ext::oneapi::experimental::detail::BufferLocation
@ BufferLocation
Definition:
property.hpp:182
sycl::_V1::ext::oneapi::experimental::detail::LatencyAnchorID
@ LatencyAnchorID
Definition:
property.hpp:170
sycl::_V1::ext::oneapi::experimental::detail::RegisterMap
@ RegisterMap
Definition:
property.hpp:179
sycl::_V1::ext::oneapi::experimental::detail::HostAccess
@ HostAccess
Definition:
property.hpp:167
sycl::_V1::ext::oneapi::experimental::detail::DataWidth
@ DataWidth
Definition:
property.hpp:184
sycl::_V1::ext::oneapi::experimental::detail::RegisterMapInterface
@ RegisterMapInterface
Definition:
property.hpp:177
sycl::_V1::ext::oneapi::experimental::detail::SubGroupSize
@ SubGroupSize
Definition:
property.hpp:174
sycl::_V1::ext::oneapi::experimental::detail::Stable
@ Stable
Definition:
property.hpp:181
sycl::_V1::ext::oneapi::experimental::detail::WaitRequest
@ WaitRequest
Definition:
property.hpp:188
sycl::_V1::ext::oneapi::experimental::detail::Latency
@ Latency
Definition:
property.hpp:185
sycl::_V1::ext::oneapi::experimental::detail::PropKindSize
@ PropKindSize
Definition:
property.hpp:190
sycl::_V1::ext::oneapi::experimental::detail::Conduit
@ Conduit
Definition:
property.hpp:180
sycl
---— Error handling, matching OpenCL plugin semantics.
Definition:
access.hpp:14
sycl::_V1::ext::oneapi::experimental::detail::IsCompileTimeProperty
Definition:
property.hpp:207
sycl::_V1::ext::oneapi::experimental::detail::IsRuntimeProperty
Definition:
property.hpp:204
sycl::_V1::ext::oneapi::experimental::detail::PropertyID
Definition:
property.hpp:198
sycl::_V1::ext::oneapi::experimental::detail::PropertyMetaInfo
Definition:
property.hpp:210
sycl::_V1::ext::oneapi::experimental::detail::PropertyToKind
Definition:
property.hpp:195
sycl::_V1::ext::oneapi::experimental::is_property_key_of
Definition:
property.hpp:220
sycl::_V1::ext::oneapi::experimental::is_property_key
Definition:
property.hpp:219
include
sycl
ext
oneapi
properties
property.hpp
Generated by
1.9.1