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 mechanisms 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 subscribes 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.

destroy
Type: destructor
destroy()
Destroy factory object

Destroys the factory object, but does not affect any other objects.

subscribe(name: string, streamfd: fd, stream: new_id<weston_debug_stream_v1>)
Argument
Type
Description
namestringallow null
debug stream name
streamfdfd
write stream file descriptor
streamnew_id<weston_debug_stream_v1>
created debug stream object
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.

available(name: string, description: string)
Argument
Type
Description
namestringallow null
debug stream name
descriptionstringallow null
human-readable description of the debug scope
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.


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.

destroy()
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.

complete()
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.

failure(message: string)
Argument
Type
Description
messagestringallow null
human readable reason
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.


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.