Thread Local Storage Debug Information

[Jeff Johnson]

The attached is the original proposal for an extension to DWARF adding support
for thread local storage.

The current name/value is:
    DW_OP_GNU_push_tls_address = 0xe0,

As of now (2005-06-13) a more formal proposal is working its way through the
recently re-formed DWARF committee. However, this has been in use for some time.

$Id: dwarf,v 1.4 2002/06/12 21:44:14 jimb Exp $

(The function of DW_OP_push_tls_address is similar to that of the
run-time function __get_tls_addr, so it was tempting to name the
operation DW_OP_get_tls_addr. However, DW_OP_push_tls_address is more
consistent with the names of the other operations, especially
DW_OP_push_object_address.)

To section 2.4.1.3, "Stack Operations", add the following paragraphs
after DW_OP_push_object_address:

12. DW_OP_push_tls_address

The DW_OP_push_tls_address operation pushes the base address of the
current thread's thread-local storage block. If the expression occurs
in the Dwarf information for a dynamically loaded library, then
DW_OP_push_tls_address pushes the base address of that library's block
for the current thread. If the library's storage for the current
thread has not yet been allocated, a Dwarf consumer may arrange for it
to be allocated now, or report an error to the user.

<rationale italics>
Some implementations of C and C++ support a ``__thread'' storage
class, for variables that occupy distinct memory in distinct threads.
For example, the definition:

       __thread int foo;

declares an integer variable named ``foo'' which has a separate value
and address in each thread, much as a variable declared ``auto'' has a
separate value and address in each invocation of the function
containing its declaration. Creating a new thread creates a new
instance of ``foo'', and when the thread exits, the storage for
``foo'' is freed.

Typically, a program includes an ``initialization image'' --- a block
of memory containing the initial values for any thread-local variables
it defines. When the program creates a new thread, the run-time
system allocates a fresh block of memory for those thread-local
variables, and copies the initialization image into it to give the
variables their initialized values.

A dynamically loaded library may also define thread-local variables.
Some implementations delay allocating memory for such variables until
the thread actually refers to them for the first time. This avoids
the overhead of allocating and initializing the library's thread-local
storage for all the threads present in a program when the library is
loaded, even though only a few threads might actually use the library.

However, when an implementation allocates thread-local storage on
demand, this makes it hard to describe the location of a thread-local
variable using ordinary Dwarf expressions: referencing the storage may
entail allocating memory, copying an initialization image into place,
registering it with the thread, and so on. A dedicated operation like
DW_OP_push_tls_address leaves this complicated task to the debugger,
which is presumably already familiar with the program's ABI and thread
system, and can handle the request appropriately.
</rationale italics>