From 376cc65d43efdcbc19697dd627430cf58e7f5841 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Fri, 14 Jun 2024 17:24:08 -0400 Subject: [PATCH 1/2] Change the base C++ version Change wording to allow the core C++ language to be any version C++17 or later. Move sections about normative references and non-normative wording to the introduction, so they are earlier in the document. My longer term goal is to remove "chapter/references.adoc" and add any references we require to the "Normative references" section. Some more work needs to be done for this to happen: * Decide if we need to list the C++ defect reports as normative references. Currently, the "references" appendix lists only DR2325. Is there a reason to list this one and not others? * Decide if OpenCL should be a normative reference. If so, which version(s)? --- adoc/chapters/architecture.adoc | 73 --------------------------- adoc/chapters/introduction.adoc | 89 +++++++++++++++++++++++++++++++++ adoc/syclbase.adoc | 1 + 3 files changed, 90 insertions(+), 73 deletions(-) diff --git a/adoc/chapters/architecture.adoc b/adoc/chapters/architecture.adoc index ec19cfd5..73a84382 100644 --- a/adoc/chapters/architecture.adoc +++ b/adoc/chapters/architecture.adoc @@ -137,52 +137,6 @@ dependencies between <>. In this example the <> is used to write to the data buffer on line 26. -[[sec:normativerefs]] -== Normative references - -// Jon: are any of the OpenCL specifications normative? They are also -// referred to from the SYCL spec, and some of the definitions appear to be -// required. - -The documents in the following list are referred to within this SYCL -specification, and their content is a requirement for this document. - - . *{cpp17}:* <>, referred to in this - specification as the {cpp} core language. - The SYCL specification refers to language in the following {cpp} defect - reports and assumes a compiler that implements them: <>. - . *{cpp20}:* <>, referred to in this specification as the next -{cpp} specification. - -[[sec:nonnormativerefs]] -== Non-normative notes and examples - -Unless stated otherwise, text within this SYCL specification is normative and -defines the required behavior of a SYCL implementation. -Non-normative / informational notes are included within this specification using -either of two formats. -One format for non-normative notes is the "`note`" callout of this form: - -[NOTE] -==== -Information within a note callout, such as this text, is for informational -purposes and does not impose requirements on or specify behavior of a SYCL -implementation. -==== - -The other format for a non-normative note is like this: - -{note}This is also a non-normative note. -{endnote} - -Source code examples within the specification are provided to aid with -understanding, and are non-normative. - -In case of any conflict between a non-normative note or source example, and -normative text within the specification, the normative text must be taken to be -correct. - [[sec:platformmodel]] == The SYCL platform model @@ -1218,33 +1172,6 @@ The kernels may be compiled and optimized for multiple different processor architectures with very different binary representations. -// TODO: Add \subsection{SYCL {cpp} language requirements} before merging -// Don't do until then to avoid changing section numbers -// [[sec:progmodel.cpp]] - -[[sec:progmodel.minimumcppversion]] -=== Minimum version of {cpp} - -The {cpp} features used in SYCL are based on a specific version of {cpp}. -Implementations of SYCL must support this minimum {cpp} version, which defines -the {cpp} constructs that can consequently be used by SYCL feature definitions -(for example, lambdas). - -The minimum {cpp} version of this SYCL specification is determined by the -normative {cpp} core language defined in <>. -All implementations of this specification must support at least this core -language, and features within this specification are defined using features of -the core language. -Note that not all core language constructs are supported within -<> or code invoked by a -<>, as detailed by <>. - -Implementations may support newer {cpp} versions than the minimum required by -SYCL. -Code written using newer features than the SYCL requirement, though, may not be -portable to other implementations that don't support the same {cpp} version. - - [[sec:progmodel.futurecppversion]] === Alignment with future versions of {cpp} diff --git a/adoc/chapters/introduction.adoc b/adoc/chapters/introduction.adoc index c0aca595..69405ecb 100644 --- a/adoc/chapters/introduction.adoc +++ b/adoc/chapters/introduction.adoc @@ -153,6 +153,95 @@ build on top of SYCL as an open platform for system-wide heterogeneous processing innovation. +[[sec:normativerefs]] +== Normative references + +Normative references are references to external documents or resources to which +implementers of SYCL must comply with all, or specified portions of, as +described in this specification. + +International Organization for Standardization (ISO). + +ISO/IEC 14882:2017 - Programming languages - {cpp}, +https://www.iso.org/standard/68564.html + +(Referred to as {cpp17} in this document.) + +International Organization for Standardization (ISO). + +ISO/IEC 14882:2020 - Programming languages - {cpp}, +https://www.iso.org/standard/79358.html + +(Referred to as {cpp20} in this document.) + +International Organization for Standardization (ISO). + +ISO/IEC 14882:2024 - Programming languages - {cpp}, +https://www.iso.org/standard/83626.html + +(Referred to as {cpp23} in this document.) + +// Jon: are any of the OpenCL specifications normative? They are also +// referred to from the SYCL spec, and some of the definitions appear to be +// required. + + +[[sec:nonnormativerefs]] +== Non-normative notes and examples + +Unless stated otherwise, text within this SYCL specification is normative and +defines the required behavior of a SYCL implementation. +Non-normative / informational notes are included within this specification using +either of two formats. +One format for non-normative notes is the "`note`" callout of this form: + +[NOTE] +==== +Information within a note callout, such as this text, is for informational +purposes and does not impose requirements on or specify behavior of a SYCL +implementation. +==== + +The other format for a non-normative note is like this: + +{note}This is also a non-normative note. +{endnote} + +Source code examples within the specification are provided to aid with +understanding, and are non-normative. + +In case of any conflict between a non-normative note or source example, and +normative text within the specification, the normative text must be taken to be +correct. + + +[[sec:progmodel.minimumcppversion]] +== Minimum version of {cpp} + +A SYCL implementation must conform to {cpp17} or to one of the more recent {cpp} +versions listed in <>. +This version of {cpp} is subsequently referred to as the {cpp} core language in +this document. +All APIs in this specification are available regardless of the version of the +{cpp} core language unless the description specifically states otherwise. +If an API is documented with the phrase "Minimum C++ Version: __Version__", then +that API is available only if the version of the implementation's {cpp} core +language is at least _Version_. + +{note}Not all {cpp} features are supported in SYCL <>. +See <>. +{endnote} + +{note}Applications should take care when using SYCL APIs or {cpp} features that +are not available in {cpp17}. +The use of such APIs or features may prevent an application from being portable +across all implementations of SYCL. +{endnote} + +{note}Implementations may choose to make APIs documented as "Minimum C++ +Version: __Version__" available even when the {cpp} version is less than +_Version_. +The recommended practice in this case is to use [code]#+__has_include+# and the +appropriate {cpp} feature-test macros to improve the portability of SYCL +applications across implementations. +{endnote} + + [[sec::unified-spec]] == Unified specification diff --git a/adoc/syclbase.adoc b/adoc/syclbase.adoc index f6f03041..9a4832bf 100644 --- a/adoc/syclbase.adoc +++ b/adoc/syclbase.adoc @@ -78,6 +78,7 @@ include::config/api_xrefs.adoc[] // Asciidoctor uses ++ to denote spans, so use these attributes instead :cpp17: pass:[C++17] :cpp20: pass:[C++20] +:cpp23: pass:[C++23] // Fortunately, the cpp macro for C++ is defined by default in AsciiDoctor // Use these to format a non-normative note. The Asciidoc source: From d5d63ed9baf18a4026d67014331b7d0f7f9f5393 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 12 Dec 2024 12:06:28 -0500 Subject: [PATCH 2/2] Update wording for "C++ core language" --- adoc/chapters/introduction.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adoc/chapters/introduction.adoc b/adoc/chapters/introduction.adoc index 69405ecb..62622825 100644 --- a/adoc/chapters/introduction.adoc +++ b/adoc/chapters/introduction.adoc @@ -214,8 +214,8 @@ correct. A SYCL implementation must conform to {cpp17} or to one of the more recent {cpp} versions listed in <>. -This version of {cpp} is subsequently referred to as the {cpp} core language in -this document. +The version of {cpp} to which a SYCL implementation conforms is referred to as +the {cpp} core language in this document. All APIs in this specification are available regardless of the version of the {cpp} core language unless the description specifically states otherwise. If an API is documented with the phrase "Minimum C++ Version: __Version__", then