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 <[email protected]> Signed-off-by: Maniraj Devadoss <[email protected]> --- 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..acfb7a1 --- /dev/null +++ b/unstable/compositor-debug/README @@ -0,0 +1,7 @@ +Compositor Debug protocol + +Maintainers: +Pekka Paalanen <[email protected]> +Friedrich Eugen <[email protected]> +Ucan Emre <[email protected]> +Maniraj Devadoss <[email protected]> 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..78cbaa6 --- /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 [email protected] + + 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> -- 2.7.4
_______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
