[PATCH v3 0/2] Document the PACKAGE_KEEP_DEBUG_FRAME variable

[PATCH v3 0/2] Document the PACKAGE_KEEP_DEBUG_FRAME variable

[Mathieu Othacehe]

Hello,

That series is introducing a PACKAGE_KEEP_DEBUG_FRAME variable that can be
used to keep the .debug_frame ELF section 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

v2: https://lists.yoctoproject.org/g/docs/message/6252
poky: https://git.yoctoproject.org/poky/commit/?h=master-next&id=10448200b63bdc45b39504ebcddd85b5f274f0c4

Changelog:
v2: Fix a build issue
v3: Document the PACKAGE_KEEP_DEBUG_FRAME
variable rather that the PACKAGE_KEEP_SECTIONS variable because the former
approach was preferred and merged into poky.

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

 documentation/dev-manual/debugging.rst | 55 ++++++++++++++++++++++++++
 documentation/ref-manual/variables.rst |  9 +++++
 2 files changed, 64 insertions(+)

-- 
2.47.1

[PATCH v3 1/2] profile-manual: Document the PACKAGE_KEEP_DEBUG_FRAME variable.

[Mathieu Othacehe]

Document the 'PACKAGE_KEEP_DEBUG_FRAME' variable that can be used to keep the
.debug_frame ELF section when stripping.

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/ref-manual/variables.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 47d4e814f..f5bd7b353 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6243,6 +6243,15 @@ 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_DEBUG_FRAME`
+      Keep the ``.debug_frame`` ELF section when stripping during package
+      creation. You can set this variable in your ``local.conf`` file::
+
+        PACKAGE_KEEP_DEBUG_FRAME = "1"
+
+      That 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 v3 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_DEBUG_FRAME variable to get backtraces on target.
---
 documentation/dev-manual/debugging.rst | 55 ++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index 92458a0c3..6fc0bc2d4 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -1199,6 +1199,61 @@ 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. As ``.debug_frame`` is stripped by default, an option is to
+  instruct the ``strip`` command to always keep the ``.debug_frame`` section
+  around, by setting :term:`PACKAGE_KEEP_DEBUG_FRAME` in the ``local.conf``
+  file::
+
+    PACKAGE_KEEP_DEBUG_FRAME = "1"
+
+- 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. You would then get backtraces 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

Re: [PATCH v3 0/2] Document the PACKAGE_KEEP_DEBUG_FRAME variable

[Antonin Godard]

Hi Mathieu,

On Tue Feb 11, 2025 at 5:12 PM CET, Mathieu Othacehe wrote:
> Hello,
>
> That series is introducing a PACKAGE_KEEP_DEBUG_FRAME variable that can be
> used to keep the .debug_frame ELF section 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
>
> v2: https://lists.yoctoproject.org/g/docs/message/6252
> poky: https://git.yoctoproject.org/poky/commit/?h=master-next&id=10448200b63bdc45b39504ebcddd85b5f274f0c4

This link does not work for me. Could you give me a new link with your
commits, on master? I couldn't find them.

Thank you,
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [PATCH v3 0/2] Document the PACKAGE_KEEP_DEBUG_FRAME variable

[Mathieu Othacehe]

Hello Antonin,

>> poky: https://git.yoctoproject.org/poky/commit/?h=master-next&id=10448200b63bdc45b39504ebcddd85b5f274f0c4
>
> This link does not work for me. Could you give me a new link with your
> commits, on master? I couldn't find them.

Not sure why that one broke, here's a new one:

https://git.yoctoproject.org/poky/commit/?h=master-next&id=df2c9e884066aafb0dfb60521a4809c5ba4cfd5d

Thanks,

Mathieu

Re: [docs] [PATCH v3 0/2] Document the PACKAGE_KEEP_DEBUG_FRAME variable

[Richard Purdie]

On Mon, 2025-02-17 at 11:12 +0100, Mathieu Othacehe via
lists.yoctoproject.org wrote:
> 
> Hello Antonin,
> 
> > > poky:
> > > https://git.yoctoproject.org/poky/commit/?h=master-next&id=10448200b63bdc45b39504ebcddd85b5f274f0c4
> > 
> > This link does not work for me. Could you give me a new link with
> > your
> > commits, on master? I couldn't find them.
> 
> Not sure why that one broke, here's a new one:
> 
> https://git.yoctoproject.org/poky/commit/?h=master-next&id=df2c9e884066aafb0dfb60521a4809c5ba4cfd5d

The patch hasn't merged yet, it was queued in master-next which
rebases, hence the ID changes. There are some concerns about the patch,
I'm working on trying to get some feedback about it.

Cheers,

Richard