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