[PATCH] Update and clean up RISC-V gas documentation.

[PATCH] Update and clean up RISC-V gas documentation.

[Jim Wilson]

This adds gas documentation for RISC-V directives, and also does some various
other clean ups of RISC-V gas documentation.

Tested by generating as.1 and as.info files and viewing them with man and info
to ensure that they are OK.  Committed.

	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.
---
 gas/doc/as.texinfo   |  31 +++++++-------
 gas/doc/c-riscv.texi | 111 +++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 123 insertions(+), 19 deletions(-)

diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
index d37a1d633f..faa228dab3 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 01b99312d3..8d3a0b1312 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
-- 
2.14.1

Re: [PATCH] Update and clean up RISC-V gas documentation.

[Ulrich Weigand]

Jim Wilson wrote:

> 	(RISC-V Directives): New node.

This now causes build failures on my Cell daily build system (GNU texinfo 4.8):

c-riscv.texi:53: Node `RISC-V-Directives' requires a sectioning command (e.g., @unnumberedsubsubsec).
c-riscv.texi:53: `RISC-V-Directives' has no Up field (perhaps incorrect sectioning?).
c-riscv.texi:22: Next field of node `RISC-V-Options' not pointed to (perhaps incorrect sectioning?).
c-riscv.texi:53: This node (RISC-V-Directives) has the bad Prev.

Bye,
Ulrich

-- 
  Dr. Ulrich Weigand
  GNU/Linux compilers and toolchain
  Ulrich.Weigand@de.ibm.com

[PATCH] Fix for texinfo 4.8.

[Jim Wilson]

Texinfo 4.8 is 12 years old.  I had to download and build a copy to check.
Turns out that the older version requires the @section immediately after the
@node, where as current versions allow @cindex in between.  This is easy to
fix.  Committed.

	gas/
	* doc/c-riscv.texi (RISC-V-Directives): Move @section immediately after
	@node.
---
 gas/doc/c-riscv.texi | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/gas/doc/c-riscv.texi b/gas/doc/c-riscv.texi
index 8d3a0b1312..90e6be7c4c 100644
--- a/gas/doc/c-riscv.texi
+++ b/gas/doc/c-riscv.texi
@@ -51,11 +51,10 @@ the soft-float calling convention.
 @c man end
 
 @node RISC-V-Directives
+@section 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
-- 
2.14.1

Re: [PATCH] Fix for texinfo 4.8.

[Ulrich Weigand]

Jim Wilson wrote:

> Texinfo 4.8 is 12 years old.  I had to download and build a copy to check.
> Turns out that the older version requires the @section immediately after the
> @node, where as current versions allow @cindex in between.  This is easy to
> fix.  Committed.
> 
> 	gas/
> 	* doc/c-riscv.texi (RISC-V-Directives): Move @section immediately after
> 	@node.

Yes, this fixes the problem for me.

Thanks,
Ulrich

-- 
  Dr. Ulrich Weigand
  GNU/Linux compilers and toolchain
  Ulrich.Weigand@de.ibm.com