[PATCH wayland-protocols v3] protocol: add compositor-debug.xml

Pekka Paalanen ppaalanen at gmail.com
Tue Oct 3 08:45:41 UTC 2017


On Fri, 22 Sep 2017 11:17:49 +0200
Maniraj Devadoss <external.mdevadoss at de.adit-jv.com> wrote:

> From: Pekka Paalanen <pq at iki.fi>
> 
> This is a new debugging extension for non-production environments. The
> aim is to replace all build-time choosable debug prints in the
> compositor with runtime subscribable debug streams.
> 
> Signed-off-by: Pekka Paalanen <pq at iki.fi>
> Signed-off-by: Maniraj Devadoss <external.mdevadoss at de.adit-jv.com>
> ---
>  Makefile.am                                        |   1 +
>  unstable/compositor-debug/README                   |   7 ++
>  .../compositor-debug-unstable-v1.xml               | 128 +++++++++++++++++++++
>  3 files changed, 136 insertions(+)
>  create mode 100644 unstable/compositor-debug/README
>  create mode 100644 unstable/compositor-debug/compositor-debug-unstable-v1.xml
> 
> diff --git a/Makefile.am b/Makefile.am
> index 5b5ae96..a0994d1 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/compositor-debug/compositor-debug-unstable-v1.xml		\
>  	$(NULL)
>  
>  stable_protocols =								\
> diff --git a/unstable/compositor-debug/README b/unstable/compositor-debug/README
> new file mode 100644
> index 0000000..f1a7603
> --- /dev/null
> +++ b/unstable/compositor-debug/README
> @@ -0,0 +1,7 @@
> +Compositor Debug protocol
> +
> +Maintainers:
> +Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> +Friedrich Eugen <efriedrich at de.adit-jv.com>
> +Ucan Emre <eucan at de.adit-jv.com>
> +Maniraj Devadoss <maniraj.devadoss at in.bosch.com>
> diff --git a/unstable/compositor-debug/compositor-debug-unstable-v1.xml b/unstable/compositor-debug/compositor-debug-unstable-v1.xml
> new file mode 100644
> index 0000000..b81c630
> --- /dev/null
> +++ b/unstable/compositor-debug/compositor-debug-unstable-v1.xml
> @@ -0,0 +1,128 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="compositor_debug_unstable_v1">
> +
> +  <copyright>
> +    Copyright © 2017 Pekka Paalanen pq at iki.fi

Hi Maniraj,

it wasn't necessary to "obfuscate" the email addresses, we don't tend
to do that. Anyway, this patch is fine by me.

Jonas, would you like to give an Acked-by and maybe cut a
wayland-protocols release so we have a version number for Weston to
depend on? Or if you have anything you'd like changed?


Thanks,
pq

> +
> +    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="zcompositor_debug_v1" version="1">
> +    <description summary="compositor internal debugging">
> +      This is a generic debugging interface for the compositor internals,the global
> +      object advertized through wl_registry.
> +
> +      WARNING: This interface by design allows a denial-of-service attack. It
> +      should not be offered in production, or proper authorization mechnisms
> +      must be enforced.
> +
> +      The idea is for a client to provide a file descriptor that the server
> +      uses for printing debug information. The server uses the file
> +      descriptor in blocking writes mode, which exposes the denial-of-service
> +      risk. The blocking mode is necessary to ensure all debug messages can
> +      be easily printed in place. It also ensures message ordering if a
> +      client subcribes to more than one debug stream.
> +
> +      The available debugging features depend on the server. There is no
> +      explicit API for discovering the supported debug stream names. A server
> +      should implement a debug stream named "list" where the server prints
> +      the names and descriptions of all debug streams it supports to the
> +      stream file descriptor.
> +
> +      A debug stream can be one-shot where the server prints the requested
> +      information and then closes it, or continuous where server keeps on
> +      printing until the client stops it. Or anything in between.
> +    </description>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy factory object">
> +	Destroys the factory object, but does not affect any other objects.
> +      </description>
> +    </request>
> +
> +    <request name="subscribe">
> +      <description summary="subscribe to a debug stream">
> +	Subscribe to a named debug stream. The server will start printing
> +	to the given file descriptor.
> +
> +	If the named debug stream is a one-shot dump, the server will send
> +	zcompositor_debug_v1.complete event once all requested data has
> +	been printed. Otherwise, the server will continue streaming debug
> +	prints until the subscription object is destroyed.
> +
> +	If the debug stream name is unknown to the server, the server will
> +	immediately respond with zcompositor_debug_v1.failure event.
> +      </description>
> +
> +      <arg name="name" type="string" allow-null="false"
> +           summary="debug stream name"/>
> +      <arg name="streamfd" type="fd" summary="write stream file descriptor"/>
> +      <arg name="stream" type="new_id" interface="zcompositor_debug_stream_v1"
> +           summary="created debug stream object"/>
> +    </request>
> +  </interface>
> +
> +  <interface name="zcompositor_debug_stream_v1" version="1">
> +    <description summary="A subscribed debug stream">
> +      Represents one subscribed debug stream, created with
> +      zcompositor_debug_v1.subscribe. When the object is created, it is associated
> +      with a given file descriptor. The server will continue writing to the
> +      file descriptor until the object is destroyed or the server sends an
> +      event through the object.
> +    </description>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="close a debug stream">
> +	Destroys the object, which causes the server to stop writing into
> +	and closes the associated file descriptor if it was not closed
> +	already.
> +
> +	Use a wl_display.sync if the clients needs to guarantee the file
> +	descriptor is closed before continuing.
> +      </description>
> +    </request>
> +
> +    <event name="complete">
> +      <description summary="server completed the debug stream">
> +	The server has successfully finished writing to and has closed the
> +	associated file descriptor.
> +
> +	This event is delivered only for one-shot debug streams where the
> +	server dumps some data and stop. This is never delivered for
> +	continuous debbug streams because they by definition never complete.
> +      </description>
> +    </event>
> +
> +    <event name="failure">
> +      <description summary="server cannot continue the debug stream">
> +	The server has stopped writing to and has closed the
> +	associated file descriptor. The data already written to the file
> +	descriptor is correct, but it may be truncated.
> +
> +	This event may be delivered at any time and for any kind of debug
> +	stream. It may be due to a failure in or shutdown of the server.
> +	The message argument may provide a hint of the reason.
> +      </description>
> +
> +      <arg name="message" type="string" allow-null="true"
> +           summary="human readable reason"/>
> +    </event>
> +  </interface>
> +</protocol>

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20171003/0c22da3d/attachment-0001.sig>


More information about the wayland-devel mailing list