debug-flight-recorder.rst: Describe how to grab flight recorder

As I found myself writing these for a MR think it would better
to have to easily available to point people to.

Another small change is that since c706e1f8c8 we no longer
default subscribe to drm-backend for the flight recorder so update docs
as well. Combined with this new file should actually explain better how
to make use of it.

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>

doc/sphinx/toc/libweston.rst

@@ -10,6 +10,7 @@ Libweston
    libweston/shell-utils.rst
    libweston/output-management.rst
    libweston/log.rst
+   libweston/debug-flight-recorder.rst
 
 `Libweston` is an effort to separate the re-usable parts of Weston into a
 library. `Libweston` provides most of the boring and tedious bits of correctly

doc/sphinx/toc/libweston/debug-flight-recorder.rst

@@ -0,0 +1,51 @@
+.. _debugging flight recorder:
+
+
+Debugging with Flight Recorder
+==============================
+
+Weston can write debug scopes data to a circular ring buffer. This ring
+buffer can be accessed through a debug key, assuming you have a keyboard
+attached, or in case Weston dies, through a coredump. This document describes
+how to access that data in the later case.
+
+The ring buffer data can be accessed with a gdb python script that searches
+the coredump file for the that ring buffer address in order to retrieve
+data from it.
+
+Prior to setting this up make sure that flight recorder is configured
+accordingly.  Make sure that Weston is started with the debug scopes that
+you're interested into. For instance if you'd like to get the :samp:`drm-backend` one
+Weston should show when starting up:
+
+::
+
+        Flight recorder: enabled, scopes subscribed: drm-backend
+
+For that Weston needs to be started with :samp:`--debug -f drm-backend`.
+
+Also, make sure that the system is configured to generate a core dump.  Refer
+to :samp:`man core(5)` for how to do that.
+
+Next you'll need the `gdb python
+script <https://gitlab.freedesktop.org/wayland/weston/-/blob/main/doc/scripts/gdb/flight_rec.py>`_,
+as that will be needed to search for the ring buffer within the coredump.
+
+Finally, to make this easier and push everything from the ring buffer to a
+file, we would need to create a batch gdb file script to invoke the commands
+for us.
+
+As an example name that file :file:`test.gdb` and add the following to entries
+to it, making sure to adjust the path for the python script.
+
+::
+
+        source /path/to/flight_rec.py
+        display_flight_rec
+
+Then run the following commands to dump the contents of the ring buffer
+straight to a file:
+
+::
+
+        $ gdb --batch --command=/path/to/test.gdb -q /path/to/test/weston/binary --core /path/to/coredump &> dump.log.txt

doc/sphinx/toc/libweston/log.rst

@@ -141,8 +141,9 @@ force the contents to be printed on :samp:`stdout` file-descriptor.
 The user has first to specify which log scope to subscribe to.
 
 Specifying which scopes to subscribe for the flight-recorder can be done using
-:samp:`--flight-rec-scopes`. By default, the 'log' scope and 'drm-backend' are
+:samp:`-f|--flight-rec-scopes`. By default, only the 'log' scope is subscribed
-the scopes subscribed to.
+to. See :ref:`debugging flight recorder` on how retrieve the contents of the
+flight recorder in case Weston dies/crashes unexpectedly.
 
 weston-debug protocol
 ~~~~~~~~~~~~~~~~~~~~~

doc/sphinx/toc/libweston/meson.build

@@ -2,6 +2,7 @@
 files = [
 	'compositor.rst',
 	'head.rst',
+        'debug-flight-recorder.rst',
 	'log.rst',
 	'output.rst',
 	'output-management.rst',