[weston,v5,02/14] protocol: add weston-debug.xml

Submitted by Daniel Stone on July 20, 2018, 7:03 p.m.

Details

Message ID 20180720190335.23880-3-daniels@collabora.com
State Superseded
Headers show
Series "weston-debug API and tool" ( rev: 2 1 ) in Wayland

Not browsing as part of any series.

Commit Message

Daniel Stone July 20, 2018, 7:03 p.m.
From: Pekka Paalanen <pq@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@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>
---
 Makefile.am                         |  10 ++
 configure.ac                        |   1 +
 libweston/libweston-protocols.pc.in |   7 ++
 protocol/weston-debug.xml           | 136 ++++++++++++++++++++++++++++
 4 files changed, 154 insertions(+)
 create mode 100644 libweston/libweston-protocols.pc.in
 create mode 100644 protocol/weston-debug.xml

Patch hide | download patch | download mbox

diff --git a/Makefile.am b/Makefile.am
index 3bce47a11..66eb365c5 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -106,6 +106,10 @@  libweston_@LIBWESTON_MAJOR@_la_SOURCES =			\
 	shared/platform.h				\
 	shared/weston-egl-ext.h
 
+libweston_@LIBWESTON_MAJOR@_datadir = $(datadir)/weston/protocols
+dist_libweston_@LIBWESTON_MAJOR@_data_DATA =	\
+	protocol/weston-debug.xml
+
 lib_LTLIBRARIES += libweston-desktop-@LIBWESTON_MAJOR@.la
 libweston_desktop_@LIBWESTON_MAJOR@_la_CPPFLAGS = $(AM_CPPFLAGS) -DIN_WESTON
 libweston_desktop_@LIBWESTON_MAJOR@_la_CFLAGS = $(AM_CFLAGS) $(COMPOSITOR_CFLAGS)
@@ -152,6 +156,8 @@  endif
 nodist_libweston_@LIBWESTON_MAJOR@_la_SOURCES =				\
 	protocol/weston-screenshooter-protocol.c			\
 	protocol/weston-screenshooter-server-protocol.h			\
+	protocol/weston-debug-protocol.c				\
+	protocol/weston-debug-server-protocol.h				\
 	protocol/text-cursor-position-protocol.c	\
 	protocol/text-cursor-position-server-protocol.h	\
 	protocol/text-input-unstable-v1-protocol.c			\
@@ -276,6 +282,10 @@  pkgconfig_DATA = \
 	libweston-desktop/libweston-desktop-${LIBWESTON_MAJOR}.pc \
 	compositor/weston.pc
 
+noarch_pkgconfigdir = $(datadir)/pkgconfig
+noarch_pkgconfig_DATA = \
+	libweston/libweston-${LIBWESTON_MAJOR}-protocols.pc
+
 wayland_sessiondir = $(datadir)/wayland-sessions
 dist_wayland_session_DATA = compositor/weston.desktop
 
diff --git a/configure.ac b/configure.ac
index 093d6b549..3a138ea91 100644
--- a/configure.ac
+++ b/configure.ac
@@ -695,6 +695,7 @@  AC_CONFIG_FILES([Makefile libweston/version.h compositor/weston.pc])
 # libweston_abi_version here, and outside [] because of m4 quoting rules
 AC_CONFIG_FILES([libweston/libweston-]libweston_major_version[.pc:libweston/libweston.pc.in])
 AC_CONFIG_FILES([libweston/libweston-]libweston_major_version[-uninstalled.pc:libweston/libweston-uninstalled.pc.in])
+AC_CONFIG_FILES([libweston/libweston-]libweston_major_version[-protocols.pc:libweston/libweston-protocols.pc.in])
 AC_CONFIG_FILES([libweston-desktop/libweston-desktop-]libweston_major_version[.pc:libweston-desktop/libweston-desktop.pc.in])
 AC_CONFIG_FILES([libweston-desktop/libweston-desktop-]libweston_major_version[-uninstalled.pc:libweston-desktop/libweston-desktop-uninstalled.pc.in])
 
diff --git a/libweston/libweston-protocols.pc.in b/libweston/libweston-protocols.pc.in
new file mode 100644
index 000000000..6547a0d5a
--- /dev/null
+++ b/libweston/libweston-protocols.pc.in
@@ -0,0 +1,7 @@ 
+prefix=@prefix@
+datarootdir=@datarootdir@
+pkgdatadir=${pc_sysrootdir}@datadir@/@PACKAGE@/protocols
+
+Name: libWeston Protocols
+Description: libWeston protocol files
+Version: @WESTON_VERSION@
diff --git a/protocol/weston-debug.xml b/protocol/weston-debug.xml
new file mode 100644
index 000000000..1154c3ae2
--- /dev/null
+++ b/protocol/weston-debug.xml
@@ -0,0 +1,136 @@ 
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="weston_debug">
+
+  <copyright>
+    Copyright © 2017 Pekka Paalanen pq@iki.fi
+
+    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"/>
+    </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>

Comments

Reviewed-by: Emre Ucan <eucan@de.adit-jv.com>


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: Freitag, 20. Juli 2018 21:06

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

> Cc: pekka.paalanen@collabora.co.uk; emre.ucan@de.adit-jv.com;

> Maniraj.Devadoss@in.bosch.com

> Subject: [PATCH weston v5 02/14] protocol: add weston-debug.xml

> 

> From: Pekka Paalanen <pq@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@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>

> ---

>  Makefile.am                         |  10 ++

>  configure.ac                        |   1 +

>  libweston/libweston-protocols.pc.in |   7 ++

>  protocol/weston-debug.xml           | 136 ++++++++++++++++++++++++++++

>  4 files changed, 154 insertions(+)

>  create mode 100644 libweston/libweston-protocols.pc.in

>  create mode 100644 protocol/weston-debug.xml

> 

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

> index 3bce47a11..66eb365c5 100644

> --- a/Makefile.am

> +++ b/Makefile.am

> @@ -106,6 +106,10 @@ libweston_@LIBWESTON_MAJOR@_la_SOURCES =

> 			\

>  	shared/platform.h				\

>  	shared/weston-egl-ext.h

> 

> +libweston_@LIBWESTON_MAJOR@_datadir = $(datadir)/weston/protocols

> +dist_libweston_@LIBWESTON_MAJOR@_data_DATA =	\

> +	protocol/weston-debug.xml

> +

>  lib_LTLIBRARIES += libweston-desktop-@LIBWESTON_MAJOR@.la

>  libweston_desktop_@LIBWESTON_MAJOR@_la_CPPFLAGS =

> $(AM_CPPFLAGS) -DIN_WESTON

>  libweston_desktop_@LIBWESTON_MAJOR@_la_CFLAGS = $(AM_CFLAGS)

> $(COMPOSITOR_CFLAGS)

> @@ -152,6 +156,8 @@ endif

>  nodist_libweston_@LIBWESTON_MAJOR@_la_SOURCES =

> 		\

>  	protocol/weston-screenshooter-protocol.c			\

>  	protocol/weston-screenshooter-server-protocol.h

> 	\

> +	protocol/weston-debug-protocol.c				\

> +	protocol/weston-debug-server-protocol.h

> 	\

>  	protocol/text-cursor-position-protocol.c	\

>  	protocol/text-cursor-position-server-protocol.h	\

>  	protocol/text-input-unstable-v1-protocol.c			\

> @@ -276,6 +282,10 @@ pkgconfig_DATA = \

>  	libweston-desktop/libweston-desktop-${LIBWESTON_MAJOR}.pc \

>  	compositor/weston.pc

> 

> +noarch_pkgconfigdir = $(datadir)/pkgconfig

> +noarch_pkgconfig_DATA = \

> +	libweston/libweston-${LIBWESTON_MAJOR}-protocols.pc

> +

>  wayland_sessiondir = $(datadir)/wayland-sessions

>  dist_wayland_session_DATA = compositor/weston.desktop

> 

> diff --git a/configure.ac b/configure.ac

> index 093d6b549..3a138ea91 100644

> --- a/configure.ac

> +++ b/configure.ac

> @@ -695,6 +695,7 @@ AC_CONFIG_FILES([Makefile libweston/version.h

> compositor/weston.pc])

>  # libweston_abi_version here, and outside [] because of m4 quoting rules

>  AC_CONFIG_FILES([libweston/libweston-

> ]libweston_major_version[.pc:libweston/libweston.pc.in])

>  AC_CONFIG_FILES([libweston/libweston-]libweston_major_version[-

> uninstalled.pc:libweston/libweston-uninstalled.pc.in])

> +AC_CONFIG_FILES([libweston/libweston-]libweston_major_version[-

> protocols.pc:libweston/libweston-protocols.pc.in])

>  AC_CONFIG_FILES([libweston-desktop/libweston-desktop-

> ]libweston_major_version[.pc:libweston-desktop/libweston-desktop.pc.in])

>  AC_CONFIG_FILES([libweston-desktop/libweston-desktop-

> ]libweston_major_version[-uninstalled.pc:libweston-desktop/libweston-

> desktop-uninstalled.pc.in])

> 

> diff --git a/libweston/libweston-protocols.pc.in b/libweston/libweston-

> protocols.pc.in

> new file mode 100644

> index 000000000..6547a0d5a

> --- /dev/null

> +++ b/libweston/libweston-protocols.pc.in

> @@ -0,0 +1,7 @@

> +prefix=@prefix@

> +datarootdir=@datarootdir@

> +pkgdatadir=${pc_sysrootdir}@datadir@/@PACKAGE@/protocols

> +

> +Name: libWeston Protocols

> +Description: libWeston protocol files

> +Version: @WESTON_VERSION@

> diff --git a/protocol/weston-debug.xml b/protocol/weston-debug.xml

> new file mode 100644

> index 000000000..1154c3ae2

> --- /dev/null

> +++ b/protocol/weston-debug.xml

> @@ -0,0 +1,136 @@

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

> +<protocol name="weston_debug">

> +

> +  <copyright>

> +    Copyright © 2017 Pekka Paalanen pq@iki.fi

> +

> +    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"/>

> +    </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>

> --

> 2.17.1

> 

> _______________________________________________

> wayland-devel mailing list

> wayland-devel@lists.freedesktop.org

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