Skip to content

Commit

Permalink
Merge branch 'pub/main' into gmlueck/reformat-queue
Browse files Browse the repository at this point in the history
  • Loading branch information
gmlueck committed Sep 19, 2024
2 parents dd5ee47 + 781e4fe commit fe00ade
Show file tree
Hide file tree
Showing 12 changed files with 72 additions and 28 deletions.
2 changes: 0 additions & 2 deletions .github/workflows/open_cts_issue.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
10 changes: 2 additions & 8 deletions adoc/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions adoc/chapters/architecture.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
24 changes: 24 additions & 0 deletions adoc/chapters/introduction.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%
23 changes: 14 additions & 9 deletions adoc/chapters/programming_interface.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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]
----
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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>>.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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]
----
Expand Down Expand Up @@ -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]
Expand Down
6 changes: 5 additions & 1 deletion adoc/chapters/what_changed.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 1 addition & 2 deletions adoc/code/usm_device.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
13 changes: 13 additions & 0 deletions adoc/extensions/index.adoc
Original file line number Diff line number Diff line change
@@ -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]
1 change: 1 addition & 0 deletions adoc/headers/queue.h
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down
8 changes: 5 additions & 3 deletions adoc/scripts/verify_reflow_conformance.sh
Original file line number Diff line number Diff line change
@@ -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

Expand Down
2 changes: 2 additions & 0 deletions adoc/syclbase.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -158,5 +158,7 @@ include::chapters/what_changed.adoc[]

include::chapters/references.adoc[]

include::extensions/index.adoc[]

include::chapters/glossary.adoc[]
//endif::[]
6 changes: 3 additions & 3 deletions sycl_version.txt
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
SYCLLANGVERSION=2020
SYCLLANGVERSION=NEXT
SYCLNAME=SYCL
SYCLVERSION=2020
SYCLREVISION=10
SYCLVERSION=NEXT
SYCLREVISION=1

0 comments on commit fe00ade

Please sign in to comment.