1Logging/Debugging 2================= 3 4Weston's printf 5--------------- 6 7Logging in weston takes place through :func:`weston_log()` function, which 8calls a log handler (:var:`log_handler`) that has to be installed before 9actually calling :func:`weston_log()`. In weston, the log handler makes use of 10the logging framework which is (mostly) comprised of :ref:`log scopes` (produces 11of data) and :ref:`subscribers`. 12 13Logging context 14--------------- 15 16Management of the logging framework in weston happens under the 17:type:`weston_log_context` object and is entirely separated from the main 18compositor instance (:type:`weston_compositor`). The compositor 19instance can be brought up much more later, but in the same time logging can 20take place much earlier without the need of a compositor instance. 21 22Instantiation of the :type:`weston_log_context` object takes place using 23:func:`weston_log_ctx_create()` and clean-up/destroy with 24:func:`weston_log_ctx_destroy()` or :func:`weston_log_ctx_compositor_destroy()`. 25 26Log scopes 27---------- 28 29A scope represents a source for a data stream (i.e., a producer). You'll 30require one as a way to generate data. Creating a log scope is done using 31:func:`weston_log_ctx_add_log_scope()` or 32:func:`weston_compositor_add_log_scope()`. You can customize the scope 33behaviour and you'll require at least a name and a description for the scope. 34 35.. note:: 36 37 A scope **name** identifies that scope. Scope retrieval from the 38 :type:`weston_log_context` is done using the scope name. The name is 39 important for the subscription part, detailed bit later. 40 41Log scopes are managed **explicitly**, and destroying the scope is done using 42:func:`weston_log_scope_destroy`. 43 44Available scopes in weston 45~~~~~~~~~~~~~~~~~~~~~~~~~~ 46 47Weston has a few scopes worth mentioning: 48 49- **log** - a debug scope for generic logging, upon which :func:`weston_log` 50 re-routes its data. 51- **proto** - debug scope that displays the protocol communication. It is 52 similar to WAYLAND_DEBUG=server environmental variable but has the ability to 53 distinguish multiple clients. 54- **scene-graph** - an one-shot debug scope which describes the current scene 55 graph comprising of layers (containers of views), views (which represent a 56 window), their surfaces, sub-surfaces, buffer type and format, both in 57 :samp:`DRM_FOURCC` type and human-friendly form. 58- **drm-backend** - Weston uses DRM (Direct Rendering Manager) as one of its 59 backends and this debug scope display information related to that: details 60 the transitions of a view as it takes before being assigned to a hardware 61 plane or to a renderer, current assignments of views, the compositing mode 62 Weston is using for rendering the scene-graph, describes the current hardware 63 plane properties like CRTC_ID, FB_ID, FORMAT when doing a commit or a 64 page-flip. It incorporates the scene-graph scope as well. 65- **xwm-wm-x11** - a scope for the X11 window manager in Weston for supporting 66 Xwayland, printing some X11 protocol actions. 67- **content-protection-debug** - scope for debugging HDCP issues. 68- **timeline** - see more at :ref:`timeline points` 69 70.. note:: 71 72 Besides 'log' scope, which is a generic scope, intended for usage through 73 :func:`weston_log`, all the others scopes listed above could suffer various 74 modifications and might not represent a current list on which one should 75 rely upon. 76 77 78Subscribers 79----------- 80 81Besides creating a creating a scope, a subscriber (:type:`weston_log_subscriber`) 82object needs to be created. The subscriber object is an opaque 83object (private) and allows customization of the back-end side of libweston. 84The subscriber object can define its own methods. Users wanting to define 85a new data stream should extend this :type:`weston_log_subscriber`. 86 87For example libweston make uses of several type of subscribers, specific to the 88data streams they will be generating: 89 90- a **'logger'** type created by :func:`weston_log_subscriber_create_log()` 91- a **'flight-recoder'** type created by :func:`weston_log_subscriber_destroy_flight_rec()` 92- for the **'weston-debug'** protocol, which is private/hidden created whenever a 93 client connects 94 95Like log scopes, the subscribers are also manged **explicitly** and both of the 96subscriber types above have their destroy counter-parts. `weston-debug` 97protocol is a bit special in this regard as the destroying part is handled 98implicitly using wayland protocol specifics. 99 100Once the subscriber has been created there needs to be a subscription process 101in which we establish a relationship between the subscriber and the scope. 102 103To create a subscription we use :func:`weston_log_subscribe` which uses the 104subscriber created previously and the scope name. If the scope was not created 105at the time, the subscription will be (at least for a time) a *pending 106subscription*. Once the scope is created the *pending subscription* is 107destroyed, not before creating a new subscription to accommodate the 108initial/original one. 109 110.. note:: 111 112 The subscription process is (an) internal API and is managed implictly. 113 114When a scope is being destroyed the subscriptions for this scope will be 115destroyed as well. 116 117Logger 118~~~~~~ 119 120weston uses a logger type of a subscriber for logging everyhing in the code 121(through the help of :func:`weston_log()`). The subscriber method 122(:func:`weston_log_subscriber_create_log()`) takes an :samp:`FILE *` as an 123argument in case the std :samp:`stdout` file-descriptor is not where the data 124should be sent to. 125 126Additionally, specifying which scopes to subscribe to can be done using 127:samp:`--logger-scopes` command line option. As log scopes are already created 128in the code, this merely subscribes to them. Default, the 'log' scope is being 129subscribr to the logger subscriber. 130 131Flight recorder 132~~~~~~~~~~~~~~~ 133 134The flight recorder acts like a black box found in airplanes: it accumulates 135data until the user wants to display its contents. The backed up storage is a 136simple ring-buffer of a compiled-time fixed size value, and the memory is 137forcibly-mapped such that we make sure the kernel allocated storage for it. 138 139The user can use the debug keybinding :samp:`KEY_D` (shift+mod+space-d) to 140force the contents to be printed on :samp:`stdout` file-descriptor. 141The user has first to specify which log scope to subscribe to. 142 143Specifying which scopes to subscribe for the flight-recorder can be done using 144:samp:`--flight-rec-scopes`. By default, the 'log' scope and 'drm-backend' are 145the scopes subscribed to. 146 147weston-debug protocol 148~~~~~~~~~~~~~~~~~~~~~ 149 150Weston-debug protocol is only present in the weston compositor (i.e., a weston 151specific compositor). It make uses of the the logging framework presented 152above, with the exception that the subscription happens automatically rather 153than manually with :func:`weston_log_subscribe()` in case of the other two 154types of subscribers. Also the subscriber is created once the client has 155connected and requested data from a log scope. This means that each time a 156client connects a new subscriber will be created. For each stream subscribed a 157subscription will be created. Enabling the debug-protocol happens using the 158:samp:`--debug` command line. 159 160Timeline points 161--------------- 162 163A special log scope is the 'timeline' scope which, together with 164`wesgr <https://github.com/ppaalanen/wesgr>`_ tool, helps diagnose latency issues. 165Timeline points write to this 'timeline' scope in different parts of the 166compositor, including the GL renderer. 167 168As with all other scopes this scope is available over the debug protocol, or by 169using the others :ref:`subscribers`. By far the easiest way to get data out 170of this scope would be to use the debug protocol. 171Then use `wesgr <https://github.com/ppaalanen/wesgr>`_ to process the data which 172will transform it into a SVG that can be rendered by any web browser. 173 174The following illustrates how to use it: 175 176.. code-block:: console 177 178 ./weston-debug timeline > log.json 179 ./wesgr -i log.json -o log.svg 180 181Inserting timeline points 182~~~~~~~~~~~~~~~~~~~~~~~~~ 183 184Timline points can be inserted using :c:macro:`TL_POINT` macro. The macro will 185take the :type:`weston_compositor` instance, followed by the name of the 186timeline point. What follows next is a variable number of arguments, which 187**must** end with the macro :c:macro:`TLP_END`. 188 189Debug protocol API 190------------------ 191 192.. doxygengroup:: debug-protocol 193 :content-only: 194 195Weston Log API 196-------------- 197 198.. doxygengroup:: wlog 199 :content-only: 200 201Logging API 202----------- 203 204.. doxygengroup:: log 205 :content-only: 206 207Internal logging API 208-------------------- 209 210.. note:: 211 212 The following is mean to be internal API and aren't exposed in libweston! 213 214.. doxygengroup:: internal-log 215 :content-only: 216
