diff --git a/.github/workflows/open_cts_issue.yml b/.github/workflows/open_cts_issue.yml index 37b142a1..44a9f76a 100644 --- a/.github/workflows/open_cts_issue.yml +++ b/.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. diff --git a/adoc/Makefile b/adoc/Makefile index 2f22bdb2..d7b910f7 100644 --- a/adoc/Makefile +++ b/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. diff --git a/adoc/chapters/architecture.adoc b/adoc/chapters/architecture.adoc index b1555b24..1a1f0793 100644 --- a/adoc/chapters/architecture.adoc +++ b/adoc/chapters/architecture.adoc @@ -1518,6 +1518,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 <> takes a reference to a command group 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 57547b99..5bbf7ba4 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -412,7 +412,7 @@ a@ required for the underlying <> specified in the <> 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 <>. See the relevant backend specification for details. @@ -3033,7 +3033,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] ---- @@ -3282,7 +3282,8 @@ a@ ---- template event submit(T cgf, queue& secondaryQueue) ---- -a@ Submit a <> to the queue, in order to be scheduled +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 event, which corresponds to the queue the <> @@ -10259,7 +10260,7 @@ modification of shared allocations through the aspect See <> in <> 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. @@ -13434,6 +13435,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, @@ -16530,7 +16532,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 <>. @@ -16629,6 +16631,8 @@ 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 {SYCL_VERSION}. + Below is an example of catching a SYCL [code]#exception# and printing out the error message. @@ -21242,9 +21246,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] ---- @@ -21376,8 +21380,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 5085b0d3..f4322252 100644 --- a/adoc/chapters/what_changed.adoc +++ b/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 diff --git a/adoc/code/usm_device.cpp b/adoc/code/usm_device.cpp index 36f499a1..8e0d88c8 100644 --- a/adoc/code/usm_device.cpp +++ b/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(1024, myQueue); myQueue.parallel_for(1024, [=](id<1> idx) { 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 233bc6b7..fa9a22c9 100644 --- a/adoc/headers/queue.h +++ b/adoc/headers/queue.h @@ -60,6 +60,7 @@ class queue { template event submit(T cgf); + // 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::[] diff --git a/sycl_version.txt b/sycl_version.txt index 4b2c507a..180d44fe 100644 --- a/sycl_version.txt +++ b/sycl_version.txt @@ -1,4 +1,4 @@ -SYCLLANGVERSION=2020 +SYCLLANGVERSION=NEXT SYCLNAME=SYCL -SYCLVERSION=2020 -SYCLREVISION=10 +SYCLVERSION=NEXT +SYCLREVISION=1