From 96f1e0edb0863f30c600711dc5f8a12e19b0b192 Mon Sep 17 00:00:00 2001 From: Ronan Keryell Date: Tue, 21 Mar 2023 18:10:30 -0700 Subject: [PATCH 01/23] Allow recursion in kernels in the context of constant evaluation This should address https://github.com/KhronosGroup/SYCL-Docs/issues/267 --- adoc/chapters/device_compiler.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 913096cd4..a61e7756d 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -171,7 +171,8 @@ these restrictions: * Exception-handling cannot be used inside a <>. [code]#noexcept# is allowed. - * Recursion is not allowed in a <>. + * Recursion is not allowed in a <> except in a + constant evaluation. * Variables with thread storage duration ([code]#thread_local# storage class specifier) are not allowed to be odr-used in a <>. From bdc8feaf3278bdce2026967188f1010fa024cd31 Mon Sep 17 00:00:00 2001 From: Ronan Keryell Date: Wed, 17 May 2023 16:24:21 -0700 Subject: [PATCH 02/23] Waiver on manifestly constant-evaluation in kernel code In the case of a manifestly constant-evaluated expression or conversion, any code accepted by the C++ standard in this case is also accepted in SYCL device function. --- adoc/chapters/device_compiler.adoc | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index a61e7756d..b74e3d5a1 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -171,8 +171,7 @@ these restrictions: * Exception-handling cannot be used inside a <>. [code]#noexcept# is allowed. - * Recursion is not allowed in a <> except in a - constant evaluation. + * Recursion is not allowed in a <>. * Variables with thread storage duration ([code]#thread_local# storage class specifier) are not allowed to be odr-used in a <>. @@ -180,11 +179,18 @@ these restrictions: <>, must be [code]#const# or [code]#constexpr# and zero-initialized or constant-initialized. +In the case of a manifestly constant-evaluated expression or +conversion, any code accepted by the C++ standard in this case is also +accepted in SYCL <>. + [NOTE] ==== Amongst other things, this restriction makes it illegal for a <> to access a global variable that isn't [code]#const# or [code]#constexpr#. + +The restriction waiver in manifestly constant-evaluated expressions +allows any kind of meta-programming in a <>. ==== * The rules for kernels apply to both the kernel function objects From 2583115dd46d7b2f73bfe0d5f18d79107afd4fef Mon Sep 17 00:00:00 2001 From: Victor Perez Date: Thu, 1 Aug 2024 17:06:50 +0100 Subject: [PATCH 03/23] Add missing `multi_ptr` aliases for `access::address_space::generic` Add `[decorated_|raw_]generic_ptr` aliases definitions. These aliases were previously mentioned in the text (https://github.com/KhronosGroup/SYCL-Docs/blob/d314fbc9aead30704dd1f4d35db4b55b93bce7b0/adoc/chapters/architecture.adoc?plain=1#L1021), but their definitions were missing where their homologous are defined. Signed-off-by: Victor Perez --- adoc/config/rouge/lib/rouge/lexers/sycl.rb | 1 + adoc/headers/pointer.h | 15 +++++++++++++++ 2 files changed, 16 insertions(+) diff --git a/adoc/config/rouge/lib/rouge/lexers/sycl.rb b/adoc/config/rouge/lib/rouge/lexers/sycl.rb index 657d1f24e..d8e3ca6cd 100644 --- a/adoc/config/rouge/lib/rouge/lexers/sycl.rb +++ b/adoc/config/rouge/lib/rouge/lexers/sycl.rb @@ -312,6 +312,7 @@ class Sycl < Cpp context_bound cpu_selector decorated_constant_ptr + decorated_generic_ptr decorated_global_ptr decorated_local_ptr decorated_private_ptr diff --git a/adoc/headers/pointer.h b/adoc/headers/pointer.h index 989059149..7c472332b 100644 --- a/adoc/headers/pointer.h +++ b/adoc/headers/pointer.h @@ -30,6 +30,11 @@ template ; +template +using generic_ptr = + multi_ptr; + // Template specialization aliases for different pointer address spaces. // The interface exposes non-decorated pointer while keeping the // address space information internally. @@ -48,6 +53,11 @@ using raw_private_ptr = multi_ptr; +template +using raw_generic_ptr = + multi_ptr; + // Template specialization aliases for different pointer address spaces. // The interface exposes decorated pointer. @@ -66,4 +76,9 @@ using decorated_private_ptr = multi_ptr; +template +using decorated_generic_ptr = + multi_ptr; + } // namespace sycl From b393ab61cbbad38aa1078d83076e85d8c2147a6c Mon Sep 17 00:00:00 2001 From: "Larsen, Steffen" Date: Fri, 16 Aug 2024 00:46:32 -0700 Subject: [PATCH 04/23] Undeprecate legacy multi_ptr The legacy decoration for multi_ptr has been made the default template argument of the decoration in multi_ptr to bridge the gap between SYCL 1.2.1 and SYCL 2020 multi_ptr interfaces. However, the legacy decoration and the specialization of multi_ptr with the decoration is deprecated with SYCL 2020. This is confusing to users as they may easily run into deprecation warnings simply due to not specifying the decoration. This commit proposes that we remove the deprecation of legacy in SYCL 2020. Signed-off-by: Larsen, Steffen --- adoc/chapters/programming_interface.adoc | 1 - adoc/headers/multipointer.h | 2 +- adoc/headers/multipointerlegacy.h | 2 -- 3 files changed, 1 insertion(+), 4 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index aaa0c8e0b..61792b79d 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -9138,7 +9138,6 @@ For interoperability with the <>, users should rely on types exposed by the decorated version. If the value of [code]#access::decorated# is [code]#access::decorated::legacy#, the 1.2.1 interface is exposed. -This interface is deprecated. The template traits [code]#remove_decoration# and type alias [code]#remove_decoration_t# retrieve the non-decorated pointer or reference from diff --git a/adoc/headers/multipointer.h b/adoc/headers/multipointer.h index c9e727b84..32cb6aac6 100644 --- a/adoc/headers/multipointer.h +++ b/adoc/headers/multipointer.h @@ -15,7 +15,7 @@ enum class address_space : /* unspecified */ { enum class decorated : /* unspecified */ { no, yes, - legacy // Deprecated in SYCL 2020 + legacy }; } // namespace access diff --git a/adoc/headers/multipointerlegacy.h b/adoc/headers/multipointerlegacy.h index f413cad0b..0d510730f 100644 --- a/adoc/headers/multipointerlegacy.h +++ b/adoc/headers/multipointerlegacy.h @@ -4,7 +4,6 @@ namespace sycl { // Legacy interface, inherited from 1.2.1. -// Deprecated. template class [[deprecated]] multi_ptr { public: @@ -162,7 +161,6 @@ class [[deprecated]] multi_ptr { }; // Legacy interface, inherited from 1.2.1. -// Deprecated. // Specialization of multi_ptr for void and const void // VoidType can be either void or const void template From f495a777842e9f21d5b2f718be65d1fcbb2e0975 Mon Sep 17 00:00:00 2001 From: "Larsen, Steffen" Date: Thu, 29 Aug 2024 02:57:35 -0700 Subject: [PATCH 05/23] Remove alias deprecation note Signed-off-by: Larsen, Steffen --- adoc/chapters/programming_interface.adoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 61792b79d..e95b3cb70 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -9846,10 +9846,6 @@ below. include::{header_dir}/pointer.h[lines=4..-1] ---- -Note that using [code]#global_ptr#, [code]#local_ptr#, [code]#constant_ptr# or -[code]#private_ptr# without specifying the decoration is deprecated. -The default argument is provided for compatibility with 1.2.1. - [[subsec:samplers]] === Image samplers From 83732050907f3726caa784188d3d0dac846cf96e Mon Sep 17 00:00:00 2001 From: "Larsen, Steffen" Date: Tue, 10 Sep 2024 09:23:23 -0700 Subject: [PATCH 06/23] Remove deprecation entry in changelog Signed-off-by: Larsen, Steffen --- adoc/chapters/what_changed.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/adoc/chapters/what_changed.adoc b/adoc/chapters/what_changed.adoc index 5085b0d3f..bb96a2070 100644 --- a/adoc/chapters/what_changed.adoc +++ b/adoc/chapters/what_changed.adoc @@ -381,7 +381,6 @@ Changes in [code]#multi_ptr# interface: Returned pointer and reference are not annotated by an address space; ** interface exposing decorated types. Returned pointer and reference are annotated by an address space; - ** legacy 1.2.1 interface (deprecated). * deprecation of the 1.2.1 interface; * deprecation of [code]#constant_ptr#; * [code]#global_ptr#, [code]#local_ptr# and [code]#private_ptr# alias take the From 769406d1b5772d743b803a33a5874bef8f4f9000 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Tue, 17 Sep 2024 18:05:35 -0400 Subject: [PATCH 07/23] Add KHR for default context --- adoc/extensions/index.adoc | 4 +- adoc/extensions/sycl_khr_default_context.adoc | 57 +++++++++++++++++++ 2 files changed, 59 insertions(+), 2 deletions(-) create mode 100644 adoc/extensions/sycl_khr_default_context.adoc diff --git a/adoc/extensions/index.adoc b/adoc/extensions/index.adoc index 07062df61..1a13364ad 100644 --- a/adoc/extensions/index.adoc +++ b/adoc/extensions/index.adoc @@ -7,7 +7,7 @@ working group. These extensions may be promoted to core features in future versions of the SYCL specification, but their design is subject to change. -(There are currently no extensions in this appendix.) - // leveloffset=2 allows extensions to be written as standalone documents // include::sycl_khr_extension_name.adoc[leveloffset=2] + +include::sycl_khr_default_context.adoc[leveloffset=2] diff --git a/adoc/extensions/sycl_khr_default_context.adoc b/adoc/extensions/sycl_khr_default_context.adoc new file mode 100644 index 000000000..671b776f5 --- /dev/null +++ b/adoc/extensions/sycl_khr_default_context.adoc @@ -0,0 +1,57 @@ +[[sec:khr-default-context]] += SYCL_KHR_DEFAULT_CONTEXT + +When a [code]#queue# object is constructed without passing an explicit +[code]#context# object, the queue uses the platform's default context. +This extension adds a new query function to retrieve this default context +from a [code]#platform# object. + +[[sec:khr-default-context-dependencies]] +== Dependencies + +This extension has no dependencies on other extensions. + +[[sec:khr-default-context-feature-test]] +== Feature test macro + +An implementation supporting this extension must predefine the macro +[code]#SYCL_KHR_DEFAULT_CONTEXT# to one of the values defined in the table +below. + +[%header,cols="1,5"] +|=== +|Value +|Description + +|1 +|Initial version of this extension. +|=== + +[[sec:khr-default-context-platform]] +== Extensions to the platform class + +This extension adds the following new member functions to the [code]#platform# +class. + +[source,role=synopsis,id=api:khr-default-context-platform] +---- +namespace sycl { +class platform { + context khr_get_default_context() const; + // ... +}; +} +---- + +[[sec:khr-default-context-platform-member-funcs]] +=== Member functions + +.[apidef]#platform::khr_get_default_context# +[source,role=synopsis,id=api:platform-khr-get-default-context] +---- +context khr_get_default_context() const +---- + +_Returns:_ A copy of the default context object for this platform. +The default context contains all of the <> that are +associated with this platform. From ffcf063cdeddc02d299be5cd42078768906c2d65 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Tue, 17 Sep 2024 18:13:22 -0400 Subject: [PATCH 08/23] Reflow --- adoc/extensions/sycl_khr_default_context.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adoc/extensions/sycl_khr_default_context.adoc b/adoc/extensions/sycl_khr_default_context.adoc index 671b776f5..fb7003773 100644 --- a/adoc/extensions/sycl_khr_default_context.adoc +++ b/adoc/extensions/sycl_khr_default_context.adoc @@ -3,8 +3,8 @@ When a [code]#queue# object is constructed without passing an explicit [code]#context# object, the queue uses the platform's default context. -This extension adds a new query function to retrieve this default context -from a [code]#platform# object. +This extension adds a new query function to retrieve this default context from a +[code]#platform# object. [[sec:khr-default-context-dependencies]] == Dependencies From a3d76d17dbf45fedb03a1ee6ccb9d757fb8e5d98 Mon Sep 17 00:00:00 2001 From: Ronan Keryell Date: Thu, 8 Feb 2024 09:51:17 -0800 Subject: [PATCH 09/23] Mention manifestly constant-evaluated expression in "what changed" (cherry picked from commit 4af3c9f3d90e951dd9667f3d7f74b64859c03c53) --- adoc/chapters/what_changed.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/adoc/chapters/what_changed.adoc b/adoc/chapters/what_changed.adoc index 3ce5f5ebd..05d4453ae 100644 --- a/adoc/chapters/what_changed.adoc +++ b/adoc/chapters/what_changed.adoc @@ -437,4 +437,7 @@ parameters did not clearly specify which accessor's size determines the amount of memory that is copied. The spec now clarifies that the [code]#src# accessor's size is used. +Any code considered as a manifestly constant-evaluated expression or conversion +by the C++ standard is now also accepted in SYCL device function. + // %%%%%%%%%%%%%%%%%%%%%%%%%%%% end what_changed %%%%%%%%%%%%%%%%%%%%%%%%%%%% From cc30e6ae4776cab431ec0555a87f54bbe895b6ac Mon Sep 17 00:00:00 2001 From: "Gregory Lueck (Intel)" Date: Wed, 4 Sep 2024 16:23:34 +0000 Subject: [PATCH 10/23] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: Gregory Lueck (Intel) (cherry picked from commit 394354ea2c6bd5f2cec62b7fcf2dc42b50d49bf0) --- adoc/chapters/device_compiler.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index b74e3d5a1..206f49d89 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -181,7 +181,7 @@ these restrictions: In the case of a manifestly constant-evaluated expression or conversion, any code accepted by the C++ standard in this case is also -accepted in SYCL <>. +accepted in a SYCL <>. [NOTE] ==== From 8587a5e3f97a95a198f52bef992deb6ca726a993 Mon Sep 17 00:00:00 2001 From: Ronan Keryell Date: Wed, 4 Sep 2024 10:05:08 -0700 Subject: [PATCH 11/23] Add note on manifestly constant-evaluated and optional features Suggestion by Greg Lueck. (cherry picked from commit 4bf99a1c57406bd54e23bfe857ccbe0d4b891eb2) --- adoc/chapters/device_compiler.adoc | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 206f49d89..ae2bb3e8c 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -440,6 +440,16 @@ run afoul of this requirement if the implementation compiles the entire device image when [code]#KernelA# is submitted to device [code]#dev1#. ==== +[NOTE] +==== +As stated in <>, the restrictions +for optional kernel features do not apply to manifestly +constant-evaluated expressions or conversions in device code. Device +code may use optional features in manifestly constant-evaluated +expressions or conversions even if the device does not support the +optional feature. +==== + [[sec:device.attributes]] == Attributes for device code From 1f7d2e0eb38261dc6b792cb2b5fede840ab1a1da Mon Sep 17 00:00:00 2001 From: Ronan Keryell Date: Wed, 4 Sep 2024 10:18:03 -0700 Subject: [PATCH 12/23] Fix the place of a paragraph and its note (cherry picked from commit bde612085fe849640f3136558e6750895b691509) --- adoc/chapters/device_compiler.adoc | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index ae2bb3e8c..cbbfd990e 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -179,18 +179,11 @@ these restrictions: <>, must be [code]#const# or [code]#constexpr# and zero-initialized or constant-initialized. -In the case of a manifestly constant-evaluated expression or -conversion, any code accepted by the C++ standard in this case is also -accepted in a SYCL <>. - [NOTE] ==== Amongst other things, this restriction makes it illegal for a -<> to access a global variable that isn't [code]#const# -or [code]#constexpr#. - -The restriction waiver in manifestly constant-evaluated expressions -allows any kind of meta-programming in a <>. +<> to access a global variable that isn't [code]#const# or +[code]#constexpr#. ==== * The rules for kernels apply to both the kernel function objects @@ -210,6 +203,15 @@ allows any kind of meta-programming in a <>. may be defined in another translation unit if the implementation defines the [code]#SYCL_EXTERNAL# macro as described in <>. +In the case of a manifestly constant-evaluated expression or +conversion, any code accepted by the C++ standard in this case is also +accepted in a SYCL <>. + +[NOTE] +==== +The restriction waiver in manifestly constant-evaluated expressions allows any +kind of meta-programming in a <>. +==== [[subsec:scalartypes]] == Built-in scalar data types From f0c3a8fe20e043523214014f7d27195f8efd1231 Mon Sep 17 00:00:00 2001 From: Ronan Keryell Date: Wed, 2 Oct 2024 11:44:47 -0700 Subject: [PATCH 13/23] Replace a note by normative waiver on optional feature Take into account Greg Lueck comment https://github.com/KhronosGroup/SYCL-Docs/pull/388#discussion_r1784433888 Also reformat some text to pass the CI. --- adoc/chapters/device_compiler.adoc | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 67e8eaf3f..ffd14f45a 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -205,9 +205,9 @@ Amongst other things, this restriction makes it illegal for a implementation defines the [code]#SYCL_EXTERNAL# macro as described in <>. -In the case of a manifestly constant-evaluated expression or -conversion, any code accepted by the C++ standard in this case is also -accepted in a SYCL <>. +In the case of a manifestly constant-evaluated expression or conversion, any +code accepted by the C++ standard in this case is also accepted in a SYCL +<>. [NOTE] ==== @@ -386,6 +386,14 @@ in <> must be defined by all conformant implementations. A number of kernel features defined by this SYCL specification are optional; they may be supported on some devices but not on other devices. + +As stated in <>, the restrictions for +optional kernel features do not apply to manifestly constant-evaluated +expressions or conversions in device code. +Device code may use optional features in manifestly constant-evaluated +expressions or conversions even if the device does not support the optional +feature. + As described in <>, an application can test whether a device supports these features by testing whether the device has an associated aspect. The following aspects are those that correspond to optional kernel features: @@ -446,16 +454,6 @@ the entire device image when [code]#KernelA# is submitted to device [code]#dev1#. ==== -[NOTE] -==== -As stated in <>, the restrictions -for optional kernel features do not apply to manifestly -constant-evaluated expressions or conversions in device code. Device -code may use optional features in manifestly constant-evaluated -expressions or conversions even if the device does not support the -optional feature. -==== - [[sec:device.attributes]] == Attributes for device code From 54c476ea6db9714ef7bfa4d227eb20b9169bd206 Mon Sep 17 00:00:00 2001 From: Ronan Keryell Date: Wed, 2 Oct 2024 15:48:34 -0700 Subject: [PATCH 14/23] Precise the fact we are talking about optional features Co-authored-by: Greg Lueck --- adoc/chapters/device_compiler.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index ffd14f45a..5a31b5ba8 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -395,7 +395,8 @@ expressions or conversions even if the device does not support the optional feature. As described in <>, an application can test whether a device -supports these features by testing whether the device has an associated aspect. +supports an optional feature by testing whether the device has an associated +aspect. The following aspects are those that correspond to optional kernel features: * [code]#fp16# From 6af058c59b1bf4a0e8bad5627de18ccf04180cb1 Mon Sep 17 00:00:00 2001 From: Erik <18669618+etomzak@users.noreply.github.com> Date: Wed, 23 Oct 2024 11:24:29 +0100 Subject: [PATCH 15/23] Include cf. (compare) in set of non-line-ending abbreviations --- adoc/scripts/reflow.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/scripts/reflow.py b/adoc/scripts/reflow.py index f5bf81b1d..bda81b9e1 100755 --- a/adoc/scripts/reflow.py +++ b/adoc/scripts/reflow.py @@ -53,7 +53,7 @@ # A single letter followed by a period, typically a middle initial. endInitial = re.compile(r'^[A-Z]\.$') # An abbreviation, which does not (usually) end a line. -endAbbrev = re.compile(r'(e\.g|i\.e|c\.f|\bvs\b|\bco\b|\bltd\b|\bch\b)\.$', re.IGNORECASE) +endAbbrev = re.compile(r'(e\.g|i\.e|c\.f|\bvs\b|\bco\b|\bltd\b|\bch\b|\bcf\b)\.$', re.IGNORECASE) # A lower case word. When "etc." is followed by this, it does not end a line. startsLowerCase = re.compile(r'\(?[a-z]') From b0b5d71d9de36b971057e1e40c1c88d351b6b59f Mon Sep 17 00:00:00 2001 From: Erik <18669618+etomzak@users.noreply.github.com> Date: Wed, 23 Oct 2024 13:48:14 +0100 Subject: [PATCH 16/23] Remove c.f. (extra period) from reflow.py --- adoc/scripts/reflow.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/scripts/reflow.py b/adoc/scripts/reflow.py index bda81b9e1..0869562c2 100755 --- a/adoc/scripts/reflow.py +++ b/adoc/scripts/reflow.py @@ -53,7 +53,7 @@ # A single letter followed by a period, typically a middle initial. endInitial = re.compile(r'^[A-Z]\.$') # An abbreviation, which does not (usually) end a line. -endAbbrev = re.compile(r'(e\.g|i\.e|c\.f|\bvs\b|\bco\b|\bltd\b|\bch\b|\bcf\b)\.$', re.IGNORECASE) +endAbbrev = re.compile(r'(e\.g|i\.e|\bvs\b|\bco\b|\bltd\b|\bch\b|\bcf\b)\.$', re.IGNORECASE) # A lower case word. When "etc." is followed by this, it does not end a line. startsLowerCase = re.compile(r'\(?[a-z]') From 6bb1cda71778679874f5be69c52a72c43a31022d Mon Sep 17 00:00:00 2001 From: Erik <18669618+etomzak@users.noreply.github.com> Date: Wed, 23 Oct 2024 19:45:30 +0100 Subject: [PATCH 17/23] Un-capitalize some headings --- adoc/chapters/architecture.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/adoc/chapters/architecture.adoc b/adoc/chapters/architecture.adoc index ff3e8d3af..ec19cfd57 100644 --- a/adoc/chapters/architecture.adoc +++ b/adoc/chapters/architecture.adoc @@ -1389,7 +1389,7 @@ implementation-defined. [[sec:coordination]] -=== Coordination and Synchronization +=== Coordination and synchronization Coordination between the host and any devices can be expressed in the host SYCL application using calls into the SYCL runtime. @@ -1403,7 +1403,7 @@ Such functions can be used to ensure that the host and any devices do not access data concurrently, and/or to reason about the ordering of operations across the host and any devices. -==== Host-Device Coordination +==== Host-device coordination The following operations can be used to coordinate host and device(s): @@ -1456,7 +1456,7 @@ So it is up to the programmer to use a member function to wait for completion in some cases if this does not fit the goal. See <> for more information on object life time. -==== Work-item Coordination +==== Work-item coordination A <> provides a mechanism to coordinate all work-items in the same group. From ffbeb2013357a8ad7df9e80134c9655f5c4a558f Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Mon, 28 Oct 2024 14:50:11 +0000 Subject: [PATCH 18/23] Fix error behavior for initialize_to_identity Previously, the specification said that a compiler must issue a diagnostic if the initialize_to_identity property was used without a known identity value. This requirement cannot be satisfied, because the presence of the initialize_to_identity value in a property_list cannot be proven until run-time. This change replaces the compile-time diagnostic with a run-time exception. --- adoc/chapters/programming_interface.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 2332823df..48901a58f 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -13892,9 +13892,10 @@ property::reduction::initialize_to_identity identity value passed to the reduction interface, or to the identity value determined by the [code]#known_identity# trait if no identity value was specified. If no identity value was specified and an identity value - cannot be determined by the [code]#known_identity# trait, the compiler - must raise a diagnostic. When this property is set, the original value of - the reduction variable is not included in the reduction. + cannot be determined by the [code]#known_identity# trait, the + implementation must throw an [code]#exception# with the + [code]#errc::invalid# error code. When this property is set, the original + value of the reduction variable is not included in the reduction. |==== From 966a051946f1a3f8e4880cee9b5a4f828420bfea Mon Sep 17 00:00:00 2001 From: Ronan Keryell Date: Wed, 6 Nov 2024 17:32:44 -0800 Subject: [PATCH 19/23] Allow also arbitrary kernel code inside discarded statements See ISO C++ standard "The if statement [stmt.if]". --- adoc/chapters/device_compiler.adoc | 11 ++++++----- adoc/chapters/what_changed.adoc | 5 +++-- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 5a31b5ba8..735f718c0 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -205,14 +205,15 @@ Amongst other things, this restriction makes it illegal for a implementation defines the [code]#SYCL_EXTERNAL# macro as described in <>. -In the case of a manifestly constant-evaluated expression or conversion, any -code accepted by the C++ standard in this case is also accepted in a SYCL -<>. +Inside discarded statements or in the case of manifestly constant-evaluated +expression or conversion, any code accepted by the C++ standard in this case is +also accepted in a SYCL <>. [NOTE] ==== -The restriction waiver in manifestly constant-evaluated expressions allows any -kind of meta-programming in a <>. +The restriction waiver in manifestly constant-evaluated expressions and +discarded statements allows any kind of meta-programming in a +<>. ==== [[subsec:scalartypes]] diff --git a/adoc/chapters/what_changed.adoc b/adoc/chapters/what_changed.adoc index ac67948d3..833696070 100644 --- a/adoc/chapters/what_changed.adoc +++ b/adoc/chapters/what_changed.adoc @@ -468,7 +468,8 @@ parameters did not clearly specify which accessor's size determines the amount of memory that is copied. The spec now clarifies that the [code]#src# accessor's size is used. -Any code considered as a manifestly constant-evaluated expression or conversion -by the C++ standard is now also accepted in SYCL device function. +Any code considered as a discarded statement or as a manifestly +constant-evaluated expression or conversion by the C++ standard is now also +accepted in SYCL device function. // %%%%%%%%%%%%%%%%%%%%%%%%%%%% end what_changed %%%%%%%%%%%%%%%%%%%%%%%%%%%% From 9b20c4fe84829abcd423e6c8e4ad56118e059e16 Mon Sep 17 00:00:00 2001 From: Ronan Keryell Date: Thu, 7 Nov 2024 09:33:48 -0800 Subject: [PATCH 20/23] Add discarded statement & manifestly constant-evaluated in glossary --- adoc/chapters/device_compiler.adoc | 20 ++++++++++---------- adoc/chapters/glossary.adoc | 12 ++++++++++++ adoc/chapters/what_changed.adoc | 6 +++--- 3 files changed, 25 insertions(+), 13 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 735f718c0..29cf37790 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -205,14 +205,14 @@ Amongst other things, this restriction makes it illegal for a implementation defines the [code]#SYCL_EXTERNAL# macro as described in <>. -Inside discarded statements or in the case of manifestly constant-evaluated -expression or conversion, any code accepted by the C++ standard in this case is -also accepted in a SYCL <>. +Inside a <> or in the case of a +<>, any code accepted by the C++ standard in this +case is also accepted in a SYCL <>. [NOTE] ==== -The restriction waiver in manifestly constant-evaluated expressions and -discarded statements allows any kind of meta-programming in a +The restriction waiver in <> or +<> allows any kind of meta-programming in a <>. ==== @@ -389,11 +389,11 @@ A number of kernel features defined by this SYCL specification are optional; they may be supported on some devices but not on other devices. As stated in <>, the restrictions for -optional kernel features do not apply to manifestly constant-evaluated -expressions or conversions in device code. -Device code may use optional features in manifestly constant-evaluated -expressions or conversions even if the device does not support the optional -feature. +optional kernel features do not apply to discarded statements or to manifestly +constant-evaluated expressions or conversions in device code. Device code may +use optional features in <> or +<> even if the device does not support the +optional feature. As described in <>, an application can test whether a device supports an optional feature by testing whether the device has an associated diff --git a/adoc/chapters/glossary.adoc b/adoc/chapters/glossary.adoc index b276e8c8b..88d7dd47c 100644 --- a/adoc/chapters/glossary.adoc +++ b/adoc/chapters/glossary.adoc @@ -188,6 +188,11 @@ For the full description please refer to <>. One of the device with the highest non-negative value is selected. See <> for more details. +[[discarded-statement]]discarded statement:: + ISO C++ +[stmt.if]+ describes a discarded statement as the branch statement + of an [code]#if constexpr# which is not instantiated because of the boolean + condition. For more context, see <>. + [[event]]event:: A SYCL object that represents the status of an operation that is being executed by the SYCL runtime. @@ -370,6 +375,13 @@ For the full description please refer to <>. In the SYCL interface an <> is represented by the [code]#nd_range# class (see <>). +[[manifestly-constant-evaluated]]manifestly constant-evaluated expression or conversion:: + ISO C++ +[expr.const]+ describes manifestly constant-evaluated expression or + conversion like constant expressions, condition of an +if constexpr+, an + immediate invocation, used in template parameters, in constant + initialization, etc. This is evaluated at compile-time by the compiler. For + more context, see <>. + [[mem-fence]]mem-fence:: A memory fence provides control over re-ordering of memory load and store operations when coupled with an atomic operation. diff --git a/adoc/chapters/what_changed.adoc b/adoc/chapters/what_changed.adoc index 833696070..7e40744ac 100644 --- a/adoc/chapters/what_changed.adoc +++ b/adoc/chapters/what_changed.adoc @@ -468,8 +468,8 @@ parameters did not clearly specify which accessor's size determines the amount of memory that is copied. The spec now clarifies that the [code]#src# accessor's size is used. -Any code considered as a discarded statement or as a manifestly -constant-evaluated expression or conversion by the C++ standard is now also -accepted in SYCL device function. +Any code considered as a <> or as a +<> by the C++ standard is now also accepted in +SYCL device function. // %%%%%%%%%%%%%%%%%%%%%%%%%%%% end what_changed %%%%%%%%%%%%%%%%%%%%%%%%%%%% From b246ce28744fdd8305ed0972bec5ba14df13988b Mon Sep 17 00:00:00 2001 From: Tom Deakin Date: Thu, 7 Nov 2024 17:17:24 +0000 Subject: [PATCH 21/23] Fix a typo in `multi_ptr::operator=` documentation Cherry pick #642 from sycl-2020 (cherry picked from commit 05469ac562242d171fc87c42d77dea23739573e2) --- adoc/chapters/programming_interface.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index c3d845817..5f2b2f9c5 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -10135,7 +10135,7 @@ operator=(const multi_ptr&) ---- a@ Available only when: [code]#(Space == access::address_space::generic_space && AS != access::address_space::constant_space)#. -Assigns the value of the left hand side [code]#multi_ptr# into the [code]#generic_ptr#. +Assigns the value of the right hand side [code]#multi_ptr# into the [code]#generic_ptr#. a@ [source] @@ -10148,7 +10148,7 @@ operator=(multi_ptr&&) a@ Available only when: [code]#(Space == access::address_space::generic_space && AS != access::address_space::constant_space)#. -Move the value of the left hand side [code]#multi_ptr# into the [code]#generic_ptr#. +Move the value of the right hand side [code]#multi_ptr# into the [code]#generic_ptr#. a@ [source] From 87c90fc93b63631cc2eb53e0c8326ab39bac4a8f Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 14 Nov 2024 14:22:54 -0500 Subject: [PATCH 22/23] Fix reflow --- adoc/chapters/device_compiler.adoc | 4 ++-- adoc/chapters/glossary.adoc | 8 +++++--- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 29cf37790..d75680ff4 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -390,8 +390,8 @@ they may be supported on some devices but not on other devices. As stated in <>, the restrictions for optional kernel features do not apply to discarded statements or to manifestly -constant-evaluated expressions or conversions in device code. Device code may -use optional features in <> or +constant-evaluated expressions or conversions in device code. +Device code may use optional features in <> or <> even if the device does not support the optional feature. diff --git a/adoc/chapters/glossary.adoc b/adoc/chapters/glossary.adoc index a6607efd4..66d82165f 100644 --- a/adoc/chapters/glossary.adoc +++ b/adoc/chapters/glossary.adoc @@ -191,7 +191,8 @@ For the full description please refer to <>. [[discarded-statement]]discarded statement:: ISO C++ +[stmt.if]+ describes a discarded statement as the branch statement of an [code]#if constexpr# which is not instantiated because of the boolean - condition. For more context, see <>. + condition. + For more context, see <>. [[event]]event:: A SYCL object that represents the status of an operation that is being @@ -384,8 +385,9 @@ For the full description please refer to <>. ISO C++ +[expr.const]+ describes manifestly constant-evaluated expression or conversion like constant expressions, condition of an +if constexpr+, an immediate invocation, used in template parameters, in constant - initialization, etc. This is evaluated at compile-time by the compiler. For - more context, see <>. + initialization, etc. + This is evaluated at compile-time by the compiler. + For more context, see <>. [[object]]object:: A state which a <> can be in, representing From df3b0fa635a8ceb4d1673b4ae74a8bc43ed0d612 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 14 Nov 2024 14:25:21 -0500 Subject: [PATCH 23/23] Sort glossary --- adoc/chapters/glossary.adoc | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/adoc/chapters/glossary.adoc b/adoc/chapters/glossary.adoc index 66d82165f..2fb43ce98 100644 --- a/adoc/chapters/glossary.adoc +++ b/adoc/chapters/glossary.adoc @@ -345,6 +345,14 @@ For the full description please refer to <>. Local memory is a memory region associated with a <> and accessible only by <> in that <>. +[[manifestly-constant-evaluated]]manifestly constant-evaluated expression or conversion:: + ISO C++ +[expr.const]+ describes manifestly constant-evaluated expression or + conversion like constant expressions, condition of an +if constexpr+, an + immediate invocation, used in template parameters, in constant + initialization, etc. + This is evaluated at compile-time by the compiler. + For more context, see <>. + [[mem-fence]]mem-fence:: A memory fence provides control over re-ordering of memory load and store operations when coupled with an atomic operation. @@ -359,7 +367,6 @@ For the full description please refer to <>. A <> in a device image whose value can be used by an online compiler as an immediate value during the compilation. - [[nd-item]]nd-item:: A unique identifier representing a single <> and <> within the index space of a SYCL kernel execution. @@ -381,14 +388,6 @@ For the full description please refer to <>. In the SYCL interface an <> is represented by the [code]#nd_range# class (see <>). -[[manifestly-constant-evaluated]]manifestly constant-evaluated expression or conversion:: - ISO C++ +[expr.const]+ describes manifestly constant-evaluated expression or - conversion like constant expressions, condition of an +if constexpr+, an - immediate invocation, used in template parameters, in constant - initialization, etc. - This is evaluated at compile-time by the compiler. - For more context, see <>. - [[object]]object:: A state which a <> can be in, representing <> as a non-executable object.