Update and clean up RISC-V gas documentation.

	gas/
	* doc/as.texinfo (RISC-V): Alphabetize RISC-V entries.  Change
	RISC-V-Opts to RISC-V-Options.  Delete redundant space.  Add -fpic
	and related options to option list.
	* doc/c-riscv.texi: (RISC-V-Options): Renamed from RISC-V-Opts.
	(RISC-V Options): Renamed from Options.  Add missing period.
	(-fpic): Also mention -fPIC.
	(RISC-V Directives): New node.

2 files changed, 123 insertions, 19 deletions

diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
index d37a1d633f0..faa228dab36 100644
--- a/gas/doc/as.texinfo
+++ b/gas/doc/as.texinfo
@@ -502,6 +502,13 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
    [@b{-mnolink-relax}]
    [@b{-mno-warn-regname-label}]
 @end ifset
+@ifset RISCV
+
+@emph{Target RISC-V options:}
+   [@b{-fpic}|@b{-fPIC}|@b{-fno-pic}]
+   [@b{-march}=@var{ISA}]
+   [@b{-mabi}=@var{ABI}]
+@end ifset
 @ifset RL78
 
 @emph{Target RL78 options:}
@@ -520,12 +527,6 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
    [@b{-mint-register=@var{number}}]
    [@b{-mgcc-abi}|@b{-mrx-abi}]
 @end ifset
-@ifset RISCV
-
-@emph{Target RISC-V options:}
-   [@b{-march}=@var{ISA}]
-   [@b{-mabi}=@var{ABI}]
-@end ifset
 @ifset S390
 
 @emph{Target s390 options:}
@@ -1702,14 +1703,14 @@ PowerPC processor.
 @ifset RISCV
 
 @ifclear man
-@xref{RISC-V-Opts}, for the options available when @value{AS} is configured
+@xref{RISC-V-Options}, for the options available when @value{AS} is configured
 for a RISC-V processor.
 @end ifclear
 
 @ifset man
 @c man begin OPTIONS
 The following options are available when @value{AS} is configured for a
-RISC-V  processor.
+RISC-V processor.
 @c man end
 @c man begin INCLUDE
 @include c-riscv.texi
@@ -7710,12 +7711,12 @@ subject, see the hardware manufacturer's manual.
 @ifset PRU
 * PRU-Dependent::               PRU Dependent Features
 @end ifset
-@ifset RL78
-* RL78-Dependent::              RL78 Dependent Features
-@end ifset
 @ifset RISCV
 * RISC-V-Dependent::            RISC-V Dependent Features
 @end ifset
+@ifset RL78
+* RL78-Dependent::              RL78 Dependent Features
+@end ifset
 @ifset RX
 * RX-Dependent::                RX Dependent Features
 @end ifset
@@ -7946,14 +7947,14 @@ family.
 @include c-pru.texi
 @end ifset
 
-@ifset RL78
-@include c-rl78.texi
-@end ifset
-
 @ifset RISCV
 @include c-riscv.texi
 @end ifset
 
+@ifset RL78
+@include c-rl78.texi
+@end ifset
+
 @ifset RX
 @include c-rx.texi
 @end ifset
diff --git a/gas/doc/c-riscv.texi b/gas/doc/c-riscv.texi
index 01b99312d3c..8d3a0b1312c 100644
--- a/gas/doc/c-riscv.texi
+++ b/gas/doc/c-riscv.texi
@@ -15,19 +15,21 @@
 
 @cindex RISC-V support
 @menu
-* RISC-V-Opts::      RISC-V Options
+* RISC-V-Options::        RISC-V Options
+* RISC-V-Directives::     RISC-V Directives
 @end menu
 
-@node RISC-V-Opts
-@section Options
+@node RISC-V-Options
+@section RISC-V Options
 
-The following table lists all available RISC-V specific options
+The following table lists all available RISC-V specific options.
 
 @c man begin OPTIONS
 @table @gcctabopt
 
 @cindex @samp{-fpic} option, RISC-V
 @item -fpic
+@itemx -fPIC
 Generate position-independent code
 
 @cindex @samp{-fno-pic} option, RISC-V
@@ -47,3 +49,104 @@ the soft-float calling convention.
 
 @end table
 @c man end
+
+@node RISC-V-Directives
+@cindex machine directives, RISC-V
+@cindex RISC-V machine directives
+
+@section RISC-V Directives
+
+The following table lists all available RISC-V specific directives.
+
+@table @code
+
+@cindex @code{align} directive
+@item .align @var{size-log-2}
+Align to the given boundary, with the size given as log2 the number of bytes to
+align to.
+
+@cindex Data directives
+@item .half @var{value}
+@itemx .word @var{value}
+@itemx .dword @var{value}
+Emits a half-word, word, or double-word value at the current position.
+
+@cindex DTP-relative data directives
+@item .dtprelword @var{value}
+@itemx .dtpreldword @var{value}
+Emits a DTP-relative word (or double-word) at the current position.  This is
+meant to be used by the compiler in shared libraries for DWARF debug info for
+thread local variables.
+
+@cindex BSS directive
+@item .bss
+Sets the current section to the BSS section.
+
+@cindex LEB128 directives
+@item .uleb128 @var{value}
+@itemx .sleb128 @var{value}
+Emits a signed or unsigned LEB128 value at the current position.  This only
+accepts constant expressions, because symbol addresses can change with
+relaxation, and we don't support relocations to modify LEB128 values at link
+time.
+
+@cindex Option directive
+@cindex @code{option} directive
+@item .option @var{argument}
+Modifies RISC-V specific assembler options inline with the assembly code.
+This is used when particular instruction sequences must be assembled with a
+specific set of options.  For example, since we relax addressing sequences to
+shorter GP-relative sequences when possible the initial load of GP must not be
+relaxed and should be emitted as something like
+
+@smallexample
+	.option push
+	.option norelax
+	la gp, __global_pointer$
+	.option pop
+@end smallexample
+
+in order to produce after linker relaxation the expected
+
+@smallexample
+	auipc gp, %pcrel_hi(__global_pointer$)
+	addi gp, gp, %pcrel_lo(__global_pointer$)
+@end smallexample
+
+instead of just
+
+@smallexample
+	addi gp, gp, 0
+@end smallexample
+
+It's not expected that options are changed in this manner during regular use,
+but there are a handful of esoteric cases like the one above where users need
+to disable particular features of the assembler for particular code sequences.
+The complete list of option arguments is shown below:
+
+@table @code
+@item push
+@itemx pop
+Pushes or pops the current option stack.  These should be used whenever
+changing an option in line with assembly code in order to ensure the user's
+command-line options are respected for the bulk of the file being assembled.
+
+@item rvc
+@itemx norvc
+Enables or disables the generation of compressed instructions.  Instructions
+are opportunistically compressed by the RISC-V assembler when possible, but
+sometimes this behavior is not desirable.
+
+@item pic
+@itemx nopic
+Enables or disables position-independent code generation.  Unless you really
+know what you're doing, this should only be at the top of a file.
+
+@item relax
+@itemx norelax
+Enables or disables relaxation.  The RISC-V assembler and linker
+opportunistically relax some code sequences, but sometimes this behavior is not
+desirable.
+@end table
+
+@end table