libexec/ld.elf_so/README.TLS

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