Add framework for unified spec

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.

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
 

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
+<<chapter:extensions>>.
+and the specification for the OpenCL backend in <<chapter:opencl-backend>>.
+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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%

adoc/chapters/programming_interface.adoc

@@ -2981,7 +2981,7 @@ Some queue member functions are shortcuts to member functions of the
 These are listed in <<sec:queue-shortcuts>>.
 
 // Interface for class: queue
-[source,,linenums]
+[source,,linenums,subs="attributes+"]
 ----
 include::{header_dir}/queue.h[lines=4..-1]
 ----
@@ -3230,7 +3230,7 @@ a@
 ----
 template <typename T> event submit(T cgf, queue& secondaryQueue)
 ----
-a@ Deprecated in SYCL NEXT.
+a@ Deprecated in SYCL {SYCL_VERSION}.
 Submit a <<command-group-function-object>> to the queue, in order to be scheduled
 for execution on the device. On a kernel error, this <<command-group-function-object>>
 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 <<command-group-function-object>> 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 <<sec:function-objects>> 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 <<sec:function-objects>> 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 <<sec:function-objects>> are supported by
-the scan functions in SYCL 2020, but the standard {cpp} syntax is used for
+Only the binary operators defined in <<sec:function-objects>> are currently
+supported by the SYCL scan functions, but the standard {cpp} syntax is used for
 forward compatibility with future SYCL versions.
 
 [source,,linenums]

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.

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]

adoc/headers/queue.h

@@ -60,7 +60,7 @@ class queue {
 
   template <typename T> event submit(T cgf);
 
-  // Deprecated in SYCL NEXT.
+  // Deprecated in SYCL {SYCL_VERSION}.
   template <typename T> event submit(T cgf, const queue& secondaryQueue);
 
   void wait();

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
 

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::[]