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 /******************************** EXAMPLE **************************************
33 ------------- sycl/include/sycl/ext/oneapi/properties/property.hpp -------------
34 // (1.)
35 enum PropKind : uint32_t {
36  ...
37  Bar,
38  PropKindSize = N + 1, // N was the previous value
39 };
40 ---------------------- path/to/new/property/file.hpp ---------------------------
41 namespace sycl::ext::oneapi::experimental {
42 
43 // (2.)
44 struct bar_key {
45  using value_t = property_value<bar_key>;
46 };
47 
48 // (3.)
49 inline constexpr bar_key::value_t bar;
50 
51 // (4.)
52 template <> struct is_property_key<bar_key> : std::true_type {};
53 // Replace SYCL_OBJ with the SYCL object to support the property.
54 template <> struct is_property_key_of<bar_key, SYCL_OBJ> : std::true_type {};
55 
56 namespace detail {
57 
58 // (5.)
59 template <> struct PropertyToKind<bar_key> {
60  static constexpr PropKind Kind = PropKind::Bar;
61 };
62 
63 // (6.)
64 template <> struct IsCompileTimeProperty<bar_key> : std::true_type {};
65 
66 } // namespace detail
67 } // namespace sycl::ext::oneapi::experimental
68 *******************************************************************************/
69 
70 // HOW-TO: Add new runtime property
71 // 1. Add a new enumerator to `sycl::ext::oneapi::detail::PropKind`
72 // representing the new property. Increment
73 // `sycl::ext::oneapi::experimental::detail::PropKind::PropKindSize`
74 // 2. Define property class.
75 // 3. Declare the property key as an alias to the property class. The name of
76 // the key class must be the property name suffixed by `_key`, i.e. for a
77 // property `foo` the class should be named `foo_key`.
78 // 4. Overload the `==` and `!=` operators for the new property class. The
79 // comparison should compare all data members of the property class.
80 // 5. Specialize `sycl::ext::oneapi::experimental::is_property_key` and
81 // `sycl::ext::oneapi::experimental::is_property_key_of` for the property
82 // class.
83 // 6. Specialize `sycl::ext::oneapi::detail::PropertyToKind` for the new
84 // property class. The specialization should have a `Kind` member with the
85 // value equal to the enumerator added in 1.
86 // 7. Specialize `sycl::ext::oneapi::experimental::detail::IsRuntimeProperty`
87 // for the new property class. This specialization should derive from
88 // `std::true_type`.
89 /******************************* EXAMPLE ***************************************
90 ------------- sycl/include/sycl/ext/oneapi/properties/property.hpp -------------
91 // (1.)
92 enum PropKind : uint32_t {
93  ...
94  Foo,
95  PropKindSize = N + 1, // N was the previous value
96 };
97 ---------------------- path/to/new/property/file.hpp ---------------------------
98 namespace sycl::ext::oneapi::experimental {
99 
100 // (2.)
101 struct foo {
102  foo(int v) : value(v) {}
103  int value;
104 };
105 
106 // 3.
107 using foo_key = foo;
108 
109 // (4.)
110 inline bool operator==(const foo &lhs, const foo &rhs) {
111  return lhs.value == rhs.value;
112 }
113 inline bool operator!=(const foo &lhs, const foo &rhs) {
114  return !(lhs == rhs);
115 }
116 
117 // (5.)
118 template <> struct is_property_key<foo> : std::true_type {};
119 // Replace SYCL_OBJ with the SYCL object to support the property.
120 template <> struct is_property_key_of<foo, SYCL_OBJ> : std::true_type {};
121 
122 namespace detail {
123 
124 // (6.)
125 template <> struct PropertyToKind<foo> {
126  static constexpr PropKind Kind = PropKind::Foo;
127 };
128 
129 // (7.)
130 template <> struct IsRuntimeProperty<foo> : std::true_type {};
131 
132 } // namespace detail
133 } // namespace sycl::ext::oneapi::experimental
134 *******************************************************************************/
135 
136 #pragma once
137 
139 namespace sycl {
140 namespace ext {
141 namespace oneapi {
142 namespace experimental {
143 namespace detail {
144 
145 // List of all properties.
146 enum PropKind : uint32_t {
149  InitMode = 2,
154 };
155 
156 // This trait must be specialized for all properties and must have a unique
157 // constexpr PropKind member named Kind.
158 template <typename PropertyT> struct PropertyToKind {};
159 
160 // Get unique ID for property.
161 template <typename PropertyT> struct PropertyID {
162  static constexpr int value =
163  static_cast<int>(PropertyToKind<PropertyT>::Kind);
164 };
165 
166 // Trait for identifying runtime properties.
167 template <typename PropertyT> struct IsRuntimeProperty : std::false_type {};
168 
169 // Trait for identifying compile-time properties.
170 template <typename PropertyT> struct IsCompileTimeProperty : std::false_type {};
171 
172 } // namespace detail
173 
174 template <typename> struct is_property_key : std::false_type {};
175 template <typename, typename> struct is_property_key_of : std::false_type {};
176 
177 } // namespace experimental
178 } // namespace oneapi
179 } // namespace ext
180 } // namespace sycl
181 } // __SYCL_INLINE_NAMESPACE(cl)
cl::sycl::ext::oneapi::experimental::detail::PropKind
PropKind
Definition: property.hpp:146
cl::sycl::ext::oneapi::experimental::detail::HostAccess
@ HostAccess
Definition: property.hpp:148
cl::sycl::ext::oneapi::experimental::is_property_key
Definition: property.hpp:174
cl::sycl::ext::oneapi::experimental::detail::IsRuntimeProperty
Definition: property.hpp:167
cl::sycl::ext::oneapi::experimental::detail::DeviceImageScope
@ DeviceImageScope
Definition: property.hpp:147
cl::sycl::ext::oneapi::experimental::is_property_key_of
Definition: property.hpp:175
cl::sycl::ext::oneapi::experimental::detail::PropertyID
Definition: property.hpp:161
sycl
Definition: invoke_simd.hpp:68
cl::sycl::ext::oneapi::experimental::detail::IsCompileTimeProperty
Definition: property.hpp:170
cl::sycl::ext::oneapi::experimental::detail::LatencyAnchorID
@ LatencyAnchorID
Definition: property.hpp:151
cl::sycl::ext::oneapi::experimental::detail::PropertyToKind
Definition: property.hpp:158
cl
We provide new interfaces for matrix muliply in this patch:
Definition: access.hpp:13
cl::sycl::ext::oneapi::experimental::detail::InitMode
@ InitMode
Definition: property.hpp:149
cl::sycl::ext::oneapi::experimental::detail::ImplementInCSR
@ ImplementInCSR
Definition: property.hpp:150
cl::sycl::ext::oneapi::experimental::detail::PropKindSize
@ PropKindSize
Definition: property.hpp:153
cl::sycl::ext::oneapi::experimental::detail::LatencyConstraint
@ LatencyConstraint
Definition: property.hpp:152
__SYCL_INLINE_NAMESPACE
#define __SYCL_INLINE_NAMESPACE(X)
Definition: defines_elementary.hpp:12