@c to be limited to one line for the header.
@smallexample
@c man begin SYNOPSIS
-@value{AS} [@b{-a}[@b{cdhlns}][=@var{file}]] [@b{-D}] [@b{--defsym} @var{sym}=@var{val}]
- [@b{-f}] [@b{--gstabs}] [@b{--gstabs+}] [@b{--gdwarf2}] [@b{--help}]
- [@b{-I} @var{dir}] [@b{-J}] [@b{-K}] [@b{-L}]
+@value{AS} [@b{-a}[@b{cdhlns}][=@var{file}]] [@b{--alternate}] [@b{-D}]
+ [@b{--defsym} @var{sym}=@var{val}] [@b{-f}] [@b{-g}] [@b{--gstabs}] [@b{--gstabs+}]
+ [@b{--gdwarf-2}] [@b{--help}] [@b{-I} @var{dir}] [@b{-J}] [@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{-o} @var{objfile}] [@b{-R}] [@b{--statistics}] [@b{-v}]
[@b{-EB}|@b{-EL}]
[@b{-mapcs-32}|@b{-mapcs-26}|@b{-mapcs-float}|
@b{-mapcs-reentrant}]
- [@b{-mthumb-interwork}] [@b{-moabi}] [@b{-k}]
+ [@b{-mthumb-interwork}] [@b{-k}]
@end ifset
@ifset CRIS
[@b{--underscore} | @b{--no-underscore}]
[@b{--pic}] [@b{-N}]
[@b{--emulation=criself} | @b{--emulation=crisaout}]
+ [@b{--march=v0_v10} | @b{--march=v10} | @b{--march=v32} | @b{--march=common_v10_v32}]
@c Deprecated -- deliberately not documented.
@c [@b{-h}] [@b{-H}]
@end ifset
[@b{-mconstant-gp}|@b{-mauto-pic}]
[@b{-milp32}|@b{-milp64}|@b{-mlp64}|@b{-mp64}]
[@b{-mle}|@b{mbe}]
+ [@b{-munwind-check=warning}|@b{-munwind-check=error}]
[@b{-x}|@b{-xexplicit}] [@b{-xauto}] [@b{-xdebug}]
@end ifset
@ifset IP2K
@ifset XTENSA
@emph{Target Xtensa options:}
- [@b{--[no-]density}] [@b{--[no-]relax}] [@b{--[no-]generics}]
- [@b{--[no-]text-section-literals}]
+ [@b{--[no-]text-section-literals}] [@b{--[no-]absolute-literals}]
[@b{--[no-]target-align}] [@b{--[no-]longcalls}]
+ [@b{--[no-]transform}]
+ [@b{--rename-section} @var{oldname}=@var{newname}]
@end ifset
@c man end
@end smallexample
listing without forms processing. The @samp{=file} option, if used, must be
the last one. By itself, @samp{-a} defaults to @samp{-ahls}.
+@item --alternate
+Begin in alternate macro mode, see @ref{Altmacro,,@code{.altmacro}}.
+
@item -D
Ignored. This option is accepted for script compatibility with calls to
other assemblers.
``fast''---skip whitespace and comment preprocessing (assume source is
compiler output).
+@item -g
+@itemx --gen-debug
+Generate debugging information for each assembler source line using whichever
+debug format is preferred by the target. This currently means either STABS,
+ECOFF or DWARF2.
+
@item --gstabs
Generate stabs debugging information for each assembler line. This
may help debugging assembler code, if the debugger can handle it.
may help debugging assembler code. Currently the only GNU extension is
the location of the current working directory at assembling time.
-@item --gdwarf2
+@item --gdwarf-2
Generate DWARF2 debugging information for each assembler line. This
may help debugging assembler code, if the debugger can handle it. Note---this
option is only supported by some targets, not all of them.
Select which floating point ABI is in use.
@item -mthumb
Enable Thumb only instruction decoding.
-@item -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant | -moabi
+@item -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant
Select which procedure calling convention is in use.
@item -EB | -EL
Select either big-endian (-EB) or little-endian (-EL) output.
an Xtensa processor.
@table @gcctabopt
-@item --density | --no-density
-Enable or disable use of instructions from the Xtensa code density
-option. This is enabled by default when the Xtensa processor supports
-the code density option.
-
-@item --relax | --no-relax
-Enable or disable instruction relaxation. This is enabled by default.
-Note: In the current implementation, these options also control whether
-assembler optimizations are performed, making these options equivalent
-to @option{--generics} and @option{--no-generics}.
-
-@item --generics | --no-generics
-Enable or disable all assembler transformations of Xtensa instructions.
-The default is @option{--generics};
-@option{--no-generics} should be used only in the rare cases when the
-instructions must be exactly as specified in the assembly source.
-
@item --text-section-literals | --no-text-section-literals
With @option{--text-@-section-@-literals}, literal pools are interspersed
in the text section. The default is
@option{--no-@-text-@-section-@-literals}, which places literals in a
-separate section in the output file.
+separate section in the output file. These options only affect literals
+referenced via PC-relative @code{L32R} instructions; literals for
+absolute mode @code{L32R} instructions are handled separately.
+
+@item --absolute-literals | --no-absolute-literals
+Indicate to the assembler whether @code{L32R} instructions use absolute
+or PC-relative addressing. The default is to assume absolute addressing
+if the Xtensa processor includes the absolute @code{L32R} addressing
+option. Otherwise, only the PC-relative @code{L32R} mode can be used.
@item --target-align | --no-target-align
Enable or disable automatic alignment to reduce branch penalties at the
Enable or disable transformation of call instructions to allow calls
across a greater range of addresses. The default is
@option{--no-@-longcalls}.
+
+@item --transform | --no-transform
+Enable or disable all assembler transformations of Xtensa instructions.
+The default is @option{--transform};
+@option{--no-transform} should be used only in the rare cases when the
+instructions must be exactly as specified in the assembly source.
@end table
@end ifset
@menu
* a:: -a[cdhlns] enable listings
+* alternate:: --alternate enable alternate macro syntax
* D:: -D for compatibility
* f:: -f to work faster
* I:: -I for .include search path
stdin only after they have been preprocessed by the assembler. This reduces
memory usage and makes the code more efficient.
+@node alternate
+@section @option{--alternate}
+
+@kindex --alternate
+Begin in alternate macro mode, see @ref{Altmacro,,@code{.altmacro}}.
+
@node D
@section @option{-D}
@cindex auxiliary attributes, COFF symbols
The @command{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
-@code{.size}, and @code{.tag} can generate auxiliary symbol table
-information for COFF.
+@code{.size}, @code{.tag}, and @code{.weak} can generate auxiliary symbol
+table information for COFF.
@end ifset
@ifset SOM
@end ifset
* Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
+* Altmacro:: @code{.altmacro}
* Ascii:: @code{.ascii "@var{string}"}@dots{}
* Asciz:: @code{.asciz "@var{string}"}@dots{}
* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}}
* Equ:: @code{.equ @var{symbol}, @var{expression}}
* Equiv:: @code{.equiv @var{symbol}, @var{expression}}
* Err:: @code{.err}
+* Error:: @code{.error @var{string}}
* Exitm:: @code{.exitm}
* Extern:: @code{.extern}
* Fail:: @code{.fail}
* Macro:: @code{.macro @var{name} @var{args}}@dots{}
* MRI:: @code{.mri @var{val}}
+* Noaltmacro:: @code{.noaltmacro}
* Nolist:: @code{.nolist}
* Octa:: @code{.octa @var{bignums}}
* Org:: @code{.org @var{new-lc} , @var{fill}}
* Version:: @code{.version "@var{string}"}
* VTableEntry:: @code{.vtable_entry @var{table}, @var{offset}}
* VTableInherit:: @code{.vtable_inherit @var{child}, @var{parent}}
-* Weak:: @code{.weak @var{names}}
@end ifset
+* Warning:: @code{.warning @var{string}}
+* Weak:: @code{.weak @var{names}}
* Word:: @code{.word @var{expressions}}
* Deprecated:: Deprecated Directives
@end menu
message and, unless the @option{-Z} option was used, it will not generate an
object file. This can be used to signal error an conditionally compiled code.
+@node Error
+@section @code{.error "@var{string}"}
+@cindex error directive
+
+Similarly to @code{.err}, this directive emits an error, but you can specify a
+string that will be emitted as the error message. If you don't specify the
+message, it defaults to @code{".error directive invoked in source file"}.
+@xref{Errors, ,Error and Warning Messages}.
+
+@smallexample
+ .error "This code has not been assembled and tested."
+@end smallexample
+
@node Exitm
@section @code{.exitm}
Exit early from the current macro definition. @xref{Macro}.
executed in this pseudo-variable; you can copy that number to your
output with @samp{\@@}, but @emph{only within a macro definition}.
-@ignore
@item LOCAL @var{name} [ , @dots{} ]
@emph{Warning: @code{LOCAL} is only available if you select ``alternate
-macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,,
-Alternate macro syntax}.
+macro syntax'' with @samp{--alternate} or @code{.altmacro}.}
+@xref{Altmacro,,@code{.altmacro}}.
+@end ftable
+
+@node Altmacro
+@section @code{.altmacro}
+Enable alternate macro mode, enabling:
-Generate a string replacement for each of the @var{name} arguments, and
+@ftable @code
+@item LOCAL @var{name} [ , @dots{} ]
+One additional directive, @code{LOCAL}, is available. It is used to
+generate a string replacement for each of the @var{name} arguments, and
replace any instances of @var{name} in each macro expansion. The
replacement string is unique in the assembly, and different for each
separate macro expansion. @code{LOCAL} allows you to write macros that
define symbols, without fear of conflict between separate macro expansions.
-@end ignore
+
+@item String delimiters
+You can write strings delimited in these other ways besides
+@code{"@var{string}"}:
+
+@table @code
+@item '@var{string}'
+You can delimit strings with single-quote charaters.
+
+@item <@var{string}>
+You can delimit strings with matching angle brackets.
+@end table
+
+@item single-character string escape
+To include any single character literally in a string (even if the
+character would otherwise have some special meaning), you can prefix the
+character with @samp{!} (an exclamation mark). For example, you can
+write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}.
+
+@item Expression results as strings
+You can write @samp{%@var{expr}} to evaluate the expression @var{expr}
+and use the result as a string.
@end ftable
+@node Noaltmacro
+@section @code{.noaltmacro}
+Disable alternate macro mode. @ref{Altmacro}
+
@node Nolist
@section @code{.nolist}
@code{.popsection} (@pxref{PopSection}), and @code{.previous}
(@pxref{Previous}).
-This directive is a synonym for @code{.section}. It pushes the current section
-(and subsection) onto the top of the section stack, and then replaces the
-current section and subsection with @code{name} and @code{subsection}.
+This directive pushes the current section (and subsection) onto the
+top of the section stack, and then replaces the current section and
+subsection with @code{name} and @code{subsection}.
@end ifset
@node Quad
section does not contain data (i.e., section only occupies space)
@item @@note
section contains data which is used by things other than the program
+@item @@init_array
+section contains an array of pointers to init functions
+@item @@fini_array
+section contains an array of pointers to finish functions
+@item @@preinit_array
+section contains an array of pointers to pre-init functions
@end table
+Many targets only support the first three section types.
+
Note on targets where the @code{@@} character is the start of a comment (eg
ARM) then another character is used instead. For example the ARM port uses the
@code{%} character.
section is used for thread local storage
@end table
-This directive replaces the current section and subsection. The replaced
-section and subsection are pushed onto the section stack. See the contents of
-the gas testsuite directory @code{gas/testsuite/gas/elf} for some examples of
-how this directive and the other section stack directives work.
+This directive replaces the current section and subsection. See the
+contents of the gas testsuite directory @code{gas/testsuite/gas/elf} for
+some examples of how this directive and the other section stack directives
+work.
@end ifset
@end ifset
@node VTableEntry
@section @code{.vtable_entry @var{table}, @var{offset}}
-@cindex @code{vtable_entry}
+@cindex @code{vtable_entry} directive
This directive finds or creates a symbol @code{table} and creates a
@code{VTABLE_ENTRY} relocation for it with an addend of @code{offset}.
@node VTableInherit
@section @code{.vtable_inherit @var{child}, @var{parent}}
-@cindex @code{vtable_inherit}
+@cindex @code{vtable_inherit} directive
This directive finds the symbol @code{child} and finds or creates the symbol
@code{parent} and then creates a @code{VTABLE_INHERIT} relocation for the
parent whose addend is the value of the child symbol. As a special case the
parent name of @code{0} is treated as refering the @code{*ABS*} section.
@end ifset
-@ifset ELF
+@node Warning
+@section @code{.warning "@var{string}"}
+@cindex warning directive
+Similar to the directive @code{.error}
+(@pxref{Error,,@code{.error "@var{string}"}}), but just emits a warning.
+
@node Weak
@section @code{.weak @var{names}}
@cindex @code{weak} directive
This directive sets the weak attribute on the comma separated list of symbol
@code{names}. If the symbols do not already exist, they will be created.
-@end ifset
+
+On COFF targets other than PE, weak symbols are a GNU extension. This
+directive sets the weak attribute on the comma separated list of symbol
+@code{names}. If the symbols do not already exist, they will be created.
+
+On the PE target, weak symbols are supported natively as weak aliases.
+When a weak symbol is created that is not an alias, GAS creates an
+alternate symbol to hold the default value.
@node Word
@section @code{.word @var{expressions}}
@ifset I960
* i960-Dependent:: Intel 80960 Dependent Features
@end ifset
+@ifset IA64
+* IA-64-Dependent:: Intel IA-64 Dependent Features
+@end ifset
@ifset IP2K
* IP2K-Dependent:: IP2K Dependent Features
@end ifset
@node Acknowledgements
@chapter Acknowledgements
-If you have contributed to @command{@value{AS}} and your name isn't listed here,
+If you have contributed to GAS and your name isn't listed here,
it is not meant as a slight. We just don't know about it. Send mail to the
maintainer, and we'll correct the situation. Currently
@c (January 1994),
added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and
PowerPC assembler, and made a few other minor patches.
-Steve Chamberlain made @command{@value{AS}} able to generate listings.
+Steve Chamberlain made GAS able to generate listings.
Hewlett-Packard contributed support for the HP9000/300.
projects / deliverable / binutils-gdb.git / blobdiff