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>
dev
Pekka Paalanen
7 years ago
committed by
Daniel Stone
parent
3ebbc6b5df
commit
4fc1ee8d5b
@ -0,0 +1,7 @@ |
|||||||
|
prefix=@prefix@ |
||||||
|
datarootdir=@datarootdir@ |
||||||
|
pkgdatadir=${pc_sysrootdir}@datadir@/@PACKAGE@/protocols |
||||||
|
|
||||||
|
Name: libWeston Protocols |
||||||
|
Description: libWeston protocol files |
||||||
|
Version: @WESTON_VERSION@ |
||||||
@ -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> |
||||||
Loading…
Reference in new issue