1<?xml version="1.0" encoding="UTF-8"?> 2<protocol name="weston_debug"> 3 4 <copyright> 5 Copyright © 2017 Pekka Paalanen pq@iki.fi 6 Copyright © 2018 Zodiac Inflight Innovations 7 8 Permission is hereby granted, free of charge, to any person obtaining a 9 copy of this software and associated documentation files (the "Software"), 10 to deal in the Software without restriction, including without limitation 11 the rights to use, copy, modify, merge, publish, distribute, sublicense, 12 and/or sell copies of the Software, and to permit persons to whom the 13 Software is furnished to do so, subject to the following conditions: 14 15 The above copyright notice and this permission notice (including the next 16 paragraph) shall be included in all copies or substantial portions of the 17 Software. 18 19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 21 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 22 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 23 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 24 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25 DEALINGS IN THE SOFTWARE. 26 </copyright> 27 28 <interface name="weston_debug_v1" version="1"> 29 <description summary="weston internal debugging"> 30 This is a generic debugging interface for Weston internals, the global 31 object advertized through wl_registry. 32 33 WARNING: This interface by design allows a denial-of-service attack. It 34 should not be offered in production, or proper authorization mechanisms 35 must be enforced. 36 37 The idea is for a client to provide a file descriptor that the server 38 uses for printing debug information. The server uses the file 39 descriptor in blocking writes mode, which exposes the denial-of-service 40 risk. The blocking mode is necessary to ensure all debug messages can 41 be easily printed in place. It also ensures message ordering if a 42 client subscribes to more than one debug stream. 43 44 The available debugging features depend on the server. 45 46 A debug stream can be one-shot where the server prints the requested 47 information and then closes it, or continuous where server keeps on 48 printing until the client stops it. Or anything in between. 49 </description> 50 51 <request name="destroy" type="destructor"> 52 <description summary="destroy factory object"> 53 Destroys the factory object, but does not affect any other objects. 54 </description> 55 </request> 56 57 <event name="available"> 58 <description summary="advertise available debug scope"> 59 Advertises an available debug scope which the client may be able to 60 bind to. No information is provided by the server about the content 61 contained within the debug streams provided by the scope, once a 62 client has subscribed. 63 </description> 64 65 <arg name="name" type="string" allow-null="false" 66 summary="debug stream name"/> 67 <arg name="description" type="string" allow-null="true" 68 summary="human-readable description of the debug scope"/> 69 </event> 70 71 <request name="subscribe"> 72 <description summary="subscribe to a debug stream"> 73 Subscribe to a named debug stream. The server will start printing 74 to the given file descriptor. 75 76 If the named debug stream is a one-shot dump, the server will send 77 weston_debug_stream_v1.complete event once all requested data has 78 been printed. Otherwise, the server will continue streaming debug 79 prints until the subscription object is destroyed. 80 81 If the debug stream name is unknown to the server, the server will 82 immediately respond with weston_debug_stream_v1.failure event. 83 </description> 84 85 <arg name="name" type="string" allow-null="false" 86 summary="debug stream name"/> 87 <arg name="streamfd" type="fd" summary="write stream file descriptor"/> 88 <arg name="stream" type="new_id" interface="weston_debug_stream_v1" 89 summary="created debug stream object"/> 90 </request> 91 </interface> 92 93 <interface name="weston_debug_stream_v1" version="1"> 94 <description summary="A subscribed debug stream"> 95 Represents one subscribed debug stream, created with 96 weston_debug_v1.subscribe. When the object is created, it is associated 97 with a given file descriptor. The server will continue writing to the 98 file descriptor until the object is destroyed or the server sends an 99 event through the object. 100 </description> 101 102 <request name="destroy" type="destructor"> 103 <description summary="close a debug stream"> 104 Destroys the object, which causes the server to stop writing into 105 and closes the associated file descriptor if it was not closed 106 already. 107 108 Use a wl_display.sync if the clients needs to guarantee the file 109 descriptor is closed before continuing. 110 </description> 111 </request> 112 113 <event name="complete"> 114 <description summary="server completed the debug stream"> 115 The server has successfully finished writing to and has closed the 116 associated file descriptor. 117 118 This event is delivered only for one-shot debug streams where the 119 server dumps some data and stop. This is never delivered for 120 continuous debbug streams because they by definition never complete. 121 </description> 122 </event> 123 124 <event name="failure"> 125 <description summary="server cannot continue the debug stream"> 126 The server has stopped writing to and has closed the 127 associated file descriptor. The data already written to the file 128 descriptor is correct, but it may be truncated. 129 130 This event may be delivered at any time and for any kind of debug 131 stream. It may be due to a failure in or shutdown of the server. 132 The message argument may provide a hint of the reason. 133 </description> 134 135 <arg name="message" type="string" allow-null="true" 136 summary="human readable reason"/> 137 </event> 138 </interface> 139</protocol> 140