[AAELF64] Allow R_AARCH64_TLS_DTPREL to be used statically. (#330)

Permit the R_AARCH64_TLS_DTPREL dynamic relocation to be used statically
so that debug information can describe the location of TLS variables.

All code sequences to access TLS data use immediates, hence all existing
static TLS relocations are instruction relocations.

To describe the location of a TLS variable in debug information requires
a static data relocation. The necessary expression needed is DTPREL(S +
A) which is performed by the traditional dialect dynamic relocation
R_AARCH64_TLS_DTPREL.

There is prior art in the x86_64 and PPC64 ABIs to use the equivalent
relocation R_X86_64_DTPOFF64 and R_PPC_DTPREL64 respectively for
relocating debug information statically.

We also introduce a syntax for assembler operators operating on data
directives, with an instance %dtprel(expr) to generate R_AARCH64_DTPREL.

The 32-bit Arm ABI uses the R_ARM_TLS_LDO32 static local dynamic
relocation. The advantage of using local dynamic is that these only
apply to a TLS variable local to the module so no additional note is
needed. An alternative design adds a new relocation code to local
dynamic.

fixes: #176

Author: smithp35

aaelf64/aaelf64.rst

@@ -295,6 +295,9 @@ changes to the content of the document for that release.
   |               |                    | - Added section for structure protection|
   |               |                    |   extension relocations.                |
   +---------------+--------------------+-----------------------------------------+
+  | 2026Q1        | 12\ :sup:`th`      | - R_AARCH64_TLS_DTPREL can be used as a |
+  |               | January 2026       |   static relocation as well as dynamic  |
+  +---------------+--------------------+-----------------------------------------+
 
 References
 ----------
@@ -1730,6 +1733,27 @@ Thread-local storage descriptors
 Relocation codes ``R_<CLS>_TLSDESC_LDR``, ``R_<CLS>_TLSDESC_ADD`` and ``R_<CLS>_TLSDESC_CALL`` are needed to permit linker optimization of TLS descriptor code sequences to use Initial-exec or Local-exec TLS sequences; this can only be done if all relevant uses of TLS descriptors are marked to permit accurate relaxation. Object producers that are unable to satisfy this requirement must generate traditional General-dynamic TLS
 sequences using the relocations described in `General Dynamic thread-local storage model`_. The details of TLS descriptors are beyond the scope of this specification; a general introduction can be found in [TLSDESC_].
 
+Thread Local Storage Data Relocations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A data relocation is required to describe the location of a TLS variable in debug information.
+
+.. class:: aaelf64-tls-data-relocations
+
+.. table:: TLS data relocations
+
+  +------------+------------+-----------------------------+------------------------------------+-------------------------------------------+
+  | 1028       | 184        | R\_<CLS>\_TLS\_IMPDEF1      |                                    | See note below                            |
+  +------------+------------+-----------------------------+------------------------------------+-------------------------------------------+
+  | 1029       | 185        | R\_<CLS>\_TLS\_IMPDEF2      |                                    | See note below                            |
+  +------------+------------+-----------------------------+------------------------------------+-------------------------------------------+
+  |            |            | R\_<CLS>\_TLS\_DTPREL       | DTPREL(S+A)                        | See note below                            |
+  +------------+------------+-----------------------------+------------------------------------+-------------------------------------------+
+
+``R_<CLS>_TLS_DTPREL`` is both a static and dynamic relocation. When used as a static relocation ``S`` must be fully resolved at static link time to a symbol definition in the same module as the relocation.
+
+It is implementation defined whether ``R_<CLS>_TLS_IMPDEF1`` implements ``R_<CLS>_TLS_DTPREL`` and ``R_<CLS>_TLS_IMPDEF2`` implements ``R_<CLS>_TLS_DTPMOD`` or whether ``R_<CLS>_TLS_IMPDEF1`` implements ``R_<CLS>_TLS_DTPMOD`` and ``R_<CLS>_TLS_IMPDEF2`` implements ``R_<CLS>_TLS_DTPREL``; a platform must document its choice\ [#aaelf64-f1]_.
+
 Relocations for PAuth ABI Extension
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

sysvabi64/sysvabi64.rst

@@ -218,6 +218,9 @@ Change History
  |            |                              | .note.gnu.property section is present.                |
  |            |                              | - Update distance to GOT for small code-model         |
  +------------+------------------------------+-------------------------------------------------------+
+ | 2026Q1     | 12\ :sup:`th` January 2026   | Add assembler conventions for data directive          |
+ |            |                              | relocation expressions.                               |
+ +------------+------------------------------+-------------------------------------------------------+
 
 References
 ----------
@@ -461,8 +464,8 @@ variant of PIC called PIE (position-independent executable) can be
 used to build an executable. PIE assumes that global symbols cannot be
 pre-empted, which means that an indirection via the GOT is not needed.
 
-Assembler language addressing mode conventions
-----------------------------------------------
+Assembler language addressing mode conventions for instructions
+---------------------------------------------------------------
 
 The assembler examples in this document make use of operators to
 modify the addressing mode used to form the immediate value of the
@@ -654,6 +657,23 @@ syntax is of the form ``#:<operator>:<symbol name>``
 
    PageBreak oneColumn
 
+Assembler language addressing mode conventions for data
+-------------------------------------------------------
+
+The assembler operators that apply to instructions use the syntax
+``#:<operator>:<symbol name>``. This syntax is not easy to apply to
+data directives due to a parsing ambiguity with labels.
+
+The recommended syntax for data directives is ``<directive> %operator(expression)``
+
+.. table:: TLS operators
+
+  +-----------------------+------------+------------------+
+  | Operator              | Data size  | Relocation       |
+  +=======================+============+==================+
+  | ``dtprel``            | 8 bytes    | R_AARCH64_DTPREL |
+  +-----------------------+------------+------------------+
+
 Code Models
 ===========