Merge branch 'pub/main' into gmlueck/reformat-queue

.github/workflows/open_cts_issue.yml

@@ -31,8 +31,6 @@ jobs:
           repo: SYCL-CTS
           title: |
             [Spec change] ${{ github.event.pull_request.title }}
-          # Assign person who opened PR
-          assignees: ${{ github.triggering_actor }}
           body: |
             Please review whether ${{ github.event.pull_request.html_url }} by @${{ github.triggering_actor }} requires any changes to the CTS.
 

adoc/Makefile

@@ -67,14 +67,8 @@ VERBOSE = --verbose
 # SYCL_VERSION & SYCL_REVISION) are based on this external configuration file:
 include $(SYCL_DIR)/sycl_version.txt
 
-# In particular, SYCL_LANGUAGE_VERSION is derived from other values
-SYCL_LANGUAGE_VERSION=$(shell printf "%04d%02d" $(SYCLLANGVERSION) \
-  $(SYCLREVISION))
-SYCL_NAME=$(SYCLNAME)
-SYCL_VERSION=$(SYCLVERSION)
-SYCL_REVISION=$(SYCLREVISION)
 # Name the generated spec from the revision
-SPEC_BASE_NAME=$(shell echo $(SYCL_NAME)-$(SYCL_VERSION) \
+SPEC_BASE_NAME=$(shell echo $(SYCLNAME)-$(SYCLVERSION) \
   | tr [:upper:] [:lower:])
 
 # asciidoc build attributes to set (defaults are usually OK)
@@ -170,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

@@ -1519,6 +1519,8 @@ 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 {SYCL_VERSION}.
+
 === Scheduling of kernels and data movement
 
 A <<command-group-function-object>> takes a reference to a command group

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

@@ -412,7 +412,7 @@ a@
       required for the underlying <<native-backend-object>> specified in
       the <<backend>> specification document, if this SYCL [code]#T# instance
       was originally constructed using one of the backend interoperability
-      [code]#make_*# functions specified in 
+      [code]#make_*# functions specified in
       <<sec:backend-interoperability-make>>.
       See the relevant backend specification for details.
 
@@ -2954,7 +2954,7 @@ completes.
 The [code]#queue# class provides the common reference semantics as defined in
 <<sec:reference-semantics>>.
 
-[source,role=synopsis]
+[source,role=synopsis,subs="attributes+"]
 ----
 include::{header_dir}/queue.h[lines=4..-1]
 ----
@@ -3241,6 +3241,8 @@ template <typename T>
 event submit(T cgf, queue& secondaryQueue)
 ----
 
+Deprecated in SYCL {SYCL_VERSION}.
+
 _Effects:_ Immediately calls the <<command-group-function-object>> [code]#cgf#,
 which may submit no more than one <<command>> to the queue for execution on the
 device.
@@ -10211,7 +10213,7 @@ modification of shared allocations through the aspect
 See <<table.device.aspect>> in <<sec:device-aspects>> for more details.
 
 Performance hints for shared allocations may be specified by the user by
-enqueueing [code]#prefetch# operations on a device.
+enqueuing [code]#prefetch# operations on a device.
 These operations inform the SYCL runtime that the specified shared allocation is
 likely to be accessed on the device in the future, and that it is free to
 migrate the allocation to the device.
@@ -13386,6 +13388,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 {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,
@@ -16482,7 +16485,7 @@ executions are decoupled from one another except at specific points.
 For example, device code executions often begin when dependencies in the SYCL
 task graph are satisfied, which occurs asynchronously from host code execution.
 As a result of this the errors that occur on a device cannot be thrown directly
-from a host API call, because the call enqueueing a device action has typically
+from a host API call, because the call enqueuing a device action has typically
 already returned by the time that the error occurs.
 Such errors are not detected until the error-causing task executes or tries to
 execute, and we refer to these as <<async-error,asynchronous errors>>.
@@ -16581,6 +16584,8 @@ 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 {SYCL_VERSION}.
+
 Below is an example of catching a SYCL [code]#exception# and printing out the
 error message.
 
@@ -21194,9 +21199,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 +21333,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,11 @@
 [[cha:what-changed-from]]
 = What has changed from previous versions
 
-[[sec:what-changed-between]]
+== 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.
+
 == What has changed from SYCL 1.2.1 to SYCL 2020
 
 The SYCL runtime moved from namespace [code]#cl::sycl# provided by

adoc/code/usm_device.cpp

@@ -9,8 +9,7 @@ int main() {
   // Create a default queue to enqueue work to the default device
   queue myQueue;
 
-  // Allocate shared memory bound to the device and context associated to the
-  // queue
+  // Allocate device USM, using the device and context associated with the queue
   int* data = sycl::malloc_device<int>(1024, myQueue);
 
   myQueue.parallel_for(1024, [=](id<1> idx) {

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

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

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

sycl_version.txt

@@ -1,4 +1,4 @@
-SYCLLANGVERSION=2020
+SYCLLANGVERSION=NEXT
 SYCLNAME=SYCL
-SYCLVERSION=2020
-SYCLREVISION=10
+SYCLVERSION=NEXT
+SYCLREVISION=1