[PATCH v2 0/2] debugging: Document how to get backtraces on target

[PATCH v2 0/2] debugging: Document how to get backtraces on target

[Mathieu Othacehe]

Hello,

That series is introducing a PACKAGE_KEEP_SECTIONS variable that can be used
to keep some specific ELF sections when stripping packages.

It is then building upon that to present how to get human-readable backtraces
on target, possibly also relying on the minidebuginfo mechanism.

Thanks,

Mathieu

v1: https://lists.yoctoproject.org/g/docs/message/6243
core commit: https://lists.openembedded.org/g/openembedded-core/message/210762

Mathieu Othacehe (2):
  profile-manual: Document the PACKAGE_KEEP_SECTIONS variable.
  dev-manual/debugging: Add a "Backtraces or target" section

 documentation/dev-manual/debugging.rst | 54 ++++++++++++++++++++++++++
 documentation/profile-manual/intro.rst |  6 +++
 documentation/ref-manual/variables.rst | 12 ++++++
 3 files changed, 72 insertions(+)

-- 
2.47.1

[PATCH v2 1/2] profile-manual: Document the PACKAGE_KEEP_SECTIONS variable.

[Mathieu Othacehe]

Document the 'PACKAGE_KEEP_SECTIONS' variable that can be used to keep some
specific ELF sections while stripping binaries and libraries.

That one can then be used to keep the .debug_frame section around for
example, this way:

PACKAGE_KEEP_SECTIONS = ".debug_frame"

By using libunwind + minidebuginfo, that provides a way for users to get
debug_frame based backtraces on target.

Signed-off-by: Mathieu Othacehe <othacehe@gnu.org>
---
 documentation/profile-manual/intro.rst |  6 ++++++
 documentation/ref-manual/variables.rst | 12 ++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/documentation/profile-manual/intro.rst b/documentation/profile-manual/intro.rst
index 317912552..a7243c1ca 100644
--- a/documentation/profile-manual/intro.rst
+++ b/documentation/profile-manual/intro.rst
@@ -75,3 +75,9 @@ Additionally, in order to generate the right type of debug info, we also need to
 set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file::
 
    PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'
+
+When you are building a stripped image, you can also keep some specific ELF
+sections in the image by setting :term:`PACKAGE_KEEP_SECTIONS` in the
+``local.conf`` file::
+
+   PACKAGE_KEEP_SECTIONS = ".debug_frame"
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 47d4e814f..6743b1a9f 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6243,6 +6243,18 @@ system and gives an overview of their function and contents.
       install, the build system does not generate an error. This variable
       is generally not user-defined.
 
+   :term:`PACKAGE_KEEP_SECTIONS`
+      Specifies a list of ELF sections that should be kept when stripping
+      during package creation. You can set this variable in your
+      ``local.conf`` file.
+
+      For example, the following::
+
+        PACKAGE_KEEP_SECTIONS = ".debug_frame"
+
+      will result in passing the ``--keep-section=.debug_frame`` argument to
+      the ``strip`` command.
+
    :term:`PACKAGE_PREPROCESS_FUNCS`
       Specifies a list of functions run to pre-process the
       :term:`PKGD` directory prior to splitting the files out
-- 
2.47.1

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

[Mathieu Othacehe]

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