From 940065ff034471bc4759ac4910ad36619a45428b Mon Sep 17 00:00:00 2001
From: Dzmitry Malyshau <dmalyshau@mozilla.com>
Date: Thu, 22 Oct 2020 17:45:53 -0400
Subject: [PATCH 1/5] Multi-queue synchronization

---
 spec/index.bs | 151 +++++++++++++++++++-------------------------------
 1 file changed, 57 insertions(+), 94 deletions(-)

diff --git a/spec/index.bs b/spec/index.bs
index d1701d95c0..9fbdb1c606 100644
--- a/spec/index.bs
+++ b/spec/index.bs
@@ -2018,6 +2018,8 @@ dictionary GPUTextureViewDescriptor : GPUObjectDescriptorBase {
 };
 </script>
 
+Issue: derive from `GPUTextureSubresourceRange`
+
 Issue: Make this a standalone algorithm used in the createView algorithm.
 
 Issue: The references to GPUTextureDescriptor here should actually refer to
@@ -6321,11 +6323,37 @@ dictionary GPURenderBundleEncoderDescriptor : GPUObjectDescriptorBase {
 # Queues # {#queues}
 
 <script type=idl>
+typedef [EnforceRange] unsigned long long GPUSignalValue;
+
+dictionary GPUTextureSubresourceRange {
+    GPUTextureAspect aspect = "all";
+    GPUIntegerCoordinate baseMipLevel = 0;
+    GPUIntegerCoordinate mipLevelCount;
+    GPUIntegerCoordinate baseArrayLayer = 0;
+    GPUIntegerCoordinate arrayLayerCount;
+};
+
+dictionary GPUTextureSubresources: GPUTextureSubresourceRange {
+    required GPUTexture texture;
+};
+
+dictionary GPUResourceTransfer {
+    required GPUQueue receivingQueue;
+    required sequence<GPUBuffer> buffers;
+    required sequence<GPUTextureSubresources> textureSubresources;
+};
+
 interface GPUQueue {
-    undefined submit(sequence<GPUCommandBuffer> commandBuffers);
+    GPUSignalValue signal();
+    readonly attribute GPUSignalValue lastSignaledValue;
+
+    undefined wait(GPUQueue queue, optional GPUSignalValue value);
 
-    GPUFence createFence(optional GPUFenceDescriptor descriptor = {});
-    undefined signal(GPUFence fence, GPUFenceValue signalValue);
+    undefined submit(
+        sequence<GPUCommandBuffer> commandBuffers,
+        optional sequence<GPUResourceTransfer> transfers = []);
+
+    Promise<undefined> onCompletion(optional GPUSignalValue value);
 
     undefined writeBuffer(
         GPUBuffer buffer,
@@ -6350,6 +6378,13 @@ GPUQueue includes GPUObjectBase;
 
 {{GPUQueue}} has the following methods:
 
+<dl dfn-type=attribute dfn-for=GPUQueue>
+    : <dfn>lastSignaledValue</dfn> of type {{GPUSignalValue}}, readonly
+    ::
+        The smallest signal value representing the progress of all the work that has been submitted
+        to the queue by this moment on the [=content timeline=].
+</dl>
+
 <dl dfn-type=method dfn-for=GPUQueue>
     : <dfn>writeBuffer(buffer, bufferOffset, data, dataOffset, size)</dfn>
     ::
@@ -6498,8 +6533,10 @@ GPUQueue includes GPUObjectBase;
             **Called on:** {{GPUQueue}} this.
 
             **Arguments:**
-            <pre class=argumentdef for="GPUQueue/submit(commandBuffers)">
-                |commandBuffers|:
+            <pre class=argumentdef for="GPUQueue/submit(commandBuffers, transfers)">
+                |commandBuffers|: list of {{GPUCommandBuffer}} to execute.
+                |transfers|: list of {{GPUResourceTransfer}} that represent transferring
+                    resource ownership from this {{GPUQueue}} to the others.
             </pre>
 
             **Returns:** {{undefined}}
@@ -6516,108 +6553,35 @@ GPUQueue includes GPUObjectBase;
                     <div class=queue-timeline>
                         1. For each |commandBuffer| in |commandBuffers|:
                             1. Execute each command in |commandBuffer|.{{GPUCommandBuffer/[[command_list]]}}.
+                        1. For each |transfer| in |transfers|:
+                            1. Transfer the |transfer|.{{GPUResourceTransfer/buffers}} to
+                                |transfer|.{{GPUResourceTransfer/receivingQueue}}.
+                            1. Transfer the |transfer|.{{GPUResourceTransfer/textureSubresources}} to
+                                |transfer|.{{GPUResourceTransfer/receivingQueue}}.
                     </div>
             </div>
         </div>
-</dl>
-
-## <dfn interface>GPUFence</dfn> ## {#fence}
-
-<script type=idl>
-interface GPUFence {
-    GPUFenceValue getCompletedValue();
-    Promise<undefined> onCompletion(GPUFenceValue completionValue);
-};
-GPUFence includes GPUObjectBase;
-</script>
-
-### Creation ### {#fence-creation}
 
-<script type=idl>
-dictionary GPUFenceDescriptor : GPUObjectDescriptorBase {
-    GPUFenceValue initialValue = 0;
-};
-</script>
-
-<dl dfn-type=method dfn-for=GPUQueue>
-    : <dfn>createFence(descriptor)</dfn>
+    : <dfn>wait(queue, value)</dfn>
     ::
-        Creates a {{GPUFence}}.
+        Waits for the |queue| reaching |value| on the [=Queue timeline=]. If |value| is undefined,
+        the |queue|.{{GPUQueue/lastSignaledValue}} is used instead.
 
-        <div algorithm="GPUQueue.createFence">
-            **Called on:** {{GPUQueue}} this.
+        All the resource transitions from |queue| targeting |this| will be considered done on the [=Queue timeline=]
+        after this call, and relevant resources can be used on |this|.
 
-            **Arguments:**
-            <pre class=argumentdef for="GPUQueue/createFence(descriptor)">
-                descriptor: Description of the {{GPUFence}} to create.
-            </pre>
-
-            **Returns:** {{GPUFence}}
-
-            Issue: Describe {{GPUQueue/createFence()}} algorithm steps.
-        </div>
-</dl>
-
-### Completion ### {#fence-signaling}
-
-Completion of a fence is signaled from the {{GPUQueue}} that created it.
-
-<dl dfn-type=method dfn-for=GPUQueue>
-    : <dfn>signal(fence, signalValue)</dfn>
+    : <dfn>signal()</dfn>
     ::
-        Signals the given fence, increasing it's completed value to `signalValue`.
-
-        <div algorithm="GPUQueue.signal">
-            **Called on:** {{GPUQueue}} this.
-
-            **Arguments:**
-            <pre class=argumentdef for="GPUQueue/signal(fence, signalValue)">
-                |fence|: The fence to signal.
-                signalValue: The value to increase |fence|'s completion value to.
-            </pre>
-
-            **Returns:** {{undefined}}
-
-            Issue: Describe {{GPUQueue/signal()}} algorithm steps.
-        </div>
-</dl>
-
-The completion of the fence and the value it completes with can be observed from the {{GPUFence}}.
-
-<dl dfn-type=method dfn-for=GPUFence>
-    : <dfn>getCompletedValue()</dfn>
-    ::
-        Returns the largest signalled value completion value for the fence that has propagated to
+        Returns the largest signalled value for the queue that has propagated to
         the [=content timeline=].
 
-        <div algorithm="GPUFence.getCompletedValue">
-            **Called on:** {{GPUFence}} this.
-
-            **Returns:** {{GPUFenceValue}}
-
-            Issue: Describe {{GPUFence/getCompletedValue()}} algorithm steps.
-        </div>
-
-    : <dfn>onCompletion(completionValue)</dfn>
+    : <dfn>onCompletion(signalValue)</dfn>
     ::
-        Returns a {{Promise}} that resolves once the fence's completion value &ge; `completionValue`.
+        Returns a {{Promise}} that resolves once the queue reaches `signalValue`
+        (or |this|.{{GPUQueue/lastSignaledValue}}) if undefined) on the [=content timeline=].
 
-        <div algorithm="GPUFence.onCompletion">
-            **Called on:** {{GPUFence}} this.
-
-            **Arguments:**
-            <pre class=argumentdef for="GPUFence/onCompletion(completionValue)">
-                completionValue: The completion value that the fence must meet or exceed before
-                    resolving the returned {{Promise}}
-            </pre>
-
-            **Returns:** {{Promise}}&lt;{{undefined}}&gt;
-
-            Issue: Describe {{GPUFence/onCompletion()}} algorithm steps.
-        </div>
 </dl>
 
-
 Queries {#queries}
 ================
 
@@ -6907,7 +6871,6 @@ partial interface GPUDevice {
 
 <script type=idl>
 typedef [EnforceRange] unsigned long GPUBufferDynamicOffset;
-typedef [EnforceRange] unsigned long long GPUFenceValue;
 typedef [EnforceRange] unsigned long GPUStencilValue;
 typedef [EnforceRange] unsigned long GPUSampleMask;
 typedef [EnforceRange] long GPUDepthBias;

From adaa652ef1e5f57e73b301211b06bd943f31c60f Mon Sep 17 00:00:00 2001
From: Dzmitry Malyshau <dmalyshau@mozilla.com>
Date: Fri, 23 Oct 2020 15:00:13 -0400
Subject: [PATCH 2/5] Minor edits according to Corentin's review

---
 spec/index.bs | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/spec/index.bs b/spec/index.bs
index 9fbdb1c606..9fa9c71e1b 100644
--- a/spec/index.bs
+++ b/spec/index.bs
@@ -6347,14 +6347,14 @@ interface GPUQueue {
     GPUSignalValue signal();
     readonly attribute GPUSignalValue lastSignaledValue;
 
+    Promise<undefined> onCompletion(optional GPUSignalValue value);
+
     undefined wait(GPUQueue queue, optional GPUSignalValue value);
 
     undefined submit(
         sequence<GPUCommandBuffer> commandBuffers,
         optional sequence<GPUResourceTransfer> transfers = []);
 
-    Promise<undefined> onCompletion(optional GPUSignalValue value);
-
     undefined writeBuffer(
         GPUBuffer buffer,
         GPUSize64 bufferOffset,
@@ -6381,8 +6381,7 @@ GPUQueue includes GPUObjectBase;
 <dl dfn-type=attribute dfn-for=GPUQueue>
     : <dfn>lastSignaledValue</dfn> of type {{GPUSignalValue}}, readonly
     ::
-        The smallest signal value representing the progress of all the work that has been submitted
-        to the queue by this moment on the [=content timeline=].
+        The last value returned by {{GPUQueue/signal()}}.
 </dl>
 
 <dl dfn-type=method dfn-for=GPUQueue>
@@ -6572,7 +6571,7 @@ GPUQueue includes GPUObjectBase;
 
     : <dfn>signal()</dfn>
     ::
-        Returns the largest signalled value for the queue that has propagated to
+        Returns the largest signaled value for the queue that has propagated to
         the [=content timeline=].
 
     : <dfn>onCompletion(signalValue)</dfn>

From 0c5f268f4e17f74bebfff6776f7fde9237e3e57e Mon Sep 17 00:00:00 2001
From: Dzmitry Malyshau <dmalyshau@mozilla.com>
Date: Mon, 26 Oct 2020 10:05:34 -0400
Subject: [PATCH 3/5] Fix signal() documentation

---
 spec/index.bs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/spec/index.bs b/spec/index.bs
index 9fa9c71e1b..7995458f83 100644
--- a/spec/index.bs
+++ b/spec/index.bs
@@ -6571,8 +6571,8 @@ GPUQueue includes GPUObjectBase;
 
     : <dfn>signal()</dfn>
     ::
-        Returns the largest signaled value for the queue that has propagated to
-        the [=content timeline=].
+        Returns a signal value corresponding to the work submitted to the queue up to this moment on the [=content timeline=].
+        This value has to be higher or equal to return value of the previous call to {{GPUQueue/signal()}} on this queue.
 
     : <dfn>onCompletion(signalValue)</dfn>
     ::

From f4eb24d8f3237ad4074060f80724d665c80fefb6 Mon Sep 17 00:00:00 2001
From: Dzmitry Malyshau <dmalyshau@mozilla.com>
Date: Fri, 13 Nov 2020 15:54:22 -0500
Subject: [PATCH 4/5] Don't touch them fences

---
 spec/index.bs | 102 +++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 97 insertions(+), 5 deletions(-)

diff --git a/spec/index.bs b/spec/index.bs
index 7995458f83..b484790e1b 100644
--- a/spec/index.bs
+++ b/spec/index.bs
@@ -6347,14 +6347,15 @@ interface GPUQueue {
     GPUSignalValue signal();
     readonly attribute GPUSignalValue lastSignaledValue;
 
-    Promise<undefined> onCompletion(optional GPUSignalValue value);
-
     undefined wait(GPUQueue queue, optional GPUSignalValue value);
 
     undefined submit(
         sequence<GPUCommandBuffer> commandBuffers,
         optional sequence<GPUResourceTransfer> transfers = []);
 
+    GPUFence createFence(optional GPUFenceDescriptor descriptor = {});
+    undefined signal(GPUFence fence, GPUFenceValue signalValue);
+
     undefined writeBuffer(
         GPUBuffer buffer,
         GPUSize64 bufferOffset,
@@ -6573,14 +6574,104 @@ GPUQueue includes GPUObjectBase;
     ::
         Returns a signal value corresponding to the work submitted to the queue up to this moment on the [=content timeline=].
         This value has to be higher or equal to return value of the previous call to {{GPUQueue/signal()}} on this queue.
+</dl>
+
+## <dfn interface>GPUFence</dfn> ## {#fence}
+
+<script type=idl>
+interface GPUFence {
+    GPUFenceValue getCompletedValue();
+    Promise<undefined> onCompletion(GPUFenceValue completionValue);
+};
+GPUFence includes GPUObjectBase;
+</script>
+
+### Creation ### {#fence-creation}
+
+<script type=idl>
+dictionary GPUFenceDescriptor : GPUObjectDescriptorBase {
+    GPUFenceValue initialValue = 0;
+};
+</script>
+
+<dl dfn-type=method dfn-for=GPUQueue>
+    : <dfn>createFence(descriptor)</dfn>
+    ::
+        Creates a {{GPUFence}}.
+
+        <div algorithm="GPUQueue.createFence">
+            **Called on:** {{GPUQueue}} this.
+
+            **Arguments:**
+            <pre class=argumentdef for="GPUQueue/createFence(descriptor)">
+                descriptor: Description of the {{GPUFence}} to create.
+            </pre>
+
+            **Returns:** {{GPUFence}}
+
+            Issue: Describe {{GPUQueue/createFence()}} algorithm steps.
+        </div>
+</dl>
+
+### Completion ### {#fence-signaling}
+
+Completion of a fence is signaled from the {{GPUQueue}} that created it.
 
-    : <dfn>onCompletion(signalValue)</dfn>
+<dl dfn-type=method dfn-for=GPUQueue>
+    : <dfn>signal(fence, signalValue)</dfn>
     ::
-        Returns a {{Promise}} that resolves once the queue reaches `signalValue`
-        (or |this|.{{GPUQueue/lastSignaledValue}}) if undefined) on the [=content timeline=].
+        Signals the given fence, increasing it's completed value to `signalValue`.
+
+        <div algorithm="GPUQueue.signal">
+            **Called on:** {{GPUQueue}} this.
+
+            **Arguments:**
+            <pre class=argumentdef for="GPUQueue/signal(fence, signalValue)">
+                |fence|: The fence to signal.
+                signalValue: The value to increase |fence|'s completion value to.
+            </pre>
+
+            **Returns:** {{undefined}}
 
+            Issue: Describe {{GPUQueue/signal()}} algorithm steps.
+        </div>
 </dl>
 
+The completion of the fence and the value it completes with can be observed from the {{GPUFence}}.
+
+<dl dfn-type=method dfn-for=GPUFence>
+    : <dfn>getCompletedValue()</dfn>
+    ::
+        Returns the largest signalled value completion value for the fence that has propagated to
+        the [=content timeline=].
+
+        <div algorithm="GPUFence.getCompletedValue">
+            **Called on:** {{GPUFence}} this.
+
+            **Returns:** {{GPUFenceValue}}
+
+            Issue: Describe {{GPUFence/getCompletedValue()}} algorithm steps.
+        </div>
+
+    : <dfn>onCompletion(completionValue)</dfn>
+    ::
+        Returns a {{Promise}} that resolves once the fence's completion value &ge; `completionValue`.
+        <div algorithm="GPUFence.onCompletion">
+            **Called on:** {{GPUFence}} this.
+
+            **Arguments:**
+            <pre class=argumentdef for="GPUFence/onCompletion(completionValue)">
+                completionValue: The completion value that the fence must meet or exceed before
+                    resolving the returned {{Promise}}
+            </pre>
+
+            **Returns:** {{Promise}}&lt;{{undefined}}&gt;
+
+            Issue: Describe {{GPUFence/onCompletion()}} algorithm steps.
+        </div>
+</dl>
+
+
 Queries {#queries}
 ================
 
@@ -6870,6 +6961,7 @@ partial interface GPUDevice {
 
 <script type=idl>
 typedef [EnforceRange] unsigned long GPUBufferDynamicOffset;
+typedef [EnforceRange] unsigned long long GPUFenceValue;
 typedef [EnforceRange] unsigned long GPUStencilValue;
 typedef [EnforceRange] unsigned long GPUSampleMask;
 typedef [EnforceRange] long GPUDepthBias;

From 43ecfb98535cfe2a23b2d5824b948bf93a114138 Mon Sep 17 00:00:00 2001
From: Dzmitry Malyshau <dmalyshau@mozilla.com>
Date: Fri, 13 Nov 2020 16:05:57 -0500
Subject: [PATCH 5/5] Rename wait to waitFor and clarify synchronization with
 more detail

---
 spec/index.bs | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/spec/index.bs b/spec/index.bs
index b484790e1b..336e09dd8d 100644
--- a/spec/index.bs
+++ b/spec/index.bs
@@ -6347,7 +6347,7 @@ interface GPUQueue {
     GPUSignalValue signal();
     readonly attribute GPUSignalValue lastSignaledValue;
 
-    undefined wait(GPUQueue queue, optional GPUSignalValue value);
+    undefined waitFor(GPUQueue queue, optional GPUSignalValue value);
 
     undefined submit(
         sequence<GPUCommandBuffer> commandBuffers,
@@ -6382,7 +6382,9 @@ GPUQueue includes GPUObjectBase;
 <dl dfn-type=attribute dfn-for=GPUQueue>
     : <dfn>lastSignaledValue</dfn> of type {{GPUSignalValue}}, readonly
     ::
-        The last value returned by {{GPUQueue/signal()}}.
+        Returns the integer value that is higher or equal to all the values
+        previously returned by either {{GPUQueue/lastSignaledValue}} or
+        {{GPUQueue/signal()}} on this queue.
 </dl>
 
 <dl dfn-type=method dfn-for=GPUQueue>
@@ -6562,11 +6564,14 @@ GPUQueue includes GPUObjectBase;
             </div>
         </div>
 
-    : <dfn>wait(queue, value)</dfn>
+    : <dfn>waitFor(queue, value)</dfn>
     ::
         Waits for the |queue| reaching |value| on the [=Queue timeline=]. If |value| is undefined,
         the |queue|.{{GPUQueue/lastSignaledValue}} is used instead.
 
+        The |value| has to be less or equal to the |queue|.{{GPUQueue/lastSignaledValue}},
+        or a validation error is produced.
+
         All the resource transitions from |queue| targeting |this| will be considered done on the [=Queue timeline=]
         after this call, and relevant resources can be used on |this|.