[PATCH v2 2/2] dev-manual/debugging: Add a "Backtraces or target" section

[Mathieu Othacehe <othacehe@gnu.org>]

That section is presenting how to rely upon the minidebuginfo, and possibly
the PACKAGE_KEEP_SECTIONS variable to get backtraces on target.
---
 documentation/dev-manual/debugging.rst | 54 ++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index 92458a0c3..914412a75 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -1199,6 +1199,60 @@ coredumps (commands ``coredumpctl list`` and ``coredumpctl info``).
 This feature was created by Fedora, see https://fedoraproject.org/wiki/Features/MiniDebugInfo for
 more details.
 
+Backtraces on target
+====================
+
+Some high level languages such as Python have an integrated backtrace system
+allowing to get the call-stack up to the failure on target. For C and C++
+programs though, there is no such thing and getting backtraces on the target
+involves some effort. To get human readable backtraces, you need three
+different components:
+
+- The symbols: it can only be function names, if you consider the mechanism
+  described in the ":ref:`dev-manual/debugging:enabling minidebuginfo`"
+  section. If storage is not an issue, you can also use the complete symbol
+  tables by disabling stripping in your ``local.conf`` file::
+
+   INHIBIT_PACKAGE_STRIP = "1"
+
+- The unwind tables: those are architecture dependent. On *x86* and *aarch64*
+  architectures, the ``.eh_frame`` and ``.eh_frame_hdr`` ELF sections that are
+  used for exception handling can also be used for stack unwinding. Those
+  sections are not stripped by default. On other architectures such as
+  *armv7*, the ``.ARM.exidx`` and ``.ARM.extab`` ELF sections that are used
+  for exception handling can also be used for stack unwinding. However, one
+  might prefer to rely upon the ``.debug_frame`` section.  That section
+  contains DWARF unwinding material, similar to what's in the ``.eh_frame``
+  section. To do that, an option is to instruct the ``strip`` command to
+  always keep the ``.debug_frame`` section around, by setting
+  :term:`PACKAGE_KEEP_SECTIONS` in the ``local.conf`` file::
+
+    PACKAGE_KEEP_SECTIONS = ".debug_frame"
+
+- An unwind program such as ``GDB`` or library such as ``libunwind``. That one
+  will use the unwind tables to get the call-stack at the moment of the
+  crash. Then it will perform the translation between the function addresses
+  and the symbols to get a human readable backtrace.
+
+With those three components in your image, you can for example configure
+``libunwind`` to display a backtrace when receiving a ``Segmentation fault``
+signal and get a backtrace similar to that one::
+
+    Backtrace:
+      0x400da9: segmentation_fault_handler(int) + 0xb
+      0xb6d64a6e: strlen + 0xad
+      0xb6d38dcf: __printf_buffer + 0x112d
+      0xb6d4be7f: __vsnprintf + 0x31
+      0x400c79: print_info(char const*, ...) + 0x5f
+      0x400ddb: main + 0x13
+      0xb6d182cb: __libc_start_call_main + 0x45
+      0xb6d18367: __libc_start_main + 0x5d
+    Segmentation fault
+
+If you are using an unwinding section that was already present on target and
+the ``minidebuginfo`` mechanism, the overhead only consists in the compressed
+function symbols and the addition of the unwinding program or library.
+
 Other Debugging Tips
 ====================
 
-- 
2.47.1