Internal debug scopes / Logging framework
Version 4 of this series, notable changes from previous version:
- lifetime of the
weston_log_scopeis maintained as is (explicit), it has to be manually destroyed.
- introduction of the
- lifetime of the
weston_log_subscriberis also explicit, it has to be manually destroyed.
- both the scope and the subscriber maintain a list of subscriptions. Subscription will be created each time "we" subscribe to a scope, and the subscription is added to both list of subscriptions.
weston-log, have a internal
weston-log-internalto handle minimal API for the subscription but it is a clear separation
- destroying compositor instance needs the log scope to be present (and available) in order to display the last debugging messages. Modified the destroy part of the compositor as to avoid free'ing the compositor instance.
- documentation for the logging framework in rST format
- debug keybinding
KEY_Fthat dumps the contents of the flight recorder on demand
Version 3 of this series, with changes from previous version:
- properly subclass this time. Introduction of
weston_log_opsobject, which contains the callbacks where each scope type can define its methods.
- introduction of
weston_log_subscriberobject which acts like a container and holds current
weston_log_opsand a destroy callback. When the subscriber is destroyed, we destroy the scopes subscribed to + call the
destroycallback for the subscriber.
weston_log_opsis unique to each subscriber and each scope type has functions to retrieve the
weston_log_scopefrom their hidden implementation:
weston_log_flight_rec_to_subscriber_ops()which actually point the bass class.
- subscriber API and the ability to subscribe to multiple scopes. Introduction of
wl_arraytype to hold the
weston_log_opsentries. Register/Deregister which can be called dynamically to add/remove entries --
weston_log_waylandis one of the user that will add/remove subscribers dynamically. For others, the
destroycallbacks are empty, only the subscriber
destroycallback being set. For this to happen
weston_log_scopegains an additional member called
- each of the subscriber is in its own file, with
- kept the older way writing to scope, and export the methods to retrieve the scope using the
weston_log_context. Added one more helper to retrieve the
weston_log_subscriber. This seems natural in my opinion otherwise, if we were to use the subscriber instead of the scope we would have duplicate messages.
weston_log_subscriberare internal and kept into
libweston/weston-log-internal.h. Everything else, exported to
include/libweston/weston-debug.h. Also, the creating/destroying/setup of the logging context transfer into
- for weston-debug protocol added dummy subscriber method to keep consistency with the others + renamed
--debugcommand line to something more suitable:
- scope subscription takes place by using
--flight-rec-scopescommand line options.
Additionally with the merge of !164 (merged) logging context, removed the logging context (
weston_log_ctx_compositor_destroy()) from the compositor destroy part (
weston_compositor_destroy()) and call it directly in
main(). This was necessary as destroying the compositor would still yield logging message and we were using an invalid reference for the logging context (as compositor is free'ed). Believe this also makes a stronger idea that the logging context is independent of the compositor.
Older version(s) follows:
Take 2 at this series, what I've done differently (based mostly on @pq comments :)):
- approached it differently, this time by sub-classing
weston_debug_streamand using a helper
weston_debug_subscriberto encapsulate the different type of
- separated the file and the flight-recorder streams into their own files
- added a weston-debug-internal file for
weston_debug_subscriber: reason is to also keep a clear separation between weston-debug and the 'hint scopes,
weston_debug_scope_hint(which are used at initialization) and
weston_debug_internal_storagewhich acts as a container added in
weston_debug_compositorto hold the
FILE *(where to dump data)
Further more, the following are done before added weston-debug-file and weston-debug-flight-recorder:
- as we need to initialize the debug framework much earlier we decouple
- we pass
weston_compositorand we connect front and back-pointer references
- need to subscribe manually to debug streams, and we need to do it after the scope has been created so we pass
flight-rec-scopesas hint scopes to
weston_debug_compositoras to determine on which subscriber scopes we need to subscribe to.
Noticeable/worth-mentioning difference(s) from prev:
flight-recorderis the only user for
weston_ring_bufferso I've included directly into weston-debug-flight-rec file.
- weston-debug-stream has its own file just like weston-debug-file and weston-debug-flight-rec making more clear the seperation between the front-end part which calls into
weston_debug_scope_write()and back-end part which calls the
writecallbacks from each debug stream type.~~
The series creates two additional lists to keep track of internal debug scopes (one that dumps data to a FILE * an one that
stores the data into a circular buffer which can be displayed at a later point in time). We then add support into weston-debug for both of those, and add
drm-backend internal debug scopes (both saving debug messages into the circular buffer and writing to an internal file).
This allows starting weston with
--log-scopes=log,drm-backend command line option, and will start printing those two log scopes when starting up. If
--debug is added on the command line
log will be added to the circular buffer. The contents of the circular buffer will be dumped/displayed if the (atomic/legacdy) commit in the DRM backend failed. Further users of this circular buffer can be later added, if there's a need.
Weston will still dump to
stderr if starting without
--log-scopes specified on the command line, so we keep the same functionality.
Nice to have
- tests for checking circular buffer is working properly / verifying that data is dumped