README.TLS revision 1.3 
1Steps for adding TLS support for a new platform:
2
3(1) Declare TLS variant in machine/types.h by defining either
4__HAVE_TLS_VARIANT_I or __HAVE_TLS_VARIANT_II.
5
6(2) _lwp_makecontext has to set the reserved register or kernel transfer
7variable in uc_mcontext to the provided value of 'private'. See
8src/lib/libc/arch/$PLATFORM/gen/_lwp.c.
9
10This is not possible on the VAX as there is no free space in ucontext_t.
11This requires either a special version of _lwp_create or versioning
12everything using ucontext_t. Debug support depends on getting the data from
13ucontext_t, so the second option is possibly required.
14
15(3) _lwp_setprivate(2) has to update the same register as
16_lwp_makecontext. cpu_lwp_setprivate has to call _lwp_setprivate(2) to
17reflect the kernel view. cpu_switch has to update the mapping.
18
19_lwp_setprivate is used for the initial thread, all other threads
20created by libpthread use _lwp_makecontext for this purpose.
21
22(4) Provide __tls_get_addr and possible other MD functions for dynamic
23TLS offset computation. If such alternative entry points exist (currently
24only i386), also add a weak reference to 0 in src/lib/libc/tls/tls.c.
25
26The generic implementation can be found in tls.c and is used with
27__HAVE_COMMON___TLS_GET_ADDR. It depends on ___lwp_getprivate_fast.
28
29(5) Implement the necessary relocation records in mdreloc.c.  There are
30typically three relocation types found in dynamic binaries:
31
32(a) R_TYPE(TLS_DTPOFF): Offset inside the module.  The common TLS code
33ensures that the DTV vector points to offset 0 inside the module TLS block.
34This is normally def->st_value + rela->r_addend.
35
36(b) R_TYPE(TLS_DTPMOD): Module index.
37
38(c) R_TYPE(TLS_TPOFF): Static TLS offset.  The code has to check whether
39the static TLS offset for this module has been allocated
40(defobj->tls_done) and otherwise call _rtld_tls_offset_allocate().  This
41may fail if no static space is available and the object has been pulled
42in via dlopen(3).
43
44For TLS Variant I, this is typically:
45
46def->st_value + rela->r_addend + defobj->tlsoffset + sizeof(struct tls_tcb)
47
48e.g. the relocation doesn't include the fixed TCB.
49
50For TLS Variant II, this is typically:
51
52def->st_value - defobj->tlsoffset + rela->r_addend
53
54e.g. starting offset is counting down from the TCB.
55
56(6) Implement _lwp_getprivate_fast() in machine/mcontext.h and set
57__HAVE___LWP_GETPRIVATE_FAST in machine/types.h.
58
59(7) Test using src/tests/lib/libc/tls.  Make sure with "objdump -R" that
60t_tls_dynamic has two TPOFF relocations and h_tls_dlopen.so.1 and
61libh_tls_dynamic.so.1 have both two DTPMOD and DTPOFF relocations.
62