Merge branch 'pub/SYCL-2020/master' into gmlueck/reformat-platform

.github/workflows/open_cts_issue.yml

@@ -0,0 +1,30 @@
+name: Open CTS issue for spec changes
+on: pull_request
+jobs:
+  create-issue:
+    runs-on: ubuntu-latest
+    # Skip if this is a purely editorial PR
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'editorial') }}
+    steps:
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ vars.SYCL_ISSUE_BOT_APP_ID }}
+          private-key: ${{ secrets.SYCL_ISSUE_BOT_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: "SYCL-CTS"
+      - name: Create Issue
+        uses: dacbd/create-issue-action@v2.0.0
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          owner: ${{ github.repository_owner }}
+          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.
+
+            **If changes are required**: Open a new PR addressing the changes and link it to this issue.
+            **If no changes are required**: Close this issue and proceed with the spec PR.

adoc/chapters/programming_interface.adoc

@@ -18,7 +18,7 @@ The underlying types for all enumerations defined in this specification are
 implementation-defined.
 In addition, all enumerators within an enumeration have some
 implementation-defined unique value unless the specification specifically
-indicates a values for the enumerator.
+indicates a value for the enumerator.
 
 
 [[sec:backends]]
@@ -48,7 +48,7 @@ specification.
 === Backend macros
 
 As the identifiers defined in [code]#enum class backend# are
-implementation-defined, and the associated backends not guaranteed to be
+implementation-defined, and the associated backends are not guaranteed to be
 available, a SYCL implementation must also define a preprocessor macro for each
 of these identifiers.
 If the <<backend>> is defined by the Khronos SYCL group, the name of the macro
@@ -249,15 +249,15 @@ interoperability, a specialization of [code]#get_native# must be defined, which
 takes an instance of [code]#T# and returns a <<sycl-application>>
 interoperability <<native-backend-object>> associated with [code]#syclObject#
 which can be used for <<sycl-application>> interoperability.
-The lifetime of the object returned are backend-defined and specified in the
+The lifetime of the object returned is backend-defined and specified in the
 backend specification.
 
 For each <<sycl-runtime>> class [code]#T# which supports kernel function
 interoperability, a specialization of [code]#get_native# must be defined, which
 takes an instance of [code]#T# and returns the kernel function interoperability
 <<native-backend-object>> associated with [code]#syclObject# which can be used
 for kernel function interoperability.
-The availability and behavior of these template functions is defined by the
+The availability and behavior of these template functions are defined by the
 <<backend>> specification document.
 
 The [code]#get_native# function must throw an [code]#exception# with the
@@ -277,7 +277,7 @@ interoperability, a specialization of the appropriate template function
 [code]#make_{sycl_class}# where [code]#{sycl_class}# is the class name of
 [code]#T#, must be defined, which takes a <<sycl-application>> interoperability
 <<native-backend-object>> and constructs and returns an instance of [code]#T#.
-The availability and behavior of these template functions is defined by the
+The availability and behavior of these template functions are defined by the
 <<backend>> specification document.
 
 Overloads of the [code]#make_{sycl_class}# function which take a SYCL
@@ -3874,14 +3874,14 @@ void wait_and_throw()
    a@ Blocks until all commands associated with this event and any dependent
       events have completed.
 
-At least all uncomsumed <<async-error,asynchronous errors>> held by queues (or
+At least all unconsumed <<async-error,asynchronous errors>> held by queues (or
 their associated contexts) which were used to enqueue commands associated with
-this event and any dependent events, are passed to the approriate
+this event and any dependent events, are passed to the appropriate
 <<async-handler>> as described in <<subsubsec:async.handler.priorities>>.
 
 [NOTE]
 ====
-This behaviour is equivalent to calling [code]#queue::throw_asynchronous()# on
+This behavior is equivalent to calling [code]#queue::throw_asynchronous()# on
 the queue associated with this event and any dependent events.
 ====
 
@@ -6544,7 +6544,7 @@ the accessor's range results in undefined behavior.
 ====
 There is no change in behavior for ranged accessors with a range of zero.
 It still creates a requisite for the entire underlying buffer, and an attempt to
-access an element produces undefined behaviour.
+access an element produces undefined behavior.
 ====
 
 ==== Buffer accessor for commands
@@ -10919,12 +10919,16 @@ a@
 ----
 void sycl::free(void* ptr, const context& syclContext)
 ----
-a@ Frees an allocation.  The memory pointed to by [code]#ptr# must have been
-allocated using one of the USM allocation routines.  [code]#syclContext# must
-be the same [code]#context# that was used to allocate the memory.  The memory
-is freed without waiting for <<command, commands>> operating on it to be
-completed.  If <<command, commands>> that use this memory are in-progress or
-are enqueued the behavior is undefined.
+a@ Frees an allocation.
+The memory pointed to by [code]#ptr# must have been allocated using one of the
+USM allocation routines or it must be a null pointer.
+If [code]#ptr# is not null, the [code]#syclContext# must be the same
+[code]#context# that was used to allocate the memory.
+If [code]#ptr# is null, this function has no effect.
+Otherwise, the memory is freed without waiting for <<command, commands>>
+operating on it to be completed.
+If <<command, commands>> that use this memory are in-progress or are enqueued,
+the behavior is undefined.
 
 a@
 [source]
@@ -18011,6 +18015,9 @@ void load(size_t offset, multi_ptr<const DataT, AddressSpace, IsDecorated> ptr)
 |====
 _Availability:_ Available only in [code]#+__writeable_swizzle__+#.
 
+_Constraints:_ Available only when the [code]#+__writeable_swizzle__+# view does
+not contain any repeated elements.
+
 _Effects:_ Loads values from memory into elements of the underlying [code]#vec#
 object.
 A total of [code]#NumElements# values are loaded from memory, starting at the
@@ -18226,9 +18233,12 @@ Where [code]#OP# is: [code]#pass:[+=]#, [code]#-=#, [code]#*=#, [code]#/=#,
 _Availability:_ These are hidden friend functions only in
 [code]#+__writeable_swizzle__+#.
 
-_Constraints:_ If [code]#OP# is one of the following: [code]#%=#, [code]#&=#,
-[code]#|=#, [code]#^=#, [code]#+<<=+#, [code]#>>=#; available only when:
-[code]#DataT != float && DataT != double && DataT != half#.
+_Constraints:_ Available only when the left hand side
+[code]#+__writeable_swizzle__+# view does not contain any repeated elements.
+
+If [code]#OP# is one of the following: [code]#%=#, [code]#&=#, [code]#|=#,
+[code]#^=#, [code]#+<<=+#, [code]#>>=#; available only when: [code]#DataT !=
+float && DataT != double && DataT != half#.
 
 In addition, overloads (1) and (2) are available only when the element data type
 of [code]#lhs# is the same as the element data type of [code]#rhs# and when the
@@ -18269,7 +18279,9 @@ Where [code]#OP# is: [code]#pass:[++]#, [code]#--#.
 _Availability:_ These are hidden friend functions only in
 [code]#+__writeable_swizzle__+#.
 
-_Constraints:_ Available only when [code]#DataT# is not [code]#bool#.
+_Constraints:_ Available only when the [code]#+__writeable_swizzle__+# view does
+not contain any repeated elements.
+Available only when [code]#DataT# is not [code]#bool#.
 
 _Effects:_ Perform an in-place element-wise [code]#OP# prefix arithmetic
 operation on those elements of the [code]#vec# object that have corresponding
@@ -18294,7 +18306,9 @@ Where [code]#OP# is: [code]#pass:[++]#, [code]#--#.
 _Availability:_ These are hidden friend functions only in
 [code]#+__writeable_swizzle__+#.
 
-_Constraints:_ Available only when [code]#DataT# is not [code]#bool#.
+_Constraints:_ Available only when the [code]#+__writeable_swizzle__+# view does
+not contain any repeated elements.
+Available only when [code]#DataT# is not [code]#bool#.
 
 _Effects:_ Perform an in-place element-wise [code]#OP# postfix arithmetic
 operation on those elements of the [code]#vec# object that have corresponding

adoc/chapters/what_changed.adoc

@@ -387,7 +387,7 @@ Changes in [code]#multi_ptr# interface:
   * [code]#global_ptr#, [code]#local_ptr# and [code]#private_ptr# alias take the
     new extra parameter;
   * addition of the [code]#address_space_cast# free function to cast undecorated
-    pointer to [code]#multi_pointer#;
+    pointer to [code]#multi_ptr#;
   * addition of construction/conversion operator for the generic address space;
   * removal of the constructor and assignment operator taking an unannotated
     pointer;

adoc/scripts/reflow.py

@@ -53,7 +53,9 @@
 # A single letter followed by a period, typically a middle initial.
 endInitial = re.compile(r'^[A-Z]\.$')
 # An abbreviation, which does not (usually) end a line.
-endAbbrev = re.compile(r'(e\.g|i\.e|c\.f|\bvs\b|\bco\b|\bltd\b|\bch\b|\betc)\.$', re.IGNORECASE)
+endAbbrev = re.compile(r'(e\.g|i\.e|c\.f|\bvs\b|\bco\b|\bltd\b|\bch\b)\.$', re.IGNORECASE)
+# A lower case word.  When "etc." is followed by this, it does not end a line.
+startsLowerCase = re.compile(r'\(?[a-z]')
 
 # Explicit Valid Usage list item with one or more leading asterisks
 # The re.DOTALL is needed to prevent vuPat.search() from stripping
@@ -125,15 +127,17 @@ def __init__(self,
         self.warnCount = 0
         """Count of markup check warnings encountered."""
 
-    def endSentence(self, word):
+    def endSentence(self, word, nextWord):
         """Return True if word ends with a sentence-period, False otherwise.
 
         Allows for contraction cases which will not end a line:
 
          - A single letter (if breakInitial is True)
-         - Abbreviations: 'c.f.', 'e.g.', 'i.e.' (or mixed-case versions)"""
+         - Abbreviations: 'c.f.', 'e.g.', 'i.e.' (or mixed-case versions)
+         - The word "etc." when it is followed by a lower case word"""
         if ((word[-1:] != '.' and word[-2:] != '.)') or
             endAbbrev.search(word) or
+            word == "etc." and startsLowerCase.match(nextWord) or
                 (self.breakInitial and endInitial.match(word))):
             return False
 
@@ -405,7 +409,7 @@ def transformParagraph(self, para, state):
                             (addWord, closeLine, startLine) = (False, True, True)
                     elif (self.breakPeriod and
                           (wordCount > 2 or not firstBullet) and
-                          self.endSentence(prevWord)):
+                          self.endSentence(prevWord, word)):
                         # If the previous word ends a sentence and
                         # breakPeriod is set, start a new line.
                         # The complicated logic allows for leading bullet