protocol: add weston-debug.xml

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@iki.fi>

Added new libweston-$MAJOR-protocols.pc file and install that
for external projects to find the XML files installed by libweston.

Signed-off-by: Maniraj Devadoss <Maniraj.Devadoss@in.bosch.com>

Use noarch_pkgconfig_DATA instead, add ${pc_sysrootdir}, drop
unnecessary EXTRA_DIST of weston-debug.xml.

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>

Add explicit advertisement of available debug interfaces.

Signed-off-by: Daniel Stone <daniels@collabora.com>
Reviewed-by: Emre Ucan <eucan@de.adit-jv.com>

1 files changed, 139 insertions, 0 deletions

diff --git a/protocol/weston-debug.xml b/protocol/weston-debug.xml
new file mode 100644
index 00000000..effa1a19
--- /dev/null
+++ b/protocol/weston-debug.xml
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="weston_debug">
+
+  <copyright>
+    Copyright © 2017 Pekka Paalanen pq@iki.fi
+    Copyright © 2018 Zodiac Inflight Innovations
+
+    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="weston_debug_v1" version="1">
+    <description summary="weston internal debugging">
+      This is a generic debugging interface for Weston 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.
+
+      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>
+
+    <event name="available">
+      <description summary="advertise available debug scope">
+        Advertises an available debug scope which the client may be able to
+        bind to. No information is provided by the server about the content
+        contained within the debug streams provided by the scope, once a
+        client has subscribed.
+      </description>
+
+      <arg name="name" type="string" allow-null="false"
+           summary="debug stream name"/>
+      <arg name="description" type="string" allow-null="true"
+           summary="human-readable description of the debug scope"/>
+    </event>
+
+    <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
+	weston_debug_stream_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 weston_debug_stream_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="weston_debug_stream_v1"
+           summary="created debug stream object"/>
+    </request>
+  </interface>
+
+  <interface name="weston_debug_stream_v1" version="1">
+    <description summary="A subscribed debug stream">
+      Represents one subscribed debug stream, created with
+      weston_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>