diff --git a/adoc/Makefile b/adoc/Makefile index 3a3dd1a3..d7b910f7 100644 --- a/adoc/Makefile +++ b/adoc/Makefile @@ -164,7 +164,7 @@ HEADER_DIR = $(CURDIR)/headers # Top-level spec source file SPECSRC = syclbase.adoc # Static files making up sections of the API spec. -SPECFILES = $(wildcard *.adoc) $(wildcard chapters/*.adoc) +SPECFILES = $(wildcard *.adoc) $(wildcard chapters/*.adoc) $(wildcard extensions/*.adoc) # Shorthand for where different types of generated files go. # All can be relocated by overriding GENERATED in the make invocation. diff --git a/adoc/chapters/architecture.adoc b/adoc/chapters/architecture.adoc index 0a4bf93c..1a1f0793 100644 --- a/adoc/chapters/architecture.adoc +++ b/adoc/chapters/architecture.adoc @@ -1518,7 +1518,7 @@ queue. The situations where a SYCL runtime may be able to achieve this asynchronous fall-back is implementation-defined. -This feature is deprecated in SYCL NEXT. +This feature is deprecated in SYCL {SYCL_VERSION}. === Scheduling of kernels and data movement diff --git a/adoc/chapters/introduction.adoc b/adoc/chapters/introduction.adoc index 4d8050a5..c0aca595 100644 --- a/adoc/chapters/introduction.adoc +++ b/adoc/chapters/introduction.adoc @@ -152,4 +152,28 @@ platform-specific technologies, thereby letting both users and implementers build on top of SYCL as an open platform for system-wide heterogeneous processing innovation. + +[[sec::unified-spec]] +== Unified specification + +This document provides the specification for both SYCL 2020 and SYCL +{SYCL_VERSION}. +It also provides the specification for extensions to the SYCL language in +<>. +and the specification for the OpenCL backend in <>. +All APIs in these extensions and the backend specification may be used with any +of the SYCL versions specified in this document unless the description +specifically states otherwise. + +If an API is documented as "Missing before SYCL __Version__", that API is newly +introduced in SYCL _Version_, so it is not available in versions of SYCL prior +to _Version_. + +If an API is documented as "Deprecated by SYCL __Version__", that API is still +supported, but its use is discouraged in SYCL _Version_ and in subsequent +versions of SYCL. + +If an API is documented as "Missing after SYCL __Version__", that API is removed +and no longer available in SYCL versions after _Version_. + // %%%%%%%%%%%%%%%%%%%%%%%%%%%% end introduction %%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 11333c35..c37393a0 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -2981,7 +2981,7 @@ Some queue member functions are shortcuts to member functions of the These are listed in <>. // Interface for class: queue -[source,,linenums] +[source,,linenums,subs="attributes+"] ---- include::{header_dir}/queue.h[lines=4..-1] ---- @@ -3230,7 +3230,7 @@ a@ ---- template event submit(T cgf, queue& secondaryQueue) ---- -a@ Deprecated in SYCL NEXT. +a@ Deprecated in SYCL {SYCL_VERSION}. Submit a <> to the queue, in order to be scheduled for execution on the device. On a kernel error, this <> is then scheduled for execution on the secondary queue. Returns an @@ -13383,7 +13383,7 @@ fall-back from primary to secondary queue are unspecified in the specification. Even if a command group is run on the secondary queue, the requirement that host code within the command group is executed exactly once remains, regardless of whether the fallback queue is used for execution. -The fallback queue feature is deprecated in SYCL NEXT. +The fallback queue feature is deprecated in SYCL {SYCL_VERSION}. The command group [code]#handler# class provides the interface for all of the member functions that are able to be executed inside the command group scope, @@ -16579,7 +16579,7 @@ context will be used and if the context was also constructed without an The <> event returned by that function will be relevant to the queue where the kernel has been enqueued. -The secondary queue feature is deprecated in SYCL NEXT. +The secondary queue feature is deprecated in SYCL {SYCL_VERSION}. Below is an example of catching a SYCL [code]#exception# and printing out the error message. @@ -21194,9 +21194,9 @@ a group. The result of a call to these functions is non-deterministic if the binary operator is not commutative and associative. -Only the binary operators defined in <> are supported by -the [code]#reduce# functions in SYCL 2020, but the standard {cpp} syntax is used -for forward compatibility with future SYCL versions. +Only the binary operators defined in <> are currently +supported by the SYCL [code]#reduce# functions, but the standard {cpp} syntax is +used for forward compatibility with future SYCL versions. [source,,linenums] ---- @@ -21328,8 +21328,8 @@ result returned to each work-item represents a partial prefix sum. The result of a call to a scan is non-deterministic if the binary operator is not associative. -Only the binary operators defined in <> are supported by -the scan functions in SYCL 2020, but the standard {cpp} syntax is used for +Only the binary operators defined in <> are currently +supported by the SYCL scan functions, but the standard {cpp} syntax is used for forward compatibility with future SYCL versions. [source,,linenums] diff --git a/adoc/chapters/what_changed.adoc b/adoc/chapters/what_changed.adoc index dd7c0906..f4322252 100644 --- a/adoc/chapters/what_changed.adoc +++ b/adoc/chapters/what_changed.adoc @@ -4,7 +4,7 @@ [[cha:what-changed-from]] = What has changed from previous versions -== What has changed from SYCL 2020 to SYCL NEXT +== What has changed from SYCL 2020 to SYCL {SYCL_VERSION} * The overload with a fallback/secondary queue parameter of the [code]#submit()# member function of [code]#sycl::queue# was deprecated. diff --git a/adoc/extensions/index.adoc b/adoc/extensions/index.adoc new file mode 100644 index 00000000..07062df6 --- /dev/null +++ b/adoc/extensions/index.adoc @@ -0,0 +1,13 @@ +[appendix] +[[chapter:extensions]] += Optional extensions + +Each of the optional extensions in this appendix has been approved by the SYCL +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] diff --git a/adoc/headers/queue.h b/adoc/headers/queue.h index 10d4c6ed..fa9a22c9 100644 --- a/adoc/headers/queue.h +++ b/adoc/headers/queue.h @@ -60,7 +60,7 @@ class queue { template event submit(T cgf); - // Deprecated in SYCL NEXT. + // Deprecated in SYCL {SYCL_VERSION}. template event submit(T cgf, const queue& secondaryQueue); void wait(); diff --git a/adoc/scripts/verify_reflow_conformance.sh b/adoc/scripts/verify_reflow_conformance.sh index 3e51d3f9..9253a9ac 100755 --- a/adoc/scripts/verify_reflow_conformance.sh +++ b/adoc/scripts/verify_reflow_conformance.sh @@ -1,11 +1,13 @@ #!/usr/bin/env bash error=0 -for file in adoc/chapters/*.adoc; +for file in adoc/chapters/*.adoc adoc/extensions/*.adoc; do echo "$file" - ./adoc/scripts/reflow.py -out tmp_ci/ -- "$file" - diff "$file" "${file/adoc\/chapters/tmp_ci}" + dir=`dirname $file` + dir=`basename $dir` + ./adoc/scripts/reflow.py -out "tmp_ci/$dir" -- "$file" + diff "$file" "${file/adoc/tmp_ci}" error=$((error+$?)) done diff --git a/adoc/syclbase.adoc b/adoc/syclbase.adoc index 1439f542..078aad23 100644 --- a/adoc/syclbase.adoc +++ b/adoc/syclbase.adoc @@ -158,5 +158,7 @@ include::chapters/what_changed.adoc[] include::chapters/references.adoc[] +include::extensions/index.adoc[] + include::chapters/glossary.adoc[] //endif::[]