From b57e49f726f854e65b2ce5e87dc7ee664daac1fb Mon Sep 17 00:00:00 2001 From: Jim Wilson Date: Fri, 1 Dec 2017 15:34:42 -0800 Subject: [PATCH] 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. --- gas/ChangeLog | 11 +++++ gas/doc/as.texinfo | 31 ++++++------ gas/doc/c-riscv.texi | 111 +++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 134 insertions(+), 19 deletions(-) diff --git a/gas/ChangeLog b/gas/ChangeLog index 19e13d60195..8aa5e541c9e 100644 --- a/gas/ChangeLog +++ b/gas/ChangeLog @@ -1,3 +1,14 @@ +2017-12-01 Palmer Dabbelt + Jim Wilson + + * 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. + 2017-12-01 Peter Bergner * config/tc-ppc.c (last_insn): Update type. 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 -- 2.30.2