\input texinfo @c -*-Texinfo-*-
-@c Copyright (C) 1991-2016 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2017 Free Software Foundation, Inc.
@c UPDATE!! On future updates--
@c (1) check for new machine-dep cmdline options in
@c md_parse_option definitions in config/tc-*.c
This file documents the GNU Assembler "@value{AS}".
@c man begin COPYRIGHT
-Copyright @copyright{} 1991-2016 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2017 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1991-2016 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2017 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
[@b{-K}] [@b{-L}] [@b{--listing-lhs-width}=@var{NUM}]
[@b{--listing-lhs-width2}=@var{NUM}] [@b{--listing-rhs-width}=@var{NUM}]
[@b{--listing-cont-lines}=@var{NUM}] [@b{--keep-locals}]
+ [@b{--no-pad-sections}]
[@b{-o} @var{objfile}] [@b{-R}]
[@b{--hash-size}=@var{NUM}] [@b{--reduce-memory-overheads}]
[@b{--statistics}]
[@b{--target-help}] [@var{target-options}]
[@b{--}|@var{files} @dots{}]
@c
+@c man end
@c Target dependent options are listed below. Keep the list sorted.
@c Add an empty line for separation.
+@c man begin TARGET
@ifset AARCH64
@emph{Target AArch64 options:}
[@b{-mips32r3}] [@b{-mips32r5}] [@b{-mips32r6}] [@b{-mips64}] [@b{-mips64r2}]
[@b{-mips64r3}] [@b{-mips64r5}] [@b{-mips64r6}]
[@b{-construct-floats}] [@b{-no-construct-floats}]
+ [@b{-mignore-branch-isa}] [@b{-mno-ignore-branch-isa}]
[@b{-mnan=@var{encoding}}]
[@b{-trap}] [@b{-no-break}] [@b{-break}] [@b{-no-trap}]
[@b{-mips16}] [@b{-no-mips16}]
[@b{-mdmx}] [@b{-no-mdmx}]
[@b{-mdsp}] [@b{-mno-dsp}]
[@b{-mdspr2}] [@b{-mno-dspr2}]
+ [@b{-mdspr3}] [@b{-mno-dspr3}]
[@b{-mmsa}] [@b{-mno-msa}]
[@b{-mxpa}] [@b{-mno-xpa}]
[@b{-mmt}] [@b{-mno-mt}]
[@b{-msolaris}|@b{-mno-solaris}]
[@b{-nops=@var{count}}]
@end ifset
+@ifset PRU
+
+@emph{Target PRU options:}
+ [@b{-link-relax}]
+ [@b{-mnolink-relax}]
+ [@b{-mno-warn-regname-label}]
+@end ifset
@ifset RL78
@emph{Target RL78 options:}
[@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:}
@emph{Target SPARC options:}
@c The order here is important. See c-sparc.texi.
- [@b{-Av6}|@b{-Av7}|@b{-Av8}|@b{-Asparclet}|@b{-Asparclite}
- @b{-Av8plus}|@b{-Av8plusa}|@b{-Av9}|@b{-Av9a}]
- [@b{-xarch=v8plus}|@b{-xarch=v8plusa}] [@b{-bump}]
+ [@b{-Av6}|@b{-Av7}|@b{-Av8}|@b{-Aleon}|@b{-Asparclet}|@b{-Asparclite}
+ @b{-Av8plus}|@b{-Av8plusa}|@b{-Av8plusb}|@b{-Av8plusc}|@b{-Av8plusd}
+ @b{-Av8plusv}|@b{-Av8plusm}|@b{-Av9}|@b{-Av9a}|@b{-Av9b}|@b{-Av9c}
+ @b{-Av9d}|@b{-Av9e}|@b{-Av9v}|@b{-Av9m}|@b{-Asparc}|@b{-Asparcvis}
+ @b{-Asparcvis2}|@b{-Asparcfmaf}|@b{-Asparcima}|@b{-Asparcvis3}
+ @b{-Asparcvisr}|@b{-Asparc5}]
+ [@b{-xarch=v8plus}|@b{-xarch=v8plusa}]|@b{-xarch=v8plusb}|@b{-xarch=v8plusc}
+ @b{-xarch=v8plusd}|@b{-xarch=v8plusv}|@b{-xarch=v8plusm}|@b{-xarch=v9}
+ @b{-xarch=v9a}|@b{-xarch=v9b}|@b{-xarch=v9c}|@b{-xarch=v9d}|@b{-xarch=v9e}
+ @b{-xarch=v9v}|@b{-xarch=v9m}|@b{-xarch=sparc}|@b{-xarch=sparcvis}
+ @b{-xarch=sparcvis2}|@b{-xarch=sparcfmaf}|@b{-xarch=sparcima}
+ @b{-xarch=sparcvis3}|@b{-xarch=sparcvisr}|@b{-xarch=sparc5}
+ @b{-bump}]
[@b{-32}|@b{-64}]
+ [@b{--enforce-aligned-data}][@b{--dcti-couples-detect}]
@end ifset
@ifset TIC54X
Set the maximum number of lines printed in a listing for a single line of input
to @var{number} + 1.
+@item --no-pad-sections
+Stop the assembler for padding the ends of output sections to the alignment
+of that section. The default is to pad the sections, but this can waste space
+which might be needed on targets which have tight memory constraints.
+
@item -o @var{objfile}
Name the object-file output from @command{@value{AS}} @var{objfile}.
@end table
@end ifset
+@ifset PRU
+
+@ifclear man
+@xref{PRU Options}, for the options available when @value{AS} is configured
+for a PRU processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for a
+PRU processor.
+@c man end
+@c man begin INCLUDE
+@include c-pru.texi
+@c ended inside the included file
+@end ifset
+@end ifset
+
@ifset M68HC11
The following options are available when @value{AS} is configured for the
Motorola 68HC11 or 68HC12 series.
@end ifset
@ifset MIPS
+@c man begin OPTIONS
The following options are available when @value{AS} is configured for
a MIPS processor.
@item -mdspr2
@itemx -mno-dspr2
Generate code for the DSP Release 2 Application Specific Extension.
-This option implies -mdsp.
+This option implies @samp{-mdsp}.
This tells the assembler to accept DSP Release 2 instructions.
@samp{-mno-dspr2} turns off this option.
+@item -mdspr3
+@itemx -mno-dspr3
+Generate code for the DSP Release 3 Application Specific Extension.
+This option implies @samp{-mdsp} and @samp{-mdspr2}.
+This tells the assembler to accept DSP Release 3 instructions.
+@samp{-mno-dspr3} turns off this option.
+
@item -mmsa
@itemx -mno-msa
Generate code for the MIPS SIMD Architecture Extension.
branches. By default @samp{--no-relax-branch} is selected, causing any
out-of-range branches to produce an error.
+@item -mignore-branch-isa
+@itemx -mno-ignore-branch-isa
+Ignore branch checks for invalid transitions between ISA modes. The
+semantics of branches does not provide for an ISA mode switch, so in
+most cases the ISA mode a branch has been encoded for has to be the
+same as the ISA mode of the branch's target label. Therefore GAS has
+checks implemented that verify in branch assembly that the two ISA
+modes match. @samp{-mignore-branch-isa} disables these checks. By
+default @samp{-mno-ignore-branch-isa} is selected, causing any invalid
+branch requiring a transition between ISA modes to produce an error.
+
@item -mnan=@var{encoding}
Select between the IEEE 754-2008 (@option{-mnan=2008}) or the legacy
(@option{-mnan=legacy}) NaN encoding format. The latter is the default.
When this option is used, @command{@value{AS}} will issue a warning every
time it generates a nop instruction from a macro.
@end table
+@c man end
@end ifset
@ifset MCORE
@end ifset
+@ifset RISCV
+
+@ifclear man
+@xref{RISC-V-Opts}, 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.
+@c man end
+@c man begin INCLUDE
+@include c-riscv.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
@c man begin OPTIONS
@ifset RX
See the info pages for documentation of the RX-specific options.
Select the architecture mode, either the Enterprise System
Architecture (esa) or the z/Architecture mode (zarch).
@item -march=@var{processor}
-Specify which s390 processor variant is the target, @samp{g6}, @samp{g6},
-@samp{z900}, @samp{z990}, @samp{z9-109}, @samp{z9-ec}, @samp{z10},
-@samp{z196}, @samp{zEC12}, or @samp{z13}.
+Specify which s390 processor variant is the target, @samp{g5} (or
+@samp{arch3}), @samp{g6}, @samp{z900} (or @samp{arch5}), @samp{z990} (or
+@samp{arch6}), @samp{z9-109}, @samp{z9-ec} (or @samp{arch7}), @samp{z10} (or
+@samp{arch8}), @samp{z196} (or @samp{arch9}), @samp{zEC12} (or @samp{arch10}),
+@samp{z13} (or @samp{arch11}), or @samp{arch12}.
@item -mregnames
@itemx -mno-regnames
Allow or disallow symbolic names for registers.
* listing:: --listing-XXX to configure listing output
* M:: -M or --mri to assemble in MRI compatibility mode
* MD:: --MD for dependency tracking
+* no-pad-sections:: --no-pad-sections to stop section padding
* o:: -o to name the object file
* R:: -R to join data and text sections
* statistics:: --statistics to see statistics about assembly
This feature is used in the automatic updating of makefiles.
+@node no-pad-sections
+@section Output Section Padding
+@kindex --no-pad-sections
+@cindex output section padding
+Normally the assembler will pad the end of each output section up to its
+alignment boundary. But this can waste space, which can be significant on
+memory constrained targets. So the @option{--no-pad-sections} option will
+disable this behaviour.
+
@node o
@section Name the Object File: @option{-o}
(@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver
to get other ``CPP'' style preprocessing by giving the input file a
@samp{.S} suffix. @xref{Overall Options, ,Options Controlling the Kind of
-Output, gcc.info, Using GNU CC}.
+Output, gcc info, Using GNU CC}.
Excess whitespace, comments, and character constants
cannot be used in the portions of the input text that are not
@cindex single character constant
@cindex character, single
@cindex constant, single character
-A single character may be written as a single quote immediately
-followed by that character. The same escapes apply to characters as
-to strings. So if you want to write the character backslash, you
-must write @kbd{'\\} where the first @code{\} escapes the second
-@code{\}. As you can see, the quote is an acute accent, not a
-grave accent. A newline
+A single character may be written as a single quote immediately followed by
+that character. Some backslash escapes apply to characters, @code{\b},
+@code{\f}, @code{\n}, @code{\r}, @code{\t}, and @code{\"} with the same meaning
+as for strings, plus @code{\'} for a single quote. So if you want to write the
+character backslash, you must write @kbd{'\\} where the first @code{\} escapes
+the second @code{\}. As you can see, the quote is an acute accent, not a grave
+accent. A newline
@ifclear GENERIC
@ifclear abnormal-separator
(or semicolon @samp{;})
@ifclear no-space-dir
* Zero:: @code{.zero @var{size}}
@end ifclear
+@ifset ELF
+* 2byte:: @code{.2byte @var{expressions}}
+* 4byte:: @code{.4byte @var{expressions}}
+* 8byte:: @code{.8byte @var{bignums}}
+@end ifset
* Deprecated:: Deprecated Directives
@end menu
@subsection @code{.cfi_adjust_cfa_offset @var{offset}}
Same as @code{.cfi_def_cfa_offset} but @var{offset} is a relative
-value that is added/substracted from the previous offset.
+value that is added/subtracted from the previous offset.
@subsection @code{.cfi_offset @var{register}, @var{offset}}
Previous value of @var{register} is saved at offset @var{offset} from
CFA.
+@subsection @code{.cfi_val_offset @var{register}, @var{offset}}
+Previous value of @var{register} is CFA + @var{offset}.
+
@subsection @code{.cfi_rel_offset @var{register}, @var{offset}}
Previous value of @var{register} is saved at offset @var{offset} from
the current CFA register. This is transformed to @code{.cfi_offset}
Current value of @var{register} is the same like in the previous frame,
i.e. no restoration needed.
-@subsection @code{.cfi_remember_state},
-First save all current rules for all registers by @code{.cfi_remember_state},
-then totally screw them up by subsequent @code{.cfi_*} directives and when
-everything is hopelessly bad, use @code{.cfi_restore_state} to restore
-the previous saved state.
+@subsection @code{.cfi_remember_state} and @code{.cfi_restore_state}
+@code{.cfi_remember_state} pushes the set of rules for every register onto an
+implicit stack, while @code{.cfi_restore_state} pops them off the stack and
+places them in the current row. This is useful for situations where you have
+multiple @code{.cfi_*} directives that need to be undone due to the control
+flow of the program. For example, we could have something like this (assuming
+the CFA is the value of @code{rbp}):
+
+@smallexample
+ je label
+ popq %rbx
+ .cfi_restore %rbx
+ popq %r12
+ .cfi_restore %r12
+ popq %rbp
+ .cfi_restore %rbp
+ .cfi_def_cfa %rsp, 8
+ ret
+label:
+ /* Do something else */
+@end smallexample
+
+Here, we want the @code{.cfi} directives to affect only the rows corresponding
+to the instructions before @code{label}. This means we'd have to add multiple
+@code{.cfi} directives after @code{label} to recreate the original save
+locations of the registers, as well as setting the CFA back to the value of
+@code{rbp}. This would be clumsy, and result in a larger binary size. Instead,
+we can write:
+
+@smallexample
+ je label
+ popq %rbx
+ .cfi_remember_state
+ .cfi_restore %rbx
+ popq %r12
+ .cfi_restore %r12
+ popq %rbp
+ .cfi_restore %rbp
+ .cfi_def_cfa %rsp, 8
+ ret
+label:
+ .cfi_restore_state
+ /* Do something else */
+@end smallexample
+
+That way, the rules for the instructions after @code{label} will be the same
+as before the first @code{.cfi_restore} without having to use multiple
+@code{.cfi} directives.
@subsection @code{.cfi_return_column @var{register}}
Change return column @var{register}, i.e. the return address is either
@ifset Z80
The syntax for @code{equ} on the Z80 is
@samp{@var{symbol} equ @var{expression}}.
-On the Z80 it is an eror if @var{symbol} is already defined,
+On the Z80 it is an error if @var{symbol} is already defined,
but the symbol is not protected from later redefinition.
Compare @ref{Equiv}.
@end ifset
The two @code{exception_code} invocations above would create the
@code{.text.exception} and @code{.init.exception} sections respectively.
-This is useful e.g. to discriminate between anciliary sections that are
-tied to setup code to be discarded after use from anciliary sections that
+This is useful e.g. to discriminate between ancillary sections that are
+tied to setup code to be discarded after use from ancillary sections that
need to stay resident without having to define multiple @code{exception_code}
macros just for that purpose.
@item STT_TLS
@itemx tls_object
-Mark the symbol as being a thead-local data object.
+Mark the symbol as being a thread-local data object.
@item STT_COMMON
@itemx common
instead of zero. Using @samp{.zero} in this way would be confusing however.
@end ifclear
+@ifset ELF
+@node 2byte
+@section @code{.2byte @var{expression} [, @var{expression}]*}
+@cindex @code{2byte} directive
+@cindex two-byte integer
+@cindex integer, 2-byte
+
+This directive expects zero or more expressions, separated by commas. If there
+are no expressions then the directive does nothing. Otherwise each expression
+is evaluated in turn and placed in the next two bytes of the current output
+section, using the endian model of the target. If an expression will not fit
+in two bytes, a warning message is displayed and the least significant two
+bytes of the expression's value are used. If an expression cannot be evaluated
+at assembly time then relocations will be generated in order to compute the
+value at link time.
+
+This directive does not apply any alignment before or after inserting the
+values. As a result of this, if relocations are generated, they may be
+different from those used for inserting values with a guaranteed alignment.
+
+This directive is only available for ELF targets,
+
+@node 4byte
+@section @code{.4byte @var{expression} [, @var{expression}]*}
+@cindex @code{4byte} directive
+@cindex four-byte integer
+@cindex integer, 4-byte
+
+Like the @option{.2byte} directive, except that it inserts unaligned, four byte
+long values into the output.
+
+@node 8byte
+@section @code{.8byte @var{expression} [, @var{expression}]*}
+@cindex @code{8byte} directive
+@cindex eight-byte integer
+@cindex integer, 8-byte
+
+Like the @option{.8byte} directive, except that it inserts unaligned, eight
+byte long bignum values into the output.
+
+@end ifset
+
@node Deprecated
@section Deprecated Directives
@ifset PPC
* PPC-Dependent:: PowerPC Dependent Features
@end ifset
+@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 RX
* RX-Dependent:: RX Dependent Features
@end ifset
@ifset VISIUM
* Visium-Dependent:: Visium Dependent Features
@end ifset
+@ifset WASM32
+* WebAssembly-Dependent:: WebAssembly Dependent Features
+@end ifset
@ifset XGATE
-* XGATE-Dependent:: XGATE Features
+* XGATE-Dependent:: XGATE Dependent Features
@end ifset
@ifset XSTORMY16
* XSTORMY16-Dependent:: XStormy16 Dependent Features
@include c-ppc.texi
@end ifset
+@ifset PRU
+@include c-pru.texi
+@end ifset
+
@ifset RL78
@include c-rl78.texi
@end ifset
+@ifset RISCV
+@include c-riscv.texi
+@end ifset
+
@ifset RX
@include c-rx.texi
@end ifset
@include c-visium.texi
@end ifset
+@ifset WASM32
+@include c-wasm32.texi
+@end ifset
+
@ifset XGATE
@include c-xgate.texi
@end ifset
projects / deliverable / binutils-gdb.git / blobdiff