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 *name = "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 #include <iosfwd> // for nullptr_t
158 #include <stdint.h> // for uint32_t
159 #include <type_traits> // for false_type
160 
161 namespace sycl {
162 inline namespace _V1 {
163 namespace ext {
164 namespace oneapi {
165 namespace experimental {
166 namespace detail {
167 
168 // List of all properties.
169 enum PropKind : uint32_t {
172  InitMode = 2,
180  StreamingInterface = 10, // kernel attribute
182  Pipelined = 12,
183  RegisterMap = 13, // kernel argument attribute
184  Conduit = 14,
185  Stable = 15,
187  AddrWidth = 17,
188  DataWidth = 18,
189  Latency = 19,
190  RWMode = 20,
191  MaxBurst = 21,
193  Alignment = 23,
199  UsesValid = 29,
202  GRFSize = 32,
204  // PropKindSize must always be the last value.
206 };
207 
208 // This trait must be specialized for all properties and must have a unique
209 // constexpr PropKind member named Kind.
210 template <typename PropertyT> struct PropertyToKind {};
211 
212 // Get unique ID for property.
213 template <typename PropertyT> struct PropertyID {
214  static constexpr int value =
215  static_cast<int>(PropertyToKind<PropertyT>::Kind);
216 };
217 
218 // Trait for identifying runtime properties.
219 template <typename PropertyT> struct IsRuntimeProperty : std::false_type {};
220 
221 // Trait for identifying compile-time properties.
222 template <typename PropertyT> struct IsCompileTimeProperty : std::false_type {};
223 
224 // Trait for property compile-time meta names and values.
225 template <typename PropertyT> struct PropertyMetaInfo {
226  // Some properties don't have meaningful compile-time values.
227  // Default to empty, as those will be ignored anyway.
228  static constexpr const char *name = "";
229  static constexpr std::nullptr_t value = nullptr;
230 };
231 
232 } // namespace detail
233 
234 template <typename> struct is_property_key : std::false_type {};
235 template <typename, typename> struct is_property_key_of : std::false_type {};
236 
237 } // namespace experimental
238 } // namespace oneapi
239 } // namespace ext
240 } // namespace _V1
241 } // namespace sycl
sycl::_V1::ext::oneapi::experimental::detail::StreamingInterface
@ StreamingInterface
Definition: property.hpp:180
sycl::_V1::ext::oneapi::experimental::detail::PropKind
PropKind
Definition: property.hpp:169
sycl::_V1::ext::oneapi::experimental::detail::UseRootSync
@ UseRootSync
Definition: property.hpp:200
sycl::_V1::ext::oneapi::experimental::detail::WaitRequest
@ WaitRequest
Definition: property.hpp:192
sycl::_V1::ext::oneapi::experimental::detail::PropertyMetaInfo::value
static constexpr std::nullptr_t value
Definition: property.hpp:229
sycl::_V1::ext::oneapi::experimental::detail::RegisterMapInterface
@ RegisterMapInterface
Definition: property.hpp:181
sycl::_V1::ext::oneapi::experimental::detail::SubGroupSize
@ SubGroupSize
Definition: property.hpp:178
sycl::_V1::ext::oneapi::experimental::detail::IsCompileTimeProperty
Definition: property.hpp:222
sycl::_V1::ext::oneapi::experimental::detail::IsRuntimeProperty
Definition: property.hpp:219
sycl::_V1::ext::oneapi::experimental::detail::UsesValid
@ UsesValid
Definition: property.hpp:199
detail
---— Error handling, matching OpenCL plugin semantics.
Definition: common.hpp:44
sycl::_V1::ext::oneapi::experimental::detail::HostAccess
@ HostAccess
Definition: property.hpp:171
sycl::_V1::ext::oneapi::experimental::detail::WorkGroupSizeHint
@ WorkGroupSizeHint
Definition: property.hpp:177
sycl::_V1::ext::oneapi::experimental::detail::WorkGroupSize
@ WorkGroupSize
Definition: property.hpp:176
sycl
Definition: access.hpp:18
sycl::_V1::ext::oneapi::experimental::detail::PipeProtocol
@ PipeProtocol
Definition: property.hpp:197
sycl::_V1::ext::oneapi::experimental::is_property_key_of
Definition: property.hpp:235
sycl::_V1::ext::oneapi::experimental::detail::RegisterMap
@ RegisterMap
Definition: property.hpp:183
sycl::_V1::ext::oneapi::experimental::detail::ReadyLatency
@ ReadyLatency
Definition: property.hpp:198
sycl::_V1::ext::oneapi::experimental::detail::Pipelined
@ Pipelined
Definition: property.hpp:182
sycl::_V1::ext::oneapi::experimental::detail::BitsPerSymbol
@ BitsPerSymbol
Definition: property.hpp:195
sycl::_V1::ext::oneapi::experimental::detail::RegisterAllocMode
@ RegisterAllocMode
Definition: property.hpp:201
sycl::_V1::ext::oneapi::experimental::detail::DeviceHas
@ DeviceHas
Definition: property.hpp:179
sycl::_V1::ext::oneapi::experimental::detail::RWMode
@ RWMode
Definition: property.hpp:190
sycl::_V1::ext::oneapi::experimental::detail::MaxBurst
@ MaxBurst
Definition: property.hpp:191
sycl::_V1::ext::oneapi::experimental::detail::PropertyID::value
static constexpr int value
Definition: property.hpp:214
sycl::_V1::ext::oneapi::experimental::detail::Conduit
@ Conduit
Definition: property.hpp:184
sycl::_V1::ext::oneapi::experimental::detail::PropKindSize
@ PropKindSize
Definition: property.hpp:205
sycl::_V1::ext::oneapi::experimental::detail::Alignment
@ Alignment
Definition: property.hpp:193
sycl::_V1::ext::oneapi::experimental::detail::GRFSize
@ GRFSize
Definition: property.hpp:202
sycl::_V1::ext::oneapi::experimental::detail::LatencyAnchorID
@ LatencyAnchorID
Definition: property.hpp:174
sycl::_V1::ext::oneapi::experimental::detail::PropertyMetaInfo
Definition: property.hpp:225
sycl::_V1::ext::oneapi::experimental::detail::AddrWidth
@ AddrWidth
Definition: property.hpp:187
sycl::_V1::ext::oneapi::experimental::detail::InitMode
@ InitMode
Definition: property.hpp:172
sycl::_V1::ext::oneapi::experimental::detail::Stable
@ Stable
Definition: property.hpp:185
sycl::_V1::ext::oneapi::experimental::detail::DeviceImageScope
@ DeviceImageScope
Definition: property.hpp:170
sycl::_V1::ext::oneapi::experimental::detail::PropertyID
Definition: property.hpp:213
sycl::_V1::ext::oneapi::experimental::detail::ImplementInCSR
@ ImplementInCSR
Definition: property.hpp:173
sycl::_V1::ext::oneapi::experimental::detail::PropertyMetaInfo::name
static constexpr const char * name
Definition: property.hpp:228
sycl::_V1::ext::oneapi::experimental::detail::FirstSymbolInHigherOrderBit
@ FirstSymbolInHigherOrderBit
Definition: property.hpp:196
sycl::_V1::ext::oneapi::experimental::detail::PropertyToKind
Definition: property.hpp:210
sycl::_V1::ext::oneapi::experimental::detail::LatencyConstraint
@ LatencyConstraint
Definition: property.hpp:175
sycl::_V1::ext::oneapi::experimental::detail::BufferLocation
@ BufferLocation
Definition: property.hpp:186
sycl::_V1::ext::oneapi::experimental::detail::CacheConfig
@ CacheConfig
Definition: property.hpp:194
sycl::_V1::ext::oneapi::experimental::detail::DataWidth
@ DataWidth
Definition: property.hpp:188
sycl::_V1::ext::oneapi::experimental::detail::GRFSizeAutomatic
@ GRFSizeAutomatic
Definition: property.hpp:203
sycl::_V1::ext::oneapi::experimental::is_property_key
Definition: property.hpp:234
sycl::_V1::ext::oneapi::experimental::detail::Latency
@ Latency
Definition: property.hpp:189