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

.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.
 

README.md

@@ -2,8 +2,8 @@
 
 <!-- to update to newer CI when going public ![Build Status](https://api.travis-ci.com/KhronosGroup/SYCL-Docs.svg?branch=master) -->
 <!-- to update to newer CI when going public [![SPEC master](https://img.shields.io/badge/SPEC-master-red.svg?logo=adobe-acrobat-reader)](https://khronosgroup.github.io/SYCL-Docs/sycl/sycl.pdf) -->
-[![SPEC 2020-8](https://img.shields.io/badge/SPEC-2020--8-orange.svg?logo=adobe-acrobat-reader)](https://www.khronos.org/registry/SYCL/specs/sycl-2020/pdf/sycl-2020.pdf)
-[![SPEC 2020-8](https://img.shields.io/badge/SPEC-2020--8-orange.svg?logo=HTML5)](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html)
+[![SPEC 2020-9](https://img.shields.io/badge/SPEC-2020--9-orange.svg?logo=adobe-acrobat-reader)](https://www.khronos.org/registry/SYCL/specs/sycl-2020/pdf/sycl-2020.pdf)
+[![SPEC 2020-9](https://img.shields.io/badge/SPEC-2020--9-orange.svg?logo=HTML5)](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html)
 [![SPEC latest](https://img.shields.io/badge/SPEC-latest-red.svg?logo=adobe-acrobat-reader)](https://github.com/KhronosGroup/SYCL-Docs/actions?query=branch%3ASYCL-2020%2Fmaster+is%3Asuccess)
 [![Join the Slack group](https://img.shields.io/badge/chat-on%20slack-blue.svg?logo=slack)](https://khr.io/slack)
 

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

@@ -16,10 +16,10 @@ can run on either an heterogeneous device or on the <<host>>.
 The terminology used for SYCL inherits historically from OpenCL with some
 SYCL-specific additions.
 However SYCL is a generic {cpp} programming model that can be laid out on top of
-other heterogeneous APIs apart from OpenCL.
-SYCL implementations can provide <<backend>>s for various heterogeneous APIs,
-implementing the SYCL general specification on top of them.
-We refer to this heterogeneous API as the <<backend-api>>.
+other APIs apart from OpenCL.
+SYCL implementations can provide <<backend>>s for various APIs, implementing the
+SYCL general specification on top of them.
+We refer to this API as the <<backend-api>>.
 The SYCL general specification defines the behavior that all SYCL
 implementations must expose to SYCL users for a SYCL application to behave as
 expected.
@@ -62,7 +62,7 @@ developers in other fields.
 == Anatomy of a SYCL application
 
 Below is an example of a typical <<sycl-application>> which schedules a job to
-run in parallel on any heterogeneous device available.
+run in parallel on any device available.
 
 // An AsciiDoctor "feature", the language is specified as the second
 // parameter of this attribute, even if we do not want it. So add a
@@ -186,8 +186,8 @@ correct.
 [[sec:platformmodel]]
 == The SYCL platform model
 
-The SYCL platform model consists of a host connected to one or more
-heterogeneous devices, called <<device,devices>>.
+The SYCL platform model consists of a host connected to one or more devices,
+called <<device,devices>>.
 <<device,Devices>> are grouped together into one or multiple <<platform,
 platforms>>.
 An implementation may also expose empty <<platform, platforms>> that do not
@@ -215,8 +215,7 @@ The <<sycl-runtime>> then extracts operations from the
 <<sycl-kernel-function>>.
 When the operation is a <<sycl-kernel-function>>, the <<sycl-runtime>> uses a
 <<backend>>-specific mechanism to extract the device binary from the SYCL
-application and pass it to the heterogeneous API for execution on the
-<<device>>.
+application and pass it to the <<backend-api>> for execution on the <<device>>.
 
 A SYCL <<device>> is divided into one or more compute units (CUs) which are each
 divided into one or more processing elements (PEs).
@@ -241,7 +240,7 @@ programmable kernels, and only support _built-in_ functions.
 == The SYCL backend model
 
 SYCL is a generic programming model for the {cpp} language that can target
-multiple heterogeneous APIs, such as OpenCL.
+multiple APIs, such as OpenCL.
 
 SYCL implementations enable these target APIs by implementing <<backend, SYCL
 backends>>.
@@ -270,8 +269,8 @@ guarantee that said backends can be executed at runtime.
 The subset of active backends available at runtime is called _available
 backends_.
 A backend is said to be _available_ if the host platform where the SYCL
-application is executed exposes support for the heterogeneous API required for
-the <<backend>>.
+application is executed exposes support for the API required for the
+<<backend>>.
 
 It is implementation dependent whether certain backends require third-party
 libraries to be available in the system.
@@ -366,8 +365,7 @@ been satisfied.
 ==== Backend resources managed by the SYCL application
 
 The SYCL runtime integrated with the SYCL application will manage the resources
-required by the <<backend-api>> to manage the heterogeneous devices it is
-providing access to.
+required by the <<backend-api>> to manage the devices it is providing access to.
 This includes, but is not limited to, resource handlers, memory pools, dispatch
 queues and other temporary handler objects.
 
@@ -1520,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 <<command-group-function-object>> takes a reference to a command group

adoc/chapters/information_descriptors.adoc

@@ -11,7 +11,7 @@ introduced in <<chapter:sycl-programming-interface>>.
 == Platform information descriptors
 
 The following interface includes all the information descriptors for the
-[code]#platform# class as described in <<table.platform.info>>.
+[code]#platform# class.
 [source,,linenums]
 ----
 include::{header_dir}/platformInfo.h[lines=4..-1]

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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%