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..62622825 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 <>. +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 +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: