[docs][PATCH v2] manuals: document minidebuginfo

[docs][PATCH v2] manuals: document minidebuginfo

[ecordonnier]

From: Etienne Cordonnier <ecordonnier@snap.com>

Signed-off-by: Etienne Cordonnier <ecordonnier@snap.com>
---
 documentation/dev-manual/debugging.rst | 15 +++++++++++++++
 documentation/ref-manual/features.rst  |  3 +++
 2 files changed, 18 insertions(+)

diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index fea2cb30a..12694b01b 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -1173,6 +1173,21 @@ To support this kind of debugging, you need do the following:
    Consider that this will reduce the application's performance and is
    recommended only for debugging purposes.
 
+Enabling Minidebuginfo
+======================
+
+Enabling the DISTRO_FEATURES minidebuginfo adds a compressed ELF section ".gnu_debugdata"
+to all binary files, containing only function names, and thus increasing the size of the
+binaries only by 5 to 10%. For comparison, full debug symbols can be 10 times as big as
+a stripped binary, and it is thus not always possible to deploy full debug symbols.
+Minidebuginfo data allows, on the one side, to retrieve a call-stack using
+gdb (command backtrace) without deploying full debug-symbols to the target. It also
+allows to retrieve a symbolicated call-stack when using systemd-coredump to manage
+coredumps (commands "coredumpctl list" and "coredumpctl info").
+
+This feature was created by Fedora, see https://fedoraproject.org/wiki/Features/MiniDebugInfo for
+more details.
+
 Other Debugging Tips
 ====================
 
diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst
index dd14339bc..1320c3a58 100644
--- a/documentation/ref-manual/features.rst
+++ b/documentation/ref-manual/features.rst
@@ -161,6 +161,9 @@ metadata, as extra layers can define their own:
 -  *keyboard:* Include keyboard support (e.g. keymaps will be loaded
    during boot).
 
+-  *minidebuginfo:* Add minimal debug symbols :ref:`(minidebuginfo)<dev-manual/debugging:enabling minidebuginfo>`
+   to binary files containing, allowing coredumpctl and gdb to show symbolicated stack traces.
+
 -  *multiarch:* Enable building applications with multiple architecture
    support.
 
-- 
2.36.1.vfs.0.0

Re: [docs][PATCH v2] manuals: document minidebuginfo

[Michael Opdenacker]

Hi Etienne,

Many thanks for your contribution. Happy to learn about MiniDebugInfo!

See my comments below, mostly about formatting issues. I could fix it by 
myself if you lack time, but this way you know this for future patches :)

On 07.12.23 at 15:08, Etienne Cordonnier via lists.yoctoproject.org wrote:
> From: Etienne Cordonnier <ecordonnier@snap.com>
>
> Signed-off-by: Etienne Cordonnier <ecordonnier@snap.com>
> ---
>   documentation/dev-manual/debugging.rst | 15 +++++++++++++++
>   documentation/ref-manual/features.rst  |  3 +++
>   2 files changed, 18 insertions(+)
>
> diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
> index fea2cb30a..12694b01b 100644
> --- a/documentation/dev-manual/debugging.rst
> +++ b/documentation/dev-manual/debugging.rst
> @@ -1173,6 +1173,21 @@ To support this kind of debugging, you need do the following:
>      Consider that this will reduce the application's performance and is
>      recommended only for debugging purposes.
>   
> +Enabling Minidebuginfo
> +======================
> +
> +Enabling the DISTRO_FEATURES minidebuginfo adds a compressed ELF section ".gnu_debugdata"


Use :term:`DISTRO_FEATURES`
and ``.gnu_debugdata``

> +to all binary files, containing only function names, and thus increasing the size of the
> +binaries only by 5 to 10%. For comparison, full debug symbols can be 10 times as big as
> +a stripped binary, and it is thus not always possible to deploy full debug symbols.
> +Minidebuginfo data allows, on the one side, to retrieve a call-stack using
> +gdb (command backtrace) without deploying full debug-symbols to the target. It also


Use ``gdb`` (to refer to the command) or GDB (to refer to the program) 
as in other parts of the manual.

Replace "debug-symbols" by "debugging symbols"?

> +allows to retrieve a symbolicated call-stack when using systemd-coredump to manage


Use ``systemd-coredump``

> +coredumps (commands "coredumpctl list" and "coredumpctl info").

Use ``coredumpctl list`` and ``coredumpctl info``

> +
> +This feature was created by Fedora, see https://fedoraproject.org/wiki/Features/MiniDebugInfo for
> +more details.
> +
>   Other Debugging Tips
>   ====================
>   
> diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst
> index dd14339bc..1320c3a58 100644
> --- a/documentation/ref-manual/features.rst
> +++ b/documentation/ref-manual/features.rst
> @@ -161,6 +161,9 @@ metadata, as extra layers can define their own:
>   -  *keyboard:* Include keyboard support (e.g. keymaps will be loaded
>      during boot).
>   
> +-  *minidebuginfo:* Add minimal debug symbols :ref:`(minidebuginfo)<dev-manual/debugging:enabling minidebuginfo>`


Use "debugging symbols" as in the change above?

> +   to binary files containing, allowing coredumpctl and gdb to show symbolicated stack traces.


Use ``coredumpctl`` and ``gdb``.
Thanks again
Cheers
Michael.

-- 

Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs][PATCH v2] manuals: document minidebuginfo

[Etienne Cordonnier]

[-- Attachment #1: Type: text/plain, Size: 4613 bytes --]

Hi / bonjour Michael,

Thanks for your feedback, indeed it is meaningful that I learn the proper
formatting for future patches. I changed everything according to your
feedback, except "debug symbol" (I only removed the hyphen), my reasoning
being:
- even though I find both "debug symbol" and "debugging symbol" on google,
the wikipedia article is called "debug symbol" (
https://en.wikipedia.org/wiki/Debug_symbol )
- yocto documentation uses both "debug symbol" and "debugging symbol",
however I find 5 hits for "debugging symbol" vs 35 hits for "debug symbol"
- I asked a native English speaker and he thought "debug symbol" sounded
better

Etienne


On Fri, Dec 8, 2023 at 9:19 AM Michael Opdenacker <
michael.opdenacker@bootlin.com> wrote:

> Hi Etienne,
>
> Many thanks for your contribution. Happy to learn about MiniDebugInfo!
>
> See my comments below, mostly about formatting issues. I could fix it by
> myself if you lack time, but this way you know this for future patches :)
>
> On 07.12.23 at 15:08, Etienne Cordonnier via lists.yoctoproject.org wrote:
> > From: Etienne Cordonnier <ecordonnier@snap.com>
> >
> > Signed-off-by: Etienne Cordonnier <ecordonnier@snap.com>
> > ---
> >   documentation/dev-manual/debugging.rst | 15 +++++++++++++++
> >   documentation/ref-manual/features.rst  |  3 +++
> >   2 files changed, 18 insertions(+)
> >
> > diff --git a/documentation/dev-manual/debugging.rst
> b/documentation/dev-manual/debugging.rst
> > index fea2cb30a..12694b01b 100644
> > --- a/documentation/dev-manual/debugging.rst
> > +++ b/documentation/dev-manual/debugging.rst
> > @@ -1173,6 +1173,21 @@ To support this kind of debugging, you need do
> the following:
> >      Consider that this will reduce the application's performance and is
> >      recommended only for debugging purposes.
> >
> > +Enabling Minidebuginfo
> > +======================
> > +
> > +Enabling the DISTRO_FEATURES minidebuginfo adds a compressed ELF
> section ".gnu_debugdata"
>
>
> Use :term:`DISTRO_FEATURES`
> and ``.gnu_debugdata``
>
> > +to all binary files, containing only function names, and thus
> increasing the size of the
> > +binaries only by 5 to 10%. For comparison, full debug symbols can be 10
> times as big as
> > +a stripped binary, and it is thus not always possible to deploy full
> debug symbols.
> > +Minidebuginfo data allows, on the one side, to retrieve a call-stack
> using
> > +gdb (command backtrace) without deploying full debug-symbols to the
> target. It also
>
>
> Use ``gdb`` (to refer to the command) or GDB (to refer to the program)
> as in other parts of the manual.
>
> Replace "debug-symbols" by "debugging symbols"?
>
> > +allows to retrieve a symbolicated call-stack when using
> systemd-coredump to manage
>
>
> Use ``systemd-coredump``
>
> > +coredumps (commands "coredumpctl list" and "coredumpctl info").
>
> Use ``coredumpctl list`` and ``coredumpctl info``
>
> > +
> > +This feature was created by Fedora, see
> https://urldefense.proofpoint.com/v2/url?u=https-3A__fedoraproject.org_wiki_Features_MiniDebugInfo&d=DwICaQ&c=ncDTmphkJTvjIDPh0hpF_4vCHvabgGkICC2epckfdiw&r=AhkbNonVuMIGRfPx_Qj9TsRih1DULJTKUkSGa66m67E&m=hQV-UWkUsNIhb4Pyow0-VyHqmNd6krcB7umcC1z9AOQiDkBhJM3XT-1O8-fB_Gik&s=zTnO9U6vQxH0Thr-4OnmF-jGcGK4b_1R-ikzP832JoQ&e=
> for
> > +more details.
> > +
> >   Other Debugging Tips
> >   ====================
> >
> > diff --git a/documentation/ref-manual/features.rst
> b/documentation/ref-manual/features.rst
> > index dd14339bc..1320c3a58 100644
> > --- a/documentation/ref-manual/features.rst
> > +++ b/documentation/ref-manual/features.rst
> > @@ -161,6 +161,9 @@ metadata, as extra layers can define their own:
> >   -  *keyboard:* Include keyboard support (e.g. keymaps will be loaded
> >      during boot).
> >
> > +-  *minidebuginfo:* Add minimal debug symbols
> :ref:`(minidebuginfo)<dev-manual/debugging:enabling minidebuginfo>`
>
>
> Use "debugging symbols" as in the change above?
>
> > +   to binary files containing, allowing coredumpctl and gdb to show
> symbolicated stack traces.
>
>
> Use ``coredumpctl`` and ``gdb``.
> Thanks again
> Cheers
> Michael.
>
> --
>
> Michael Opdenacker, Bootlin
> Embedded Linux and Kernel engineering
>
> https://urldefense.proofpoint.com/v2/url?u=https-3A__bootlin.com&d=DwICaQ&c=ncDTmphkJTvjIDPh0hpF_4vCHvabgGkICC2epckfdiw&r=AhkbNonVuMIGRfPx_Qj9TsRih1DULJTKUkSGa66m67E&m=hQV-UWkUsNIhb4Pyow0-VyHqmNd6krcB7umcC1z9AOQiDkBhJM3XT-1O8-fB_Gik&s=rbqxBdiyaYg0d0YO9htyEO3uk_oMr48vN-X-L0UPwPE&e=
>
>

[-- Attachment #2: Type: text/html, Size: 6455 bytes --]

Re: [docs][PATCH v2] manuals: document minidebuginfo

[Etienne Cordonnier]

[-- Attachment #1: Type: text/plain, Size: 4126 bytes --]

Patch v2: Fixed grammar according to Ulrich's feedback:
s/of 5 to 10%/by 5 to 10%/

Etienne

On Thu, Dec 7, 2023 at 3:08 PM Etienne Cordonnier via lists.yoctoproject.org
<ecordonnier=snap.com@lists.yoctoproject.org> wrote:

> From: Etienne Cordonnier <ecordonnier@snap.com>
>
> Signed-off-by: Etienne Cordonnier <ecordonnier@snap.com>
> ---
>  documentation/dev-manual/debugging.rst | 15 +++++++++++++++
>  documentation/ref-manual/features.rst  |  3 +++
>  2 files changed, 18 insertions(+)
>
> diff --git a/documentation/dev-manual/debugging.rst
> b/documentation/dev-manual/debugging.rst
> index fea2cb30a..12694b01b 100644
> --- a/documentation/dev-manual/debugging.rst
> +++ b/documentation/dev-manual/debugging.rst
> @@ -1173,6 +1173,21 @@ To support this kind of debugging, you need do the
> following:
>     Consider that this will reduce the application's performance and is
>     recommended only for debugging purposes.
>
> +Enabling Minidebuginfo
> +======================
> +
> +Enabling the DISTRO_FEATURES minidebuginfo adds a compressed ELF section
> ".gnu_debugdata"
> +to all binary files, containing only function names, and thus increasing
> the size of the
> +binaries only by 5 to 10%. For comparison, full debug symbols can be 10
> times as big as
> +a stripped binary, and it is thus not always possible to deploy full
> debug symbols.
> +Minidebuginfo data allows, on the one side, to retrieve a call-stack using
> +gdb (command backtrace) without deploying full debug-symbols to the
> target. It also
> +allows to retrieve a symbolicated call-stack when using systemd-coredump
> to manage
> +coredumps (commands "coredumpctl list" and "coredumpctl info").
> +
> +This feature was created by Fedora, see
> https://urldefense.proofpoint.com/v2/url?u=https-3A__fedoraproject.org_wiki_Features_MiniDebugInfo&d=DwIDAg&c=ncDTmphkJTvjIDPh0hpF_4vCHvabgGkICC2epckfdiw&r=AhkbNonVuMIGRfPx_Qj9TsRih1DULJTKUkSGa66m67E&m=YXeDmFamWpT6qC-yFNYvNIC8dcQgCpj0yktlGvqpuJU1lflqnaJCc47hrcxEtbdf&s=nLuMgeFeJNMlIMiWN8PUROk-3ig9Cm7VHE0J-vVeP2A&e=
> for
> +more details.
> +
>  Other Debugging Tips
>  ====================
>
> diff --git a/documentation/ref-manual/features.rst
> b/documentation/ref-manual/features.rst
> index dd14339bc..1320c3a58 100644
> --- a/documentation/ref-manual/features.rst
> +++ b/documentation/ref-manual/features.rst
> @@ -161,6 +161,9 @@ metadata, as extra layers can define their own:
>  -  *keyboard:* Include keyboard support (e.g. keymaps will be loaded
>     during boot).
>
> +-  *minidebuginfo:* Add minimal debug symbols
> :ref:`(minidebuginfo)<dev-manual/debugging:enabling minidebuginfo>`
> +   to binary files containing, allowing coredumpctl and gdb to show
> symbolicated stack traces.
> +
>  -  *multiarch:* Enable building applications with multiple architecture
>     support.
>
> --
> 2.36.1.vfs.0.0
>
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#4666):
> https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.yoctoproject.org_g_docs_message_4666&d=DwIFaQ&c=ncDTmphkJTvjIDPh0hpF_4vCHvabgGkICC2epckfdiw&r=AhkbNonVuMIGRfPx_Qj9TsRih1DULJTKUkSGa66m67E&m=YXeDmFamWpT6qC-yFNYvNIC8dcQgCpj0yktlGvqpuJU1lflqnaJCc47hrcxEtbdf&s=7PlaS4qaGHb1v_X9vINbttbEvcXYCom5eXEQCwKZLDA&e=
> Mute This Topic:
> https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.yoctoproject.org_mt_103034540_7048771&d=DwIFaQ&c=ncDTmphkJTvjIDPh0hpF_4vCHvabgGkICC2epckfdiw&r=AhkbNonVuMIGRfPx_Qj9TsRih1DULJTKUkSGa66m67E&m=YXeDmFamWpT6qC-yFNYvNIC8dcQgCpj0yktlGvqpuJU1lflqnaJCc47hrcxEtbdf&s=-s69Se9_govdXJfABjAcyjYfch1dRtFTX3-t-DsOAfU&e=
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe:
> https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.yoctoproject.org_g_docs_unsub&d=DwIFaQ&c=ncDTmphkJTvjIDPh0hpF_4vCHvabgGkICC2epckfdiw&r=AhkbNonVuMIGRfPx_Qj9TsRih1DULJTKUkSGa66m67E&m=YXeDmFamWpT6qC-yFNYvNIC8dcQgCpj0yktlGvqpuJU1lflqnaJCc47hrcxEtbdf&s=WPXYi_eDq2Maud3rxLAD1r5pjG3pCDifwZaOYRBJMeM&e=
> [ecordonnier@snap.com]
> -=-=-=-=-=-=-=-=-=-=-=-
>
>

[-- Attachment #2: Type: text/html, Size: 6498 bytes --]