RISC-V: Add description for RISC-V Modifiers to as doc.

	gas/
	* doc/c-riscv.texi (relocation modifiers): Add documentation.
	(RISC-V-Formats): Update the section name from "Instruction Formats"
	to "RISC-V Instruction Formats".

diff --git a/gas/ChangeLog b/gas/ChangeLog
index d5611ee76854d1fee3bc9b85815d635ec51c9cb6..179ebe789a61d4206aef773423c5c90460e17911 100644 (file)
--- a/gas/ChangeLog
+++ b/gas/ChangeLog
@@ -1,3 +1,9 @@
+2020-03-04  Nelson Chu  <nelson.chu@sifive.com>
+
+       * doc/c-riscv.texi (relocation modifiers): Add documentation.
+       (RISC-V-Formats): Update the section name from "Instruction Formats"
+       to "RISC-V Instruction Formats".
+
 2020-03-04  Alexandre Oliva  <oliva@adacore.com>
 
        * config/tc-arm.c (md_apply_fix): Warn if a PC-relative load is

diff --git a/gas/doc/c-riscv.texi b/gas/doc/c-riscv.texi
index 599b5cf8afeb8b0d027b3ce4632e8d400eb9f6f6..6e932dcb2443c9c68e0aaeea9b110f83cf3614a9 100644 (file)
--- a/gas/doc/c-riscv.texi
+++ b/gas/doc/c-riscv.texi
@@ -17,6 +17,7 @@
 @menu
 * RISC-V-Options::        RISC-V Options
 * RISC-V-Directives::     RISC-V Directives
+* RISC-V-Modifiers::      RISC-V Assembler Modifiers
 * RISC-V-Formats::        RISC-V Instruction Formats
 * RISC-V-ATTRIBUTE::      RISC-V Object Attribute
 @end menu
@@ -207,8 +208,117 @@ The @var{tag} is either an attribute number, or one of the following:
 
 @end table
 
+@node RISC-V-Modifiers
+@section RISC-V Assembler Modifiers
+
+The RISC-V assembler supports following modifiers for relocatable addresses
+used in RISC-V instruction operands.  However, we also support some pseudo
+instructions that are easier to use than these modifiers.
+
+@table @code
+@item %lo(@var{symbol})
+The low 12 bits of absolute address for @var{symbol}.
+
+@item %hi(@var{symbol})
+The high 20 bits of absolute address for @var{symbol}.  This is usually
+used with the %lo modifier to represent a 32-bit absolute address.
+
+@smallexample
+       lui        a0, %hi(@var{symbol})     // R_RISCV_HI20
+       addi       a0, a0, %lo(@var{symbol}) // R_RISCV_LO12_I
+
+       lui        a0, %hi(@var{symbol})     // R_RISCV_HI20
+       load/store a0, %lo(@var{symbol})(a0) // R_RISCV_LO12_I/S
+@end smallexample
+
+@item %pcrel_lo(@var{label})
+The low 12 bits of relative address between pc and @var{symbol}.
+The @var{symbol} is related to the high part instruction which is marked
+by @var{label}.
+
+@item %pcrel_hi(@var{symbol})
+The high 20 bits of relative address between pc and @var{symbol}.
+This is usually used with the %pcrel_lo modifier to represent a +/-2GB
+pc-relative range.
+
+@smallexample
+@var{label}:
+       auipc      a0, %pcrel_hi(@var{symbol})    // R_RISCV_PCREL_HI20
+       addi       a0, a0, %pcrel_lo(@var{label}) // R_RISCV_PCREL_LO12_I
+
+@var{label}:
+       auipc      a0, %pcrel_hi(@var{symbol})    // R_RISCV_PCREL_HI20
+       load/store a0, %pcrel_lo(@var{label})(a0) // R_RISCV_PCREL_LO12_I/S
+@end smallexample
+
+Or you can use the pseudo lla/lw/sw/... instruction to do this.
+
+@smallexample
+       lla  a0, @var{symbol}
+@end smallexample
+
+@item %tprel_add(@var{symbol})
+This is used purely to associate the R_RISCV_TPREL_ADD relocation for
+TLS relaxation.  This one is only valid as the fourth operand to the normally
+3 operand add instruction.
+
+@item %tprel_lo(@var{symbol})
+The low 12 bits of relative address between tp and @var{symbol}.
+
+@item %tprel_hi(@var{symbol})
+The high 20 bits of relative address between tp and @var{symbol}.  This is
+usually used with the %tprel_lo and %tprel_add modifiers to access the thread
+local variable @var{symbol} in TLS Local Exec.
+
+@smallexample
+       lui        a5, %tprel_hi(@var{symbol})          // R_RISCV_TPREL_HI20
+       add        a5, a5, tp, %tprel_add(@var{symbol}) // R_RISCV_TPREL_ADD
+       load/store t0, %tprel_lo(@var{symbol})(a5)      // R_RISCV_TPREL_LO12_I/S
+@end smallexample
+
+@item %tls_ie_pcrel_hi(@var{symbol})
+The high 20 bits of relative address between pc and GOT entry.  It is
+usually used with the %pcrel_lo modifier to access the thread local
+variable @var{symbol} in TLS Initial Exec.
+
+@smallexample
+       la.tls.ie  a5, @var{symbol}
+       add        a5, a5, tp
+       load/store t0, 0(a5)
+@end smallexample
+
+The pseudo la.tls.ie instruction can be expended to
+
+@smallexample
+@var{label}:
+       auipc a5, %tls_ie_pcrel_hi(@var{symbol}) // R_RISCV_TLS_GOT_HI20
+       load  a5, %pcrel_lo(@var{label})(a5)     // R_RISCV_PCREL_LO12_I
+@end smallexample
+
+@item %tls_gd_pcrel_hi(@var{symbol})
+The high 20 bits of relative address between pc and GOT entry.  It is
+usually used with the %pcrel_lo modifier to access the thread local variable
+@var{symbol} in TLS Global Dynamic.
+
+@smallexample
+       la.tls.gd  a0, @var{symbol}
+       call       __tls_get_addr@@plt
+       mv         a5, a0
+       load/store t0, 0(a5)
+@end smallexample
+
+The pseudo la.tls.gd instruction can be expended to
+
+@smallexample
+@var{label}:
+       auipc a0, %tls_gd_pcrel_hi(@var{symbol}) // R_RISCV_TLS_GD_HI20
+       addi  a0, a0, %pcrel_lo(@var{label})     // R_RISCV_PCREL_LO12_I
+@end smallexample
+
+@end table
+
 @node RISC-V-Formats
-@section Instruction Formats
+@section RISC-V Instruction Formats
 @cindex instruction formats, risc-v
 @cindex RISC-V instruction formats