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

[Kevin Buettner <kevinb@redhat.com>]

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