Clarify GOT layout and relaxations.

riscv-elf.adoc

@@ -956,8 +956,8 @@ TLS Descriptors (TLSDESC) are an alternative implementation of the Global Dynami
 that allows the dynamic linker to achieve performance close to that
 of Initial Exec when the library was not loaded dynamically with `dlopen`.
 
-For each `TLSDESC` relocation inside the GOT, the dynamic linker fills in the
-TLS descriptor entry as defined below:
+The linker reserves a consecutive pair of pointer-sized entry in the GOT for each `TLSDESC`
+relocation. At runtime, the dynamic linker fills in the TLS descriptor entry as defined below:
 
 [,c]
 ----
@@ -968,8 +968,8 @@ typedef struct
 } tls_descriptor;
 ----
 
-The `entry` function is called with the address of `tls_descriptor` containing it,
-and returns `<address of TLS variable> - tp`.
+Upon accessing the thread local variable, the `entry` function is called with the address
+of `tls_descriptor` containing it, returning `<address of thread local variable> - tp`.
 
 The TLS descriptor `entry` is called with a special calling convention, specified as follows:
 
@@ -1605,7 +1605,8 @@ Target Relocation:: R_RISCV_TLSDESC_HI20, R_RISCV_TLSDESC_LOAD_LO12_I, R_RISCV_T
 
 Description:: This relaxation can relax a sequence loading the address of a thread-local symbol reference into a GOT load instruction.
 
-Condition:: None.
+Condition::
+- Linker output is an executable.
 
 Relaxation::
 
@@ -1615,15 +1616,15 @@ Relaxation::
 Example::
 +
 --
-Relaxation candidate:
+Relaxation candidate (`tX` and `tY` can be any combination of two general purpose registers):
 
 [,asm]
 ----
 label:
-	auipc a0, 0     // R_RISCV_TLSDESC_HI20 (symbol), R_RISCV_RELAX
-	lw    t0, a0, 0 // R_RISCV_TLSDESC_LOAD_LO12_I (label), R_RISCV_RELAX
-	addi  a0, a0, 0 // R_RISCV_TLSDESC_ADD_LO12_I (label), R_RISCV_RELAX
-	jalr  t0, t0    // R_RISCV_TLSDESC_CALL (label), R_RISCV_RELAX
+	auipc tX, <hi>      // R_RISCV_TLSDESC_HI20 (symbol), R_RISCV_RELAX
+	lw    tY, tX, <lo>  // R_RISCV_TLSDESC_LOAD_LO12_I (label), R_RISCV_RELAX
+	addi  a0, tX, <lo>  // R_RISCV_TLSDESC_ADD_LO12_I (label), R_RISCV_RELAX
+	jalr  t0, tY        // R_RISCV_TLSDESC_CALL (label), R_RISCV_RELAX
 ----
 
 Relaxation result:
@@ -1643,8 +1644,9 @@ Description:: This relaxation can relax a sequence loading the address of a thre
 
 Condition::
 
-- For the short form: Offset between thread-pointer and thread-local symbol is within +-2KiB.
-- For the long form: None.
+- Short form only: Offset between thread-pointer and thread-local symbol is within +-2KiB.
+- Linker output is an executable.
+- Target symbol is non-preemptible.
 
 Relaxation::
 
@@ -1655,15 +1657,15 @@ Relaxation::
 Example::
 +
 --
-Relaxation candidate:
+Relaxation candidate (`tX` and `tY` can be any combination of two general purpose registers):
 
 [,asm]
 ----
 label:
-	auipc a0, 0     // R_RISCV_TLSDESC_HI20 (symbol), R_RISCV_RELAX
-	lw    t0, a0, 0 // R_RISCV_TLSDESC_LOAD_LO12_I (label), R_RISCV_RELAX
-	addi  a0, a0, 0 // R_RISCV_TLSDESC_ADD_LO12_I (label), R_RISCV_RELAX
-	jalr  t0, t0    // R_RISCV_TLSDESC_CALL (label), R_RISCV_RELAX
+	auipc tX, <hi>      // R_RISCV_TLSDESC_HI20 (symbol), R_RISCV_RELAX
+	lw    tY, tX, <lo>  // R_RISCV_TLSDESC_LOAD_LO12_I (label), R_RISCV_RELAX
+	addi  a0, tX, <lo>  // R_RISCV_TLSDESC_ADD_LO12_I (label), R_RISCV_RELAX
+	jalr  t0, tY        // R_RISCV_TLSDESC_CALL (label), R_RISCV_RELAX
 ----
 
 Relaxation result (long form):