[wayland-protocols] Add zwp_linux_explicit_synchronization_v1

Submitted by Daniel Stone on Sept. 19, 2017, 11:46 p.m.

Details

Message ID 20170919234603.25704-1-daniels@collabora.com
State Superseded
Headers show
Series "Add zwp_linux_explicit_synchronization_v1" ( rev: 1 ) in Wayland

Not browsing as part of any series.

Commit Message

Daniel Stone Sept. 19, 2017, 11:46 p.m.
Signed-off-by: Daniel Stone <daniels@collabora.com>
---
 Makefile.am                                        |   1 +
 unstable/linux-explicit-synchronization/README     |   5 +
 .../linux-explicit-synchronization-unstable-v1.xml | 208 +++++++++++++++++++++
 3 files changed, 214 insertions(+)
 create mode 100644 unstable/linux-explicit-synchronization/README
 create mode 100644 unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml

Patch hide | download patch | download mbox

diff --git a/Makefile.am b/Makefile.am
index 5b5ae96..941692c 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -15,6 +15,7 @@  unstable_protocols =								\
 	unstable/xwayland-keyboard-grab/xwayland-keyboard-grab-unstable-v1.xml	\
 	unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-unstable-v1.xml \
 	unstable/xdg-output/xdg-output-unstable-v1.xml				\
+	unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml \
 	$(NULL)
 
 stable_protocols =								\
diff --git a/unstable/linux-explicit-synchronization/README b/unstable/linux-explicit-synchronization/README
new file mode 100644
index 0000000..fac116f
--- /dev/null
+++ b/unstable/linux-explicit-synchronization/README
@@ -0,0 +1,5 @@ 
+Linux explicit synchronization (dma-fence) protocol
+
+Maintainers:
+David Reveman <reveman@chromium.org>
+Daniel Stone <daniels@collabora.com>
diff --git a/unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml b/unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml
new file mode 100644
index 0000000..4a6636e
--- /dev/null
+++ b/unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml
@@ -0,0 +1,208 @@ 
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="zwp_linux_explicit_synchronization_unstable_v1">
+
+  <copyright>
+    Copyright 2016 The Chromium Authors.
+    Copyright 2017 Intel Corporation
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="zwp_linux_explicit_synchronization_v1" version="1">
+    <description summary="protocol for providing explicit synchronization">
+      This global is a factory interface, allowing clients to request
+      explicit synchronization for buffers on a per-surface basis.
+
+      See zwp_surface_synchronization_v1 for more information.
+
+      This interface is derived from Chromium's
+      zcr_linux_explicit_synchronization_v1.
+
+      Warning! The protocol described in this file is experimental and
+      backward incompatible changes may be made. Backward compatible changes
+      may be added together with the corresponding interface version bump.
+      Backward incompatible changes are done by bumping the version number in
+      the protocol and interface names and resetting the interface version.
+      Once the protocol is to be declared stable, the 'z' prefix and the
+      version number in the protocol and interface names are removed and the
+      interface version number is reset.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy explicit synchronization factory object">
+	Destroy this explicit synchronization factory object. Other objects,
+	including zwp_surface_synchronization_v1 objects created by this
+	factory, shall not be affected by this request.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="synchronization_exists" value="0"
+	     summary="the surface already has a synchronization object associated"/>
+    </enum>
+
+    <request name="get_synchronization">
+      <description summary="extend surface interface for explicit synchronization">
+	Instantiate an interface extension for the given wl_surface to
+	provide explicit synchronization.
+	
+	If the given wl_surface already has an explicit synchronization object
+	associated, the synchronization_exists protocol error is raised.
+      </description>
+
+      <arg name="id" type="new_id" interface="zwp_surface_synchronization_v1"
+	   summary="the new synchronization interface id"/>
+      <arg name="surface" type="object" interface="wl_surface"
+	   summary="the surface"/>
+    </request>
+  </interface>
+
+  <interface name="zwp_surface_synchronization_v1" version="1">
+    <description summary="per-surface explicit synchronization support">
+      This object implements per-surface explicit synchronization.
+
+      Explicit synchronization refers to co-ordination of pipelined
+      operations performed on buffers. Most GPU clients will schedule
+      an asynchronous operation to render to the buffer, then immediately
+      send the buffer to the compositor to be attached to a surface.
+      Ensuring that the rendering operation is complete before the
+      compositor displays the buffer is an implementation detail handled
+      by either the kernel or userspace graphics driver. This is referred
+      to as 'implicit synchronization'.
+
+      By contrast, explicit synchronization takes dma_fence objects as a
+      marker of when the asynchronous operations are complete. The fence
+      provided by the client will be waited on before the compositor
+      accesses the buffer. Conversely, in place of wl_buffer.release
+      events, the Wayland server will inform the client when the buffer
+      can be destructively accessed through a zwp_buffer_release_v1
+      object.
+
+      This interface cannot be instantiated multiple times for a single
+      surface, and as such should only be used by the component which
+      performs the wl_surface.attach request. Whenever control of
+      buffer attachments is released, the releasing component should
+      ensure it destroys the zwp_surface_synchronization_v1 object.
+
+      It is illegal to destroy a zwp_surface_synchronization_v1 object
+      after its wl_surface has been destroyed.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy synchronization object">
+	Destroy this explicit synchronization object.
+
+	zwp_buffer_release_v1 objects created by this object are not affected
+	by this request.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="invalid_fence" value="0"
+	     summary="the fence specified by the client could not be imported"/>
+      <entry name="duplicate_fence" value="1"
+             summary="multiple fences added for a single surface commit"/>
+      <entry name="duplicate_release" value="2"
+             summary="multiple releases added for a single surface commit"/>
+    </enum>
+
+    <request name="set_acquire_fence">
+      <description summary="set the acquire fence">
+	Set the acquire fence that must be signaled before the compositor
+	may sample from the buffer attached with wl_buffer_attach. The fence
+	is a dma_fence kernel object.
+
+	The acquire fence is double-buffered state, and will be applied on
+	the next wl_surface.commit request for the associated surface.
+
+	If the fence could not be imported, an INVALID_FENCE error is signaled
+	to the client.
+
+	If a fence has already been attached during the same commit cycle,
+	a DUPLICATE_FENCE error is signaled to the client.
+      </description>
+      <arg name="fd" type="fd" summary="acquire fence fd"/>
+    </request>
+
+    <request name="get_release">
+      <description summary="release fence for last-attached buffer">
+        Create a listener for the release of the buffer attached by the
+	client with wl_buffer.attach. See zwp_buffer_release_v1
+	documentation for more information.
+
+	The release object is double-buffered state, and will be applied
+	on the next wl_surface.commit request for the associated surface.
+	
+	If a zwp_buffer_release_v1 object has already been requested for
+	the surface in the same commit cycle, a DUPLICATE_RELEASE error
+	is signaled to the client.
+      </description>
+
+      <arg name="release" type="new_id" interface="zwp_buffer_release_v1"
+           summary="new zwp_buffer_release_v1 object"/>
+    </request>
+  </interface>
+
+  <interface name="zwp_buffer_release_v1" version="1">
+    <description summary="buffer release explicit synchronization">
+      This object is instantiated in response to a
+      zwp_surface_synchronization_v1 request. 
+
+      It provides an alternative to wl_buffer.release events, providing
+      a unique release from a single wl_surface.commit request. The release
+      event also supports explicit synchronization, providing a fence FD
+      where relevant for the client to synchronize against before reusing
+      the buffer.
+
+      This event does not replace wl_buffer.release events; servers are still
+      required to send those events.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy buffer release synchronization object">
+	Destroy this buffer release explicit synchronization object. The object
+	may be destroyed at any time.
+      </description>
+    </request>
+
+    <event name="fenced_release">
+      <description summary="release buffer with fence">
+        Sent when the compositor has finalised its usage of the associated
+	buffer, providing a dma_fence which will be signaled when all
+	operations by the compositor on that buffer have finished.
+
+	Clients must not perform any destructive operations (e.g. clearing or
+	rendering) on the buffer until that fence has passed. They may,
+	however, destroy the wl_buffer object.
+      </description>
+      <arg name="fence" type="fd" summary="fence for last operation on buffer"/>
+    </event>
+
+    <event name="immediate_release">
+      <description summary="release buffer immediately">
+        Sent when the compositor has finalised its usage of the associated
+	buffer, and either performed no operations using it, or has a
+	guarantee that all its operations have finished and no more external
+	effects will be observed from these operations.
+      </description>
+    </event>
+  </interface>
+
+</protocol>

Comments

On Tue, Sep 19, 2017 at 6:46 PM, Daniel Stone <daniels@collabora.com> wrote:
> Signed-off-by: Daniel Stone <daniels@collabora.com>
> ---
>  Makefile.am                                        |   1 +
>  unstable/linux-explicit-synchronization/README     |   5 +
>  .../linux-explicit-synchronization-unstable-v1.xml | 208 +++++++++++++++++++++
>  3 files changed, 214 insertions(+)
>  create mode 100644 unstable/linux-explicit-synchronization/README
>  create mode 100644 unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml
>
> diff --git a/Makefile.am b/Makefile.am
> index 5b5ae96..941692c 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -15,6 +15,7 @@ unstable_protocols =                                                          \
>         unstable/xwayland-keyboard-grab/xwayland-keyboard-grab-unstable-v1.xml  \
>         unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-unstable-v1.xml \
>         unstable/xdg-output/xdg-output-unstable-v1.xml                          \
> +       unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml \
>         $(NULL)
>
>  stable_protocols =                                                             \
> diff --git a/unstable/linux-explicit-synchronization/README b/unstable/linux-explicit-synchronization/README
> new file mode 100644
> index 0000000..fac116f
> --- /dev/null
> +++ b/unstable/linux-explicit-synchronization/README
> @@ -0,0 +1,5 @@
> +Linux explicit synchronization (dma-fence) protocol
> +
> +Maintainers:
> +David Reveman <reveman@chromium.org>
> +Daniel Stone <daniels@collabora.com>
> diff --git a/unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml b/unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml
> new file mode 100644
> index 0000000..4a6636e
> --- /dev/null
> +++ b/unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml
> @@ -0,0 +1,208 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="zwp_linux_explicit_synchronization_unstable_v1">
> +
> +  <copyright>
> +    Copyright 2016 The Chromium Authors.
> +    Copyright 2017 Intel Corporation
> +
> +    Permission is hereby granted, free of charge, to any person obtaining a
> +    copy of this software and associated documentation files (the "Software"),
> +    to deal in the Software without restriction, including without limitation
> +    the rights to use, copy, modify, merge, publish, distribute, sublicense,
> +    and/or sell copies of the Software, and to permit persons to whom the
> +    Software is furnished to do so, subject to the following conditions:
> +
> +    The above copyright notice and this permission notice (including the next
> +    paragraph) shall be included in all copies or substantial portions of the
> +    Software.
> +
> +    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
> +    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
> +    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
> +    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
> +    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
> +    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
> +    DEALINGS IN THE SOFTWARE.
> +  </copyright>
> +
> +  <interface name="zwp_linux_explicit_synchronization_v1" version="1">
> +    <description summary="protocol for providing explicit synchronization">
> +      This global is a factory interface, allowing clients to request
> +      explicit synchronization for buffers on a per-surface basis.
> +
> +      See zwp_surface_synchronization_v1 for more information.
> +
> +      This interface is derived from Chromium's
> +      zcr_linux_explicit_synchronization_v1.
> +
> +      Warning! The protocol described in this file is experimental and
> +      backward incompatible changes may be made. Backward compatible changes
> +      may be added together with the corresponding interface version bump.
> +      Backward incompatible changes are done by bumping the version number in
> +      the protocol and interface names and resetting the interface version.
> +      Once the protocol is to be declared stable, the 'z' prefix and the
> +      version number in the protocol and interface names are removed and the
> +      interface version number is reset.
> +    </description>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy explicit synchronization factory object">
> +       Destroy this explicit synchronization factory object. Other objects,
> +       including zwp_surface_synchronization_v1 objects created by this
> +       factory, shall not be affected by this request.
> +      </description>
> +    </request>
> +
> +    <enum name="error">
> +      <entry name="synchronization_exists" value="0"
> +            summary="the surface already has a synchronization object associated"/>
> +    </enum>
> +
> +    <request name="get_synchronization">
> +      <description summary="extend surface interface for explicit synchronization">
> +       Instantiate an interface extension for the given wl_surface to
> +       provide explicit synchronization.
> +
> +       If the given wl_surface already has an explicit synchronization object
> +       associated, the synchronization_exists protocol error is raised.
> +      </description>
> +
> +      <arg name="id" type="new_id" interface="zwp_surface_synchronization_v1"
> +          summary="the new synchronization interface id"/>
> +      <arg name="surface" type="object" interface="wl_surface"
> +          summary="the surface"/>
> +    </request>
> +  </interface>
> +
> +  <interface name="zwp_surface_synchronization_v1" version="1">
> +    <description summary="per-surface explicit synchronization support">
> +      This object implements per-surface explicit synchronization.
> +
> +      Explicit synchronization refers to co-ordination of pipelined
> +      operations performed on buffers. Most GPU clients will schedule
> +      an asynchronous operation to render to the buffer, then immediately
> +      send the buffer to the compositor to be attached to a surface.
> +      Ensuring that the rendering operation is complete before the
> +      compositor displays the buffer is an implementation detail handled
> +      by either the kernel or userspace graphics driver. This is referred
> +      to as 'implicit synchronization'.
> +
> +      By contrast, explicit synchronization takes dma_fence objects as a
> +      marker of when the asynchronous operations are complete. The fence
> +      provided by the client will be waited on before the compositor
> +      accesses the buffer. Conversely, in place of wl_buffer.release
> +      events, the Wayland server will inform the client when the buffer
> +      can be destructively accessed through a zwp_buffer_release_v1
> +      object.
> +
> +      This interface cannot be instantiated multiple times for a single
> +      surface, and as such should only be used by the component which
> +      performs the wl_surface.attach request. Whenever control of
> +      buffer attachments is released, the releasing component should
> +      ensure it destroys the zwp_surface_synchronization_v1 object.
> +
> +      It is illegal to destroy a zwp_surface_synchronization_v1 object
> +      after its wl_surface has been destroyed.
> +    </description>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy synchronization object">
> +       Destroy this explicit synchronization object.
> +
> +       zwp_buffer_release_v1 objects created by this object are not affected
> +       by this request.
> +      </description>
> +    </request>
> +
> +    <enum name="error">
> +      <entry name="invalid_fence" value="0"
> +            summary="the fence specified by the client could not be imported"/>
> +      <entry name="duplicate_fence" value="1"
> +             summary="multiple fences added for a single surface commit"/>
> +      <entry name="duplicate_release" value="2"
> +             summary="multiple releases added for a single surface commit"/>
> +    </enum>
> +
> +    <request name="set_acquire_fence">
> +      <description summary="set the acquire fence">
> +       Set the acquire fence that must be signaled before the compositor
> +       may sample from the buffer attached with wl_buffer_attach. The fence
> +       is a dma_fence kernel object.
> +
> +       The acquire fence is double-buffered state, and will be applied on
> +       the next wl_surface.commit request for the associated surface.
> +
> +       If the fence could not be imported, an INVALID_FENCE error is signaled
> +       to the client.
> +
> +       If a fence has already been attached during the same commit cycle,
> +       a DUPLICATE_FENCE error is signaled to the client.
> +      </description>
> +      <arg name="fd" type="fd" summary="acquire fence fd"/>
> +    </request>
> +
> +    <request name="get_release">
> +      <description summary="release fence for last-attached buffer">
> +        Create a listener for the release of the buffer attached by the
> +       client with wl_buffer.attach. See zwp_buffer_release_v1
> +       documentation for more information.
> +
> +       The release object is double-buffered state, and will be applied
> +       on the next wl_surface.commit request for the associated surface.
> +
> +       If a zwp_buffer_release_v1 object has already been requested for
> +       the surface in the same commit cycle, a DUPLICATE_RELEASE error
> +       is signaled to the client.
> +      </description>
> +
> +      <arg name="release" type="new_id" interface="zwp_buffer_release_v1"
> +           summary="new zwp_buffer_release_v1 object"/>
> +    </request>
> +  </interface>
> +
> +  <interface name="zwp_buffer_release_v1" version="1">
> +    <description summary="buffer release explicit synchronization">
> +      This object is instantiated in response to a
> +      zwp_surface_synchronization_v1 request.
> +
> +      It provides an alternative to wl_buffer.release events, providing
> +      a unique release from a single wl_surface.commit request. The release
> +      event also supports explicit synchronization, providing a fence FD
> +      where relevant for the client to synchronize against before reusing
> +      the buffer.
> +
> +      This event does not replace wl_buffer.release events; servers are still
> +      required to send those events.
> +    </description>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy buffer release synchronization object">
> +       Destroy this buffer release explicit synchronization object. The object
> +       may be destroyed at any time.
> +      </description>
> +    </request>
> +
> +    <event name="fenced_release">
> +      <description summary="release buffer with fence">
> +        Sent when the compositor has finalised its usage of the associated
> +       buffer, providing a dma_fence which will be signaled when all
> +       operations by the compositor on that buffer have finished.
> +
> +       Clients must not perform any destructive operations (e.g. clearing or
> +       rendering) on the buffer until that fence has passed. They may,
> +       however, destroy the wl_buffer object.
> +      </description>
> +      <arg name="fence" type="fd" summary="fence for last operation on buffer"/>
> +    </event>
> +
> +    <event name="immediate_release">
> +      <description summary="release buffer immediately">
> +        Sent when the compositor has finalised its usage of the associated
> +       buffer, and either performed no operations using it, or has a
> +       guarantee that all its operations have finished and no more external
> +       effects will be observed from these operations.
> +      </description>
> +    </event>
> +  </interface>
> +
> +</protocol>
> --
> 2.14.1

On a related subject, there was discussion back at
https://lists.freedesktop.org/archives/wayland-devel/2013-September/011091.html
that acknowledged a longstanding bug where wl_buffer::release events
are starved indefinitely in the outbound server socket if there
doesn't happen to be any frame callback installed. That discussion
petered out, but it looked like there was a consensus that the issue
should be fixed (post the WL_BUFFER_RELEASE immediately rather than
queue if no frame callbacks attached).

That seems like a good issue to get closed up. Any objections to
reviving the patch along the lines that Pekka suggested?
Hi Daniel,

Will this protocol be used by libEGL, or applications has to use it directly ?

Best regards

Emre Ucan
Engineering Software Base (ADITG/ESB)

Tel. +49 5121 49 6937

> -----Original Message-----

> From: wayland-devel [mailto:wayland-devel-

> bounces@lists.freedesktop.org] On Behalf Of Daniel Stone

> Sent: Mittwoch, 20. September 2017 01:46

> To: wayland-devel@lists.freedesktop.org

> Subject: [PATCH wayland-protocols] Add

> zwp_linux_explicit_synchronization_v1

> 

> Signed-off-by: Daniel Stone <daniels@collabora.com>

> ---

>  Makefile.am                                        |   1 +

>  unstable/linux-explicit-synchronization/README     |   5 +

>  .../linux-explicit-synchronization-unstable-v1.xml | 208

> +++++++++++++++++++++

>  3 files changed, 214 insertions(+)

>  create mode 100644 unstable/linux-explicit-synchronization/README

>  create mode 100644 unstable/linux-explicit-synchronization/linux-explicit-

> synchronization-unstable-v1.xml

> 

> diff --git a/Makefile.am b/Makefile.am

> index 5b5ae96..941692c 100644

> --- a/Makefile.am

> +++ b/Makefile.am

> @@ -15,6 +15,7 @@ unstable_protocols =

> 				\

>  	unstable/xwayland-keyboard-grab/xwayland-keyboard-grab-

> unstable-v1.xml	\

>  	unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-

> unstable-v1.xml \

>  	unstable/xdg-output/xdg-output-unstable-v1.xml

> 		\

> +	unstable/linux-explicit-synchronization/linux-explicit-

> synchronization-unstable-v1.xml \

>  	$(NULL)

> 

>  stable_protocols =

> 	\

> diff --git a/unstable/linux-explicit-synchronization/README

> b/unstable/linux-explicit-synchronization/README

> new file mode 100644

> index 0000000..fac116f

> --- /dev/null

> +++ b/unstable/linux-explicit-synchronization/README

> @@ -0,0 +1,5 @@

> +Linux explicit synchronization (dma-fence) protocol

> +

> +Maintainers:

> +David Reveman <reveman@chromium.org>

> +Daniel Stone <daniels@collabora.com>

> diff --git a/unstable/linux-explicit-synchronization/linux-explicit-

> synchronization-unstable-v1.xml b/unstable/linux-explicit-

> synchronization/linux-explicit-synchronization-unstable-v1.xml

> new file mode 100644

> index 0000000..4a6636e

> --- /dev/null

> +++ b/unstable/linux-explicit-synchronization/linux-explicit-synchronization-

> unstable-v1.xml

> @@ -0,0 +1,208 @@

> +<?xml version="1.0" encoding="UTF-8"?>

> +<protocol name="zwp_linux_explicit_synchronization_unstable_v1">

> +

> +  <copyright>

> +    Copyright 2016 The Chromium Authors.

> +    Copyright 2017 Intel Corporation

> +

> +    Permission is hereby granted, free of charge, to any person obtaining a

> +    copy of this software and associated documentation files (the

> "Software"),

> +    to deal in the Software without restriction, including without limitation

> +    the rights to use, copy, modify, merge, publish, distribute, sublicense,

> +    and/or sell copies of the Software, and to permit persons to whom the

> +    Software is furnished to do so, subject to the following conditions:

> +

> +    The above copyright notice and this permission notice (including the next

> +    paragraph) shall be included in all copies or substantial portions of the

> +    Software.

> +

> +    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

> EXPRESS OR

> +    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

> MERCHANTABILITY,

> +    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO

> EVENT SHALL

> +    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,

> DAMAGES OR OTHER

> +    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,

> ARISING

> +    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR

> OTHER

> +    DEALINGS IN THE SOFTWARE.

> +  </copyright>

> +

> +  <interface name="zwp_linux_explicit_synchronization_v1" version="1">

> +    <description summary="protocol for providing explicit synchronization">

> +      This global is a factory interface, allowing clients to request

> +      explicit synchronization for buffers on a per-surface basis.

> +

> +      See zwp_surface_synchronization_v1 for more information.

> +

> +      This interface is derived from Chromium's

> +      zcr_linux_explicit_synchronization_v1.

> +

> +      Warning! The protocol described in this file is experimental and

> +      backward incompatible changes may be made. Backward compatible

> changes

> +      may be added together with the corresponding interface version bump.

> +      Backward incompatible changes are done by bumping the version

> number in

> +      the protocol and interface names and resetting the interface version.

> +      Once the protocol is to be declared stable, the 'z' prefix and the

> +      version number in the protocol and interface names are removed and

> the

> +      interface version number is reset.

> +    </description>

> +

> +    <request name="destroy" type="destructor">

> +      <description summary="destroy explicit synchronization factory object">

> +	Destroy this explicit synchronization factory object. Other objects,

> +	including zwp_surface_synchronization_v1 objects created by this

> +	factory, shall not be affected by this request.

> +      </description>

> +    </request>

> +

> +    <enum name="error">

> +      <entry name="synchronization_exists" value="0"

> +	     summary="the surface already has a synchronization object

> associated"/>

> +    </enum>

> +

> +    <request name="get_synchronization">

> +      <description summary="extend surface interface for explicit

> synchronization">

> +	Instantiate an interface extension for the given wl_surface to

> +	provide explicit synchronization.

> +

> +	If the given wl_surface already has an explicit synchronization object

> +	associated, the synchronization_exists protocol error is raised.

> +      </description>

> +

> +      <arg name="id" type="new_id"

> interface="zwp_surface_synchronization_v1"

> +	   summary="the new synchronization interface id"/>

> +      <arg name="surface" type="object" interface="wl_surface"

> +	   summary="the surface"/>

> +    </request>

> +  </interface>

> +

> +  <interface name="zwp_surface_synchronization_v1" version="1">

> +    <description summary="per-surface explicit synchronization support">

> +      This object implements per-surface explicit synchronization.

> +

> +      Explicit synchronization refers to co-ordination of pipelined

> +      operations performed on buffers. Most GPU clients will schedule

> +      an asynchronous operation to render to the buffer, then immediately

> +      send the buffer to the compositor to be attached to a surface.

> +      Ensuring that the rendering operation is complete before the

> +      compositor displays the buffer is an implementation detail handled

> +      by either the kernel or userspace graphics driver. This is referred

> +      to as 'implicit synchronization'.

> +

> +      By contrast, explicit synchronization takes dma_fence objects as a

> +      marker of when the asynchronous operations are complete. The fence

> +      provided by the client will be waited on before the compositor

> +      accesses the buffer. Conversely, in place of wl_buffer.release

> +      events, the Wayland server will inform the client when the buffer

> +      can be destructively accessed through a zwp_buffer_release_v1

> +      object.

> +

> +      This interface cannot be instantiated multiple times for a single

> +      surface, and as such should only be used by the component which

> +      performs the wl_surface.attach request. Whenever control of

> +      buffer attachments is released, the releasing component should

> +      ensure it destroys the zwp_surface_synchronization_v1 object.

> +

> +      It is illegal to destroy a zwp_surface_synchronization_v1 object

> +      after its wl_surface has been destroyed.

> +    </description>

> +

> +    <request name="destroy" type="destructor">

> +      <description summary="destroy synchronization object">

> +	Destroy this explicit synchronization object.

> +

> +	zwp_buffer_release_v1 objects created by this object are not

> affected

> +	by this request.

> +      </description>

> +    </request>

> +

> +    <enum name="error">

> +      <entry name="invalid_fence" value="0"

> +	     summary="the fence specified by the client could not be

> imported"/>

> +      <entry name="duplicate_fence" value="1"

> +             summary="multiple fences added for a single surface commit"/>

> +      <entry name="duplicate_release" value="2"

> +             summary="multiple releases added for a single surface commit"/>

> +    </enum>

> +

> +    <request name="set_acquire_fence">

> +      <description summary="set the acquire fence">

> +	Set the acquire fence that must be signaled before the compositor

> +	may sample from the buffer attached with wl_buffer_attach. The

> fence

> +	is a dma_fence kernel object.

> +

> +	The acquire fence is double-buffered state, and will be applied on

> +	the next wl_surface.commit request for the associated surface.

> +

> +	If the fence could not be imported, an INVALID_FENCE error is

> signaled

> +	to the client.

> +

> +	If a fence has already been attached during the same commit cycle,

> +	a DUPLICATE_FENCE error is signaled to the client.

> +      </description>

> +      <arg name="fd" type="fd" summary="acquire fence fd"/>

> +    </request>

> +

> +    <request name="get_release">

> +      <description summary="release fence for last-attached buffer">

> +        Create a listener for the release of the buffer attached by the

> +	client with wl_buffer.attach. See zwp_buffer_release_v1

> +	documentation for more information.

> +

> +	The release object is double-buffered state, and will be applied

> +	on the next wl_surface.commit request for the associated surface.

> +

> +	If a zwp_buffer_release_v1 object has already been requested for

> +	the surface in the same commit cycle, a DUPLICATE_RELEASE error

> +	is signaled to the client.

> +      </description>

> +

> +      <arg name="release" type="new_id"

> interface="zwp_buffer_release_v1"

> +           summary="new zwp_buffer_release_v1 object"/>

> +    </request>

> +  </interface>

> +

> +  <interface name="zwp_buffer_release_v1" version="1">

> +    <description summary="buffer release explicit synchronization">

> +      This object is instantiated in response to a

> +      zwp_surface_synchronization_v1 request.

> +

> +      It provides an alternative to wl_buffer.release events, providing

> +      a unique release from a single wl_surface.commit request. The release

> +      event also supports explicit synchronization, providing a fence FD

> +      where relevant for the client to synchronize against before reusing

> +      the buffer.

> +

> +      This event does not replace wl_buffer.release events; servers are still

> +      required to send those events.

> +    </description>

> +

> +    <request name="destroy" type="destructor">

> +      <description summary="destroy buffer release synchronization object">

> +	Destroy this buffer release explicit synchronization object. The object

> +	may be destroyed at any time.

> +      </description>

> +    </request>

> +

> +    <event name="fenced_release">

> +      <description summary="release buffer with fence">

> +        Sent when the compositor has finalised its usage of the associated

> +	buffer, providing a dma_fence which will be signaled when all

> +	operations by the compositor on that buffer have finished.

> +

> +	Clients must not perform any destructive operations (e.g. clearing or

> +	rendering) on the buffer until that fence has passed. They may,

> +	however, destroy the wl_buffer object.

> +      </description>

> +      <arg name="fence" type="fd" summary="fence for last operation on

> buffer"/>

> +    </event>

> +

> +    <event name="immediate_release">

> +      <description summary="release buffer immediately">

> +        Sent when the compositor has finalised its usage of the associated

> +	buffer, and either performed no operations using it, or has a

> +	guarantee that all its operations have finished and no more external

> +	effects will be observed from these operations.

> +      </description>

> +    </event>

> +  </interface>

> +

> +</protocol>

> --

> 2.14.1

> 

> _______________________________________________

> wayland-devel mailing list

> wayland-devel@lists.freedesktop.org

> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Hi Matt,

On 20 September 2017 at 05:48, Matt Hoosier <matt.hoosier@gmail.com> wrote:
> On a related subject, there was discussion back at
> https://lists.freedesktop.org/archives/wayland-devel/2013-September/011091.html
> that acknowledged a longstanding bug where wl_buffer::release events
> are starved indefinitely in the outbound server socket if there
> doesn't happen to be any frame callback installed. That discussion
> petered out, but it looked like there was a consensus that the issue
> should be fixed (post the WL_BUFFER_RELEASE immediately rather than
> queue if no frame callbacks attached).
>
> That seems like a good issue to get closed up. Any objections to
> reviving the patch along the lines that Pekka suggested?

Since then, we've moved the frame events around, such that they're no
longer sent immediately, which might change the calculus a bit. Pekka?

Cheers,
Daniel
Hi Emre,

On 20 September 2017 at 06:38, Ucan, Emre (ADITG/ESB)
<eucan@de.adit-jv.com> wrote:
> Will this protocol be used by libEGL, or applications has to use it directly ?

The idea was for whoever calls wl_surface_attach() to also attach the
fence: an EGL/Vulkan driver, or a client framework directly if using
buffers from V4L2 or similar. An implementation for Mesa's Vulkan
drivers is here:
https://lists.freedesktop.org/archives/mesa-dev/2017-September/170199.html

Cheers,
Daniel
On Wed, 20 Sep 2017 07:11:57 -0700
Daniel Stone <daniel@fooishbar.org> wrote:

> Hi Matt,
> 
> On 20 September 2017 at 05:48, Matt Hoosier <matt.hoosier@gmail.com> wrote:
> > On a related subject, there was discussion back at
> > https://lists.freedesktop.org/archives/wayland-devel/2013-September/011091.html
> > that acknowledged a longstanding bug where wl_buffer::release events
> > are starved indefinitely in the outbound server socket if there
> > doesn't happen to be any frame callback installed. That discussion
> > petered out, but it looked like there was a consensus that the issue
> > should be fixed (post the WL_BUFFER_RELEASE immediately rather than
> > queue if no frame callbacks attached).
> >
> > That seems like a good issue to get closed up. Any objections to
> > reviving the patch along the lines that Pekka suggested?  
> 
> Since then, we've moved the frame events around, such that they're no
> longer sent immediately, which might change the calculus a bit. Pekka?

Hi,

since 2013, we have got rid of the separate wl_event_loop used to
throttle the input events as well, IIRC.

I have to say today I would be completely fine with just posting the
release events always and never delaying them. The queueing has been
such a pain for EGL implementations.

I'm not sure we would even have the necessary information in the
compositor about whether a client wants release event ASAP or is it
happy with throttling. I suppose we could track whether the
wl_surface.commit that makes a wl_buffer reserved in the compositor
also had a wl_surface.frame request and only in that case queue the
release, otherwise post. I haven't thought it through.

Frame callbacks are sent as the last thing in weston_output_repaint(),
that has not changed. What did change is that there is now a delay
between the pageflip event and the call to weston_output_repaint(). Now
we also have the repaint grouping across outputs but I don't think that
makes much of a difference. So I would say the situation has not
changed wrt. to when the frame callbacks are sent out.

Well, if we need a pageflip event to release a buffer, then yes, the
frame callback will be coming later than in 2013. But that implies the
client buffer was on scanout.

I don't really like the idea that a client needs to "flush out" the
release events somehow. That is like leaking compositor implementation
details into clients. And that's exactly what asking for frame or sync
callbacks is when you have no other use for them.

I also don't quite like the idea of magically inferring whether a
client is speed-runner game or a leisurely office app. We might even
need explicit protocol for that, and then could use it for both buffer
releases and input event throttling and coalescing.

All in all, in the spirit of avoiding premature optimization, I'd go
for the simple solution and let profiling drive more complicated
solutions when the need arises. We're talking about buffer releases.
Buffer releases happen when clients animate. Surely animation is heavy
enough to obliterate any power savings we might get from optimizing
when to flush out release events?


Thanks,
pq
On Fri, Sep 22, 2017 at 10:24 AM, Pekka Paalanen <ppaalanen@gmail.com> wrote:
> On Wed, 20 Sep 2017 07:11:57 -0700
> Daniel Stone <daniel@fooishbar.org> wrote:
>
>> Hi Matt,
>>
>> On 20 September 2017 at 05:48, Matt Hoosier <matt.hoosier@gmail.com> wrote:
>> > On a related subject, there was discussion back at
>> > https://lists.freedesktop.org/archives/wayland-devel/2013-September/011091.html
>> > that acknowledged a longstanding bug where wl_buffer::release events
>> > are starved indefinitely in the outbound server socket if there
>> > doesn't happen to be any frame callback installed. That discussion
>> > petered out, but it looked like there was a consensus that the issue
>> > should be fixed (post the WL_BUFFER_RELEASE immediately rather than
>> > queue if no frame callbacks attached).
>> >
>> > That seems like a good issue to get closed up. Any objections to
>> > reviving the patch along the lines that Pekka suggested?
>>
>> Since then, we've moved the frame events around, such that they're no
>> longer sent immediately, which might change the calculus a bit. Pekka?
>
> Hi,
>
> since 2013, we have got rid of the separate wl_event_loop used to
> throttle the input events as well, IIRC.
>
> I have to say today I would be completely fine with just posting the
> release events always and never delaying them. The queueing has been
> such a pain for EGL implementations.
>
> I'm not sure we would even have the necessary information in the
> compositor about whether a client wants release event ASAP or is it
> happy with throttling. I suppose we could track whether the
> wl_surface.commit that makes a wl_buffer reserved in the compositor
> also had a wl_surface.frame request and only in that case queue the
> release, otherwise post. I haven't thought it through.
>
> Frame callbacks are sent as the last thing in weston_output_repaint(),
> that has not changed. What did change is that there is now a delay
> between the pageflip event and the call to weston_output_repaint(). Now
> we also have the repaint grouping across outputs but I don't think that
> makes much of a difference. So I would say the situation has not
> changed wrt. to when the frame callbacks are sent out.
>
> Well, if we need a pageflip event to release a buffer, then yes, the
> frame callback will be coming later than in 2013. But that implies the
> client buffer was on scanout.
>
> I don't really like the idea that a client needs to "flush out" the
> release events somehow. That is like leaking compositor implementation
> details into clients. And that's exactly what asking for frame or sync
> callbacks is when you have no other use for them.
>
> I also don't quite like the idea of magically inferring whether a
> client is speed-runner game or a leisurely office app. We might even
> need explicit protocol for that, and then could use it for both buffer
> releases and input event throttling and coalescing.
>
> All in all, in the spirit of avoiding premature optimization, I'd go
> for the simple solution and let profiling drive more complicated
> solutions when the need arises. We're talking about buffer releases.
> Buffer releases happen when clients animate. Surely animation is heavy
> enough to obliterate any power savings we might get from optimizing
> when to flush out release events?

I completely agree. I'll submit something to wayland-devel on Monday.
On Fri, Sep 22, 2017 at 6:18 PM, Matt Hoosier <matt.hoosier@gmail.com> wrote:
> On Fri, Sep 22, 2017 at 10:24 AM, Pekka Paalanen <ppaalanen@gmail.com> wrote:
>> On Wed, 20 Sep 2017 07:11:57 -0700
>> Daniel Stone <daniel@fooishbar.org> wrote:
>>
>>> Hi Matt,
>>>
>>> On 20 September 2017 at 05:48, Matt Hoosier <matt.hoosier@gmail.com> wrote:
>>> > On a related subject, there was discussion back at
>>> > https://lists.freedesktop.org/archives/wayland-devel/2013-September/011091.html
>>> > that acknowledged a longstanding bug where wl_buffer::release events
>>> > are starved indefinitely in the outbound server socket if there
>>> > doesn't happen to be any frame callback installed. That discussion
>>> > petered out, but it looked like there was a consensus that the issue
>>> > should be fixed (post the WL_BUFFER_RELEASE immediately rather than
>>> > queue if no frame callbacks attached).
>>> >
>>> > That seems like a good issue to get closed up. Any objections to
>>> > reviving the patch along the lines that Pekka suggested?
>>>
>>> Since then, we've moved the frame events around, such that they're no
>>> longer sent immediately, which might change the calculus a bit. Pekka?
>>
>> Hi,
>>
>> since 2013, we have got rid of the separate wl_event_loop used to
>> throttle the input events as well, IIRC.
>>
>> I have to say today I would be completely fine with just posting the
>> release events always and never delaying them. The queueing has been
>> such a pain for EGL implementations.
>>
>> I'm not sure we would even have the necessary information in the
>> compositor about whether a client wants release event ASAP or is it
>> happy with throttling. I suppose we could track whether the
>> wl_surface.commit that makes a wl_buffer reserved in the compositor
>> also had a wl_surface.frame request and only in that case queue the
>> release, otherwise post. I haven't thought it through.
>>
>> Frame callbacks are sent as the last thing in weston_output_repaint(),
>> that has not changed. What did change is that there is now a delay
>> between the pageflip event and the call to weston_output_repaint(). Now
>> we also have the repaint grouping across outputs but I don't think that
>> makes much of a difference. So I would say the situation has not
>> changed wrt. to when the frame callbacks are sent out.
>>
>> Well, if we need a pageflip event to release a buffer, then yes, the
>> frame callback will be coming later than in 2013. But that implies the
>> client buffer was on scanout.
>>
>> I don't really like the idea that a client needs to "flush out" the
>> release events somehow. That is like leaking compositor implementation
>> details into clients. And that's exactly what asking for frame or sync
>> callbacks is when you have no other use for them.
>>
>> I also don't quite like the idea of magically inferring whether a
>> client is speed-runner game or a leisurely office app. We might even
>> need explicit protocol for that, and then could use it for both buffer
>> releases and input event throttling and coalescing.
>>
>> All in all, in the spirit of avoiding premature optimization, I'd go
>> for the simple solution and let profiling drive more complicated
>> solutions when the need arises. We're talking about buffer releases.
>> Buffer releases happen when clients animate. Surely animation is heavy
>> enough to obliterate any power savings we might get from optimizing
>> when to flush out release events?
>
> I completely agree. I'll submit something to wayland-devel on Monday.

Done, see https://lists.freedesktop.org/archives/wayland-devel/2017-September/035175.html.