Skip to content
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

Change the base C++ version #680

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Change the base C++ version #680

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
376cc65
Change the base C++ version
gmlueck Jun 14, 2024
d5d63ed
Update wording for "C++ core language"
gmlueck Dec 12, 2024
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
73 changes: 0 additions & 73 deletions adoc/chapters/architecture.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,52 +137,6 @@ dependencies between <<sycl-kernel-function>>.
In this example the <<accessor>> 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}:* <<cpp17, ISO/IEC 14882:2017 Clauses 1-19>>, 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: <<dr2325, DR2325>>.
. *{cpp20}:* <<cpp20, ISO/IEC 14882:2020
Programming languages — {cpp}>>, 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

Expand Down Expand Up @@ -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 <<sec:normativerefs>>.
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
<<sycl-kernel-function,SYCL kernel functions>> or code invoked by a
<<sycl-kernel-function>>, as detailed by <<sec:language.restrictions.kernels>>.

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}

Expand Down
89 changes: 89 additions & 0 deletions adoc/chapters/introduction.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<sec:normativerefs>>.
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_.
Comment on lines +219 to +223
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the repetition of "C++ core language" here is confusing. The second sentence in this paragraph defines "C++ core language" to mean "C++17", so these sentences appear to be talking about different versions of C++17.

How about:

Suggested change
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_.
All APIs in this specification are available regardless of the {cpp} version
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 SYCL implementation conforms to a {cpp} version of
_Version_ or later.

The first sentence in the paragraph already talks about SYCL implementations "conforming to" specific C++ versions, which is why I picked that wording.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The term "C++ core language" is intended to identify whatever C++ version the implementation chooses. The first sentence says that an implementation must choose one of the versions listed in section <<sec:normativerefs>> (which are all the versions from C++17 and greater).

In practice, I expect that most SYCL implementations will choose the C++ version via a command line parameter like -std=.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens when ISO C++26 is out but this is not yet mentioned in the SYCL spec as s normative norm? Is it up to the implementation whether a program using C++26 in host part will work? 🤔

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The term "C++ core language" is intended to identify whatever C++ version the implementation chooses. The first sentence says that an implementation must choose one of the versions listed in section <<sec:normativerefs>> (which are all the versions from C++17 and greater).

Oh, I see. I misunderstood the sentence. I read "This version of C++" as referring to C++17, not as "the C++ standard to which a SYCL implementation conforms".

If we wanted to make this unambiguous we could say:

A SYCL implementation must conform to {cpp17} or to one of the more recent {cpp} versions listed in <sec:normativerefs>.
The version of {cpp} to which a SYCL implementation conforms is referred to as the {cpp} core language in this document.

or

A SYCL implementation must conform to a specific version of {cpp}, referred to as the {cpp} core language in this document.
The {cpp} core language must be {cpp17} or one of the more recent {cpp} versions listed in <sec:normativerefs>.

...but if I'm alone in thinking the original wording is confusing, you can ignore me!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens when ISO C++26 is out but this is not yet mentioned in the SYCL spec as s normative norm? Is it up to the implementation whether a program using C++26 in host part will work? 🤔

I don't see this as a practical problem. There are already C++ compilers that support proposed C++26 features even though there is no ratified C++26 specification yet. Those compilers can exist -- they just aren't conformant to any spec yet. I think it could be the same for SYCL. An implementation can choose to support C++26 with SYCL if it wants. It just won't be strictly conformant to the SYCL spec.

What would be the alternative? I guess the SYCL spec could say that the core C++ version could be any future version of C++ even though we don't know what language features this would include. I think that would be more problematic because we wouldn't know how those unknown language features would work in device code.

This reminds me ... we should think through all the new language features in C++20 and C++23 and decide if they are legal in device code. For those that are not, we need to add them to section 5.5 "Language restrictions for device functions".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we wanted to make this unambiguous we could say:

I updated the wording according to your suggestion in d5d63ed.


{note}Not all {cpp} features are supported in SYCL <<device-function, device
functions>>.
See <<sec:language.restrictions.kernels>>.
{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

Expand Down
1 change: 1 addition & 0 deletions adoc/syclbase.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading