[11/11] Add TLS NEWS entry and document 'set force-internal-tls-address-lookup' command

  ---
 gdb/NEWS            | 20 ++++++++++++++++++++
 gdb/doc/gdb.texinfo | 17 +++++++++++++++++
 2 files changed, 37 insertions(+)
  

> From: Kevin Buettner <kevinb@redhat.com>
> Cc: Kevin Buettner <kevinb@redhat.com>
> Date: Wed,  9 Oct 2024 19:16:14 -0700
> 
> ---
>  gdb/NEWS            | 20 ++++++++++++++++++++
>  gdb/doc/gdb.texinfo | 17 +++++++++++++++++
>  2 files changed, 37 insertions(+)

Thanks.

A general comment: I think the documentation changes should include
the explanation of the "TLS" acronym and its meaning in the context of
debugging.  Without saying that much, this piece of documentation
makes very little sense, if at all.

Another aspect that is missing is how the new commands affect
user-level features in GDB.  What does it mean to "force TLS lookup",
and how does it matter whether the TLS look up is internal or via
libthread_db, when a program uses thread-local storage?  More
generally, what is "TLS address look up" and how it affects debugging
multithreaded programs?  Note that the current text in the manual
mentions libthread_db as a "helper library" for debugging
multithreaded programs, but doesn't go into details of what that
"help" includes, leaving that vague and unexplained.  This addition
builds on that description, but it talks about a very specific aspect
of supporting threads, and does that without explaining its role.  The
previous text about libthread_db doesn't help in any way, so we must
add some details here, IMO.

Some more specific comments follow:

> diff --git a/gdb/NEWS b/gdb/NEWS
> index 42668cbc057..dcb24eb5248 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -63,6 +63,26 @@
>       the return value from the latest "stepOut" command, when
>       appropriate.
>  
> +* GDB-internal TLS support
> +
> +  ** Linux targets for the x86_64, aarch64, ppc64, s390x, and riscv
> +     architectures now have GDB-internal support for TLS address
> +     lookup in addition to that traditionally provided by the
> +     libthread_db library.  This internal support works for programs
> +     linked against either the GLIBC or MUSL C libraries.  For
> +     programs linked against MUSL, this new internal support provides
> +     new debug functionality, allowing access to TLS variables, due to
> +     the fact that MUSL does not implement the libthread_db library. 
> +     Internal TLS support is also useful in cross-debugging
> +     situations, debugging statically linked binaries, and debugging
> +     programs linked against GLIBC 2.33 and earlier, but which are not
> +     linked against libpthread.
> +
> +  ** The command 'set force-internal-tls-address-lookup on' may be
> +     used to force the internal TLS lookup mechanisms to be used.
> +     Otherwise, TLS lookup via libthread_db will still be preferred,
> +     when available.

Do we support TLS on any platform but Linux?

> +@kindex set force-internal-tls-address-lookup
> +@kindex show force-internal-tls-address-lookup
> +@cindex internal TLS lookup
> +Turns on or off forced use of @value{GDBN}-internal TLS (Thread Local
> +Storage) address lookup code.  Use @code{on} to enable and @code{0} to
> +disable.

Please add here some index entry that uses "thread-local storage".

Also, "TLS" should be in @acronym (here and elsewhere in the patch).

> +When disabled, @value{GDBN} will attempt to use a helper
> +@code{libthread_db} library if possible, but will fall back to use of
> +its own internal TLS address lookup mechanisms if necessary.
> +
> +When enabled, @value{GDBN} will only use the @value{GDBN}'s internal
> +TLS address lookup mechanisms, if they exist.
> +
> +This command is only available on targets for which internal TLS
> +address lookup support exists.

I think we should tell here that this setting has effect only for
targets that use libthread_db.
  

Hi Eli,

On Thu, 10 Oct 2024 09:01:31 +0300
Eli Zaretskii <eliz@gnu.org> wrote:

> Thanks.
> 
> A general comment: I think the documentation changes should include
> the explanation of the "TLS" acronym and its meaning in the context of
> debugging.  Without saying that much, this piece of documentation
> makes very little sense, if at all.
> 
> Another aspect that is missing is how the new commands affect
> user-level features in GDB.  What does it mean to "force TLS lookup",
> and how does it matter whether the TLS look up is internal or via
> libthread_db, when a program uses thread-local storage?  More
> generally, what is "TLS address look up" and how it affects debugging
> multithreaded programs?  Note that the current text in the manual
> mentions libthread_db as a "helper library" for debugging
> multithreaded programs, but doesn't go into details of what that
> "help" includes, leaving that vague and unexplained.  This addition
> builds on that description, but it talks about a very specific aspect
> of supporting threads, and does that without explaining its role.  The
> previous text about libthread_db doesn't help in any way, so we must
> add some details here, IMO.

I'm trying to figure out where in the doc to add background
material regarding TLS.

Adding it to the text explaining the new command doesn't really
fit with the way that other commands are documented.  It seems
to me that it ought to be placed in some prefatory remarks.

If so, should it stay within "Debugging Programs with Multiple
Threads"?  Or would it make sense to make a new section, perhaps named
"Thread Local Storage"?

Without getting bogged down with texinfo markup yet, here
is what I propose saying about TLS:

    For some debugging targets, GDB has support for accessing
    variables that reside in Thread Local Storage (TLS).  TLS
    variables are similar to global variables, except that each thread
    has its own copy of the variable.  While often used in
    multi-threaded programs, TLS variables can also be used in
    programs without threads.  The C library variable 'errno' is,
    perhaps, the most prominent example of a TLS variable that is
    frequently used in non-threaded programs.  For targets where GDB
    does not have good TLS support, printing the value of errno might
    not be directly possible.

    Linux and FreeBSD targets have support for printing TLS variables. 
    On Linux, the helper library, libthread_db, is used to help
    resolve the addresses of TLS variables.  Some FreeBSD and some
    Linux targets also have GDB-internal TLS resolution code.  Linux
    targets will attempt to use the TLS address lookup functionality
    provided by libthread_db, but will fall back to using its
    internal TLS support when libthread_db is not available.  This can
    happen in cross-debugging scenarios or when debugging programs
    that are linked in such a way that libthread_db support is
    unavailable - this includes statically linked programs, GLIBC
    versions earlier than 2.34, and use of other (non-GLIBC) C libraries.

    [Doc regarding "set force-internal-tls-address-lookup" goes here.]

There's a lot more that could be said about errno.  Earlier this
year, I wrote an article about it.  See:

https://developers.redhat.com/articles/2024/06/05/why-your-errno-value-isnt-printing-gdb-and-what-do-about-it

That article dealt with errno problems on Linux, but some of the same
tricks, with some tweaks, might apply to other environments too.  It
might make sense to try document some ways to obtain the value of
errno when "print errno" doesn't just work.  But that can be the
topic of another patch.

With regard to the question of why you might want to force use of
internal TLS lookup, it's mostly for testing purposes.  For the new
tests that I wrote, I needed a way to ensure that the internal TLS
address resolution code was being used, so I made a command which
does that.  I'll mention that in a v2 patch.  I do, however, already
mention it in the help text:

    (gdb) help set force-internal-tls-address-lookup 
    Set to force internal TLS address lookup.
    When resolving addresses for TLS (Thread Local Storage) variables,
    GDB will attempt to use facilities provided by the thread library (i.e.
    libthread_db).  If those facilities aren't available, GDB will fall
    back to using some internal (to GDB), but possibly less accurate
    mechanisms to resolve the addresses for TLS variables.  When this flag
    is set, GDB will force use of the fall-back TLS resolution mechanisms.
    This flag is used by some GDB tests to ensure that the internal fallback
    code is exercised and working as expected.  The default is to not force
    the internal fall-back mechanisms to be used.

Kevin
  

> Date: Thu, 10 Oct 2024 16:27:50 -0700
> From: Kevin Buettner <kevinb@redhat.com>
> Cc: gdb-patches@sourceware.org
> 
> I'm trying to figure out where in the doc to add background
> material regarding TLS.
> 
> Adding it to the text explaining the new command doesn't really
> fit with the way that other commands are documented.  It seems
> to me that it ought to be placed in some prefatory remarks.
> 
> If so, should it stay within "Debugging Programs with Multiple
> Threads"?  Or would it make sense to make a new section, perhaps named
> "Thread Local Storage"?

We could leave it in the multiple-threads section (as the text is not
too long, and is related to threads), or we could add a new section
under "Data".  In the latter case, you'd need to use cross-references
judiciously, both in the new section and in "Threads", to provide the
reader with all the relevant information, since libthread_db and the
commands related to it are only discussed in "Threads", and the new
command will be described there as well.

> Without getting bogged down with texinfo markup yet, here
> is what I propose saying about TLS:
> 
>     For some debugging targets, GDB has support for accessing
>     variables that reside in Thread Local Storage (TLS).  TLS
>     variables are similar to global variables, except that each thread
>     has its own copy of the variable.  While often used in
>     multi-threaded programs, TLS variables can also be used in
>     programs without threads.  The C library variable 'errno' is,
>     perhaps, the most prominent example of a TLS variable that is
>     frequently used in non-threaded programs.  For targets where GDB
>     does not have good TLS support, printing the value of errno might
>     not be directly possible.
> 
>     Linux and FreeBSD targets have support for printing TLS variables. 
>     On Linux, the helper library, libthread_db, is used to help
>     resolve the addresses of TLS variables.  Some FreeBSD and some
>     Linux targets also have GDB-internal TLS resolution code.  Linux
>     targets will attempt to use the TLS address lookup functionality
>     provided by libthread_db, but will fall back to using its
>     internal TLS support when libthread_db is not available.  This can
>     happen in cross-debugging scenarios or when debugging programs
>     that are linked in such a way that libthread_db support is
>     unavailable - this includes statically linked programs, GLIBC
>     versions earlier than 2.34, and use of other (non-GLIBC) C libraries.

LGTM.

> There's a lot more that could be said about errno.  Earlier this
> year, I wrote an article about it.  See:
> 
> https://developers.redhat.com/articles/2024/06/05/why-your-errno-value-isnt-printing-gdb-and-what-do-about-it
> 
> That article dealt with errno problems on Linux, but some of the same
> tricks, with some tweaks, might apply to other environments too.  It
> might make sense to try document some ways to obtain the value of
> errno when "print errno" doesn't just work.  But that can be the
> topic of another patch.

We can have a summary of that in this new section.

Btw, the MS-Windows situation is similar to what you describe for
Linux.  The MinGW <errno.h> says:

  _CRTIMP int *__cdecl  _errno(void);
  #define errno           (*_errno())

So one can display errno by calling this function with an explicit
type-cast.  Maybe we should mention that if and when we add this to
the GDB manual.

> With regard to the question of why you might want to force use of
> internal TLS lookup, it's mostly for testing purposes.

If this is for testing, shouldn't it be a maint command?
  

On Fri, 11 Oct 2024 08:42:33 +0300
Eli Zaretskii <eliz@gnu.org> wrote:

> > With regard to the question of why you might want to force use of
> > internal TLS lookup, it's mostly for testing purposes.  
> 
> If this is for testing, shouldn't it be a maint command?

Well, _mostly_ for testing.

I can imagine situations where a GDB user prints a TLS variable, but
doesn't believe the answer being printed.  Being able to switch the
TLS address resolution mechanism allows the user to see if a different
answer might be printed.

That said, I'm fine with changing it, since it's likely to be used by
few aside from GDB maintainers.  I'll make this change for the v2
series.  (I also need to address some problems found by the Linaro
regression tester.)

Kevin