Skip to content

[SYCL][DOC] Change device_global property definitions #5691

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 7, 2022
Merged

[SYCL][DOC] Change device_global property definitions #5691

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
517a064
[SYCL][DOC] Change device_global property definitions
steffenlarsen Feb 28, 2022
1f75138
Change copyright notice
steffenlarsen Mar 1, 2022
dcee3c7
Merge branch 'sycl' into steffen/device_global_doc_props
steffenlarsen Mar 3, 2022
c3f9f7a
Fix extension name of dependency
steffenlarsen Mar 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 76 additions & 38 deletions sycl/doc/extensions/proposed/sycl_ext_oneapi_device_global.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ around copyability and constructors/destructors.

== Notice

Copyright (c) 2021 Intel Corporation. All rights reserved.
Copyright (c) 2021 - 2022 Intel Corporation. All rights reserved.

NOTE: Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are
trademarks of The Khronos Group Inc. OpenCL(TM) is a trademark of Apple Inc.
Expand Down Expand Up @@ -79,7 +79,7 @@ Roland Schulz, Intel

This extension is written against the SYCL 2020 specification, revision 3.

It also depends on the `SYCL_EXT_ONEAPI_PROPERTY_LIST` extension.
It also depends on the `SYCL_EXT_ONEAPI_PROPERTIES` extension.

== Overview

Expand Down Expand Up @@ -172,7 +172,7 @@ A `device_global` on a given device maintains its state (address of the allocati
[source,c++]
----
namespace sycl::ext::oneapi::experimental {
template <typename T, typename PropertyListT = property_list<>>
template <typename T, typename PropertyListT = properties<>>
class device_global {
...
----
Expand Down Expand Up @@ -203,7 +203,7 @@ The section below and the table following describe the constructors, member func
----
namespace sycl::ext::oneapi::experimental {

template <typename T, typename PropertyListT = property_list<>>
template <typename T, typename PropertyListT = properties<>>
class device_global {
using subscript_return_t =
std::remove_reference_t<decltype(std::declval<T>()[std::ptrdiff_t{}])>;
Expand Down Expand Up @@ -378,7 +378,7 @@ template<typename propertyT>
static constexpr bool has_property();
----
| Returns true if the `PropertyListT` contains the property specified by `propertyT`. Returns false if it does not.
Available only if `sycl::is_property_of_v<propertyT, sycl::ext::oneapi::experimental::device_global>` is true.
Available only if `sycl::is_property_key_of_v<propertyT, sycl::ext::oneapi::experimental::device_global>` is true.

// --- ROW BREAK ---
a|
Expand All @@ -389,7 +389,7 @@ static constexpr auto get_property();
----
| Returns an object of the class used to represent the value of property `propertyT`.
Must produce a compiler diagnostic if `PropertyListT` does not contain a `propertyT` property.
Available only if `sycl::is_property_of_v<propertyT, sycl::ext::oneapi::experimental::device_global>` is true.
Available only if `sycl::is_property_key_of_v<propertyT, sycl::ext::oneapi::experimental::device_global>` is true.

|===

Expand Down Expand Up @@ -491,8 +491,8 @@ parameter as shown in this example:
----
using namespace sycl::ext::oneapi::experimental;

device_global<MyClass, property_list_t<device_image_scope::value_t>> dm1;
device_global<int[4], property_list_t<host_access::value_t<host_access::access::read>> dm2;
device_global<MyClass, decltype(properties(device_image_scope))> dm1;
device_global<int[4], decltype(properties(host_access_read))> dm2;
----

The following code synopsis shows the set of supported properties, and the
Expand All @@ -502,45 +502,83 @@ following table describes their effect.
----
namespace sycl::ext::oneapi::experimental {

struct device_image_scope {
using value_t = property_value<device_image_scope>;
struct device_image_scope_key {
using value_t = property_value<device_image_scope_key>;
};

struct host_access {
enum class access: /*unspecified*/ {
read,
write,
read_write,
none
};
template<access A>
using value_t = property_value<host_access, std::integral_constant<access, A>>;

struct init_mode {
enum class trigger: /*unspecified*/ {
reprogram,
reset
};
template<trigger T>
using value_t = property_value<init_mode, std::integral_constant<trigger, T>>;
enum class host_access_enum : /* unspecified */ {
read,
write,
read_write,
none
};

struct implement_in_csr {
template <bool Enable>
using value_t = property_value<implement_in_csr, std::bool_constant<Enable>>;
struct host_access_key {
template <host_access_enum Access>
using value_t =
property_value<host_access_key,
std::integral_constant<host_access_enum, Access>>;
};

enum class init_mode_enum : /* unspecified */ {
reprogram,
reset
};

inline constexpr device_image_scope::value_t device_image_scope_v;
struct init_mode_key {
template <init_mode_enum Trigger>
using value_t =
property_value<init_mode_key,
std::integral_constant<init_mode_enum, Trigger>>;
};

template<host_access::access A>
inline constexpr host_access::value_t<A> host_access_v;
struct implement_in_csr_key {
template <bool Enable>
using value_t =
property_value<implement_in_csr_key, std::bool_constant<Enable>>;
};

template<init_mode::trigger T>
inline constexpr init_mode::value_t<T> init_mode_v;
inline constexpr device_image_scope_key::value_t device_image_scope;

template <host_access_enum Access>
inline constexpr host_access_key::value_t<Access> host_access;
inline constexpr host_access_key::value_t<host_access_enum::read>
host_access_read;
inline constexpr host_access_key::value_t<host_access_enum::write>
host_access_write;
inline constexpr host_access_key::value_t<host_access_enum::read_write>
host_access_read_write;
inline constexpr host_access_key::value_t<host_access_enum::none>
host_access_none;

template <init_mode_enum Trigger>
inline constexpr init_mode_key::value_t<Trigger> init_mode;
inline constexpr init_mode_key::value_t<init_mode_enum::reprogram>
init_mode_reprogram;
inline constexpr init_mode_key::value_t<init_mode_enum::reset> init_mode_reset;

template <bool Enable>
inline constexpr implement_in_csr_key::value_t<Enable> implement_in_csr;
inline constexpr implement_in_csr_key::value_t<true> implement_in_csr_on;
inline constexpr implement_in_csr_key::value_t<false> implement_in_csr_off;

template <> struct is_property_key<device_image_scope_key> : std::true_type {};
template <> struct is_property_key<host_access_key> : std::true_type {};
template <> struct is_property_key<init_mode_key> : std::true_type {};
template <> struct is_property_key<implement_in_csr_key> : std::true_type {};

template<bool Enable>
inline constexpr implement_in_csr::value_t<Enable> implement_in_csr_v;
template <typename T, typename PropertyListT>
struct is_property_key_of<device_image_scope_key, device_global<T, PropertyListT>>
: std::true_type {};
template <typename T, typename PropertyListT>
struct is_property_key_of<host_access_key, device_global<T, PropertyListT>>
: std::true_type {};
template <typename T, typename PropertyListT>
struct is_property_key_of<init_mode_key, device_global<T, PropertyListT>>
: std::true_type {};
template <typename T, typename PropertyListT>
struct is_property_key_of<implement_in_csr_key, device_global<T, PropertyListT>>
: std::true_type {};

} // namespace sycl::ext::oneapi::experimental
----
Expand Down Expand Up @@ -1078,7 +1116,7 @@ A sketch of the anticipated constructor interface is:
----
namespace sycl::ext::oneapi::experimental {

template <typename T, typename PropertyListT = property_list<>>
template <typename T, typename PropertyListT = properties<>>
class device_global {
public:
using element_type = std::remove_extent_t<T>;
Expand Down