[v2,11/11] Add TLS NEWS entry and document 'set force-internal-tls-address-lookup' command
Checks
| Context |
Check |
Description |
| linaro-tcwg-bot/tcwg_gdb_build--master-arm |
success
|
Build passed
|
| linaro-tcwg-bot/tcwg_gdb_build--master-aarch64 |
success
|
Build passed
|
| linaro-tcwg-bot/tcwg_gdb_check--master-arm |
success
|
Test passed
|
| linaro-tcwg-bot/tcwg_gdb_check--master-aarch64 |
success
|
Test passed
|
Commit Message
---
gdb/NEWS | 20 ++++++++++++++++++
gdb/doc/gdb.texinfo | 50 +++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 70 insertions(+)
Comments
> From: Kevin Buettner <kevinb@redhat.com>
> Cc: Kevin Buettner <kevinb@redhat.com>
> Date: Fri, 11 Oct 2024 19:32:52 -0700
>
> ---
> gdb/NEWS | 20 ++++++++++++++++++
> gdb/doc/gdb.texinfo | 50 +++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 70 insertions(+)
Thanks.
> diff --git a/gdb/NEWS b/gdb/NEWS
> index 42668cbc057..d4970aa6a44 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 'maint 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.
> +
> * New commands
This is okay, but I'd mention "Thread Local Storage" the first time
you use "TLS", to be clear about the meaning.
> +@cindex Thread Local Storage
This should be in lower case.
> +@table @code
> +@kindex maint set force-internal-tls-address-lookup
> +@kindex maint show force-internal-tls-address-lookup
> +@cindex internal @acronym{TLS} address lookup
> +@item maint set force-internal-tls-address-lookup
> +@itemx maint show force-internal-tls-address-lookup
> +Turns on or off forced use of @value{GDBN}-internal @acronym{TLS}
> +address lookup code. Use @code{on} to enable and @code{off} to
> +disable.
This should tell what is the default, I think.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
@@ -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 'maint 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.
+
* New commands
set style line-number foreground COLOR
@@ -4084,6 +4084,56 @@ When @samp{on} @value{GDBN} will print additional messages when
threads are created and deleted.
@end table
+@cindex Thread Local Storage
+@cindex @acronym{TLS}
+For some debugging targets, @value{GDBN} has support for accessing
+variables that reside in Thread Local Storage (@acronym{TLS}).
+@acronym{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, @acronym{TLS} variables can also be used in
+programs without threads. The C library variable @var{errno} is,
+perhaps, the most prominent example of a @acronym{TLS} variable that
+is frequently used in non-threaded programs. For targets where
+@value{GDBN} does not have good @acronym{TLS} support, printing or
+changing the value of @var{errno} might not be directly possible.
+
+@sc{gnu}/Linux and FreeBSD targets have support for accessing
+@acronym{TLS} variables. On @sc{gnu}/Linux, the helper library,
+@code{libthread_db}, is used to help resolve the addresses of
+@acronym{TLS} variables. Some FreeBSD and some @sc{gnu}/Linux targets
+also have @value{GDBN}-internal @acronym{TLS} resolution code.
+@sc{gnu}/Linux targets will attempt to use the @acronym{TLS} address
+lookup functionality provided by @code{libthread_db}, but will fall
+back to using its internal @acronym{TLS} support when
+@code{libthread_db} is not available. This can happen in
+cross-debugging scenarios or when debugging programs that are linked
+in such a way that @code{libthread_db} support is unavailable - this
+includes statically linked programs, linking against @acronym{GLIBC}
+versions earlier than 2.34, but not with @code{libpthread}, and use of
+other (non-@acronym{GLIBC}) C libraries.
+
+@table @code
+@kindex maint set force-internal-tls-address-lookup
+@kindex maint show force-internal-tls-address-lookup
+@cindex internal @acronym{TLS} address lookup
+@item maint set force-internal-tls-address-lookup
+@itemx maint show force-internal-tls-address-lookup
+Turns on or off forced use of @value{GDBN}-internal @acronym{TLS}
+address lookup code. Use @code{on} to enable and @code{off} to
+disable.
+
+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 @acronym{TLS} address lookup mechanisms if necessary.
+
+When enabled, @value{GDBN} will only use @value{GDBN}'s internal
+@acronym{TLS} address lookup mechanisms, if they exist.
+
+This command is only available for @sc{gnu}/Linux targets. Its
+primary use is for testing - certain tests in the @value{GDBN} test
+suite use this command to force use of internal TLS address lookup.
+@end table
+
@node Forks
@section Debugging Forks