\input texinfo @c -*-Texinfo-*-
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001, 2002, 2003
+@c 2001, 2002, 2003, 2004
@c Free Software Foundation, Inc.
@c UPDATE!! On future updates--
@c (1) check for new machine-dep cmdline options in
@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{-march}=@var{architecture}[+@var{extension}@dots{}]]
[@b{-mfpu}=@var{floating-point-format}]
[@b{-mfloat-abi}=@var{abi}]
+ [@b{-meabi}=@var{ver}]
[@b{-mthumb}]
[@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
@ifset MIPS
@emph{Target MIPS options:}
- [@b{-nocpp}] [@b{-EL}] [@b{-EB}] [@b{-n}] [@b{-O}[@var{optimization level}]]
+ [@b{-nocpp}] [@b{-EL}] [@b{-EB}] [@b{-O}[@var{optimization level}]]
[@b{-g}[@var{debug level}]] [@b{-G} @var{num}] [@b{-KPIC}] [@b{-call_shared}]
- [@b{-non_shared}] [@b{-xgot}] [@b{--membedded-pic}]
+ [@b{-non_shared}] [@b{-xgot}]
[@b{-mabi}=@var{ABI}] [@b{-32}] [@b{-n32}] [@b{-64}] [@b{-mfp32}] [@b{-mgp32}]
[@b{-march}=@var{CPU}] [@b{-mtune}=@var{CPU}] [@b{-mips1}] [@b{-mips2}]
[@b{-mips3}] [@b{-mips4}] [@b{-mips5}] [@b{-mips32}] [@b{-mips32r2}]
@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}]
@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}
To specify which subsection you want subsequent statements assembled
into, use a numeric argument to specify it, in a @samp{.text
@var{expression}} or a @samp{.data @var{expression}} statement.
-@ifset COFF-ELF
+@ifset COFF
@ifset GENERIC
-When generating COFF or ELF output, you
+When generating COFF output, you
@end ifset
@ifclear GENERIC
You
argument with arbitrary named sections: @samp{.section @var{name},
@var{expression}}.
@end ifset
+@ifset ELF
+@ifset GENERIC
+When generating ELF output, you
+@end ifset
+@ifclear GENERIC
+You
+@end ifclear
+can also use the @code{.subsection} directive (@pxref{SubSection})
+to specify a subsection: @samp{.subsection @var{expression}}.
+@end ifset
@var{Expression} should be an absolute expression.
(@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
@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}}
* 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
+* Weak:: @code{.weak @var{names}}
* Word:: @code{.word @var{expressions}}
* Deprecated:: Deprecated Directives
@end menu
@cindex @code{hidden} directive
@cindex visibility
-This one of the ELF visibility directives. The other two are
+This is one of the ELF visibility directives. The other two are
@code{.internal} (@pxref{Internal,,@code{.internal}}) and
@code{.protected} (@pxref{Protected,,@code{.protected}}).
@cindex @code{internal} directive
@cindex visibility
-This one of the ELF visibility directives. The other two are
+This is one of the ELF visibility directives. The other two are
@code{.hidden} (@pxref{Hidden,,@code{.hidden}}) and
@code{.protected} (@pxref{Protected,,@code{.protected}}).
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
-Generate a string replacement for each of the @var{name} arguments, and
+@node Altmacro
+@section @code{.altmacro}
+Enable alternate macro mode, enabling:
+
+@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}
@cindex @code{protected} directive
@cindex visibility
-This one of the ELF visibility directives. The other two are
+This is one of the ELF visibility directives. The other two are
@code{.hidden} (@pxref{Hidden}) and @code{.internal} (@pxref{Internal}).
This directive overrides the named symbols default visibility (which is set by
@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
For ELF targets, the @code{.section} directive is used like this:
@smallexample
-.section @var{name} [, "@var{flags}"[, @@@var{type}[, @@@var{entsize}]]]
+.section @var{name} [, "@var{flags}"[, @@@var{type}[,@var{flag_specific_arguments}]]
@end smallexample
The optional @var{flags} argument is a quoted string which may contain any
section is mergeable
@item S
section contains zero terminated strings
+@item G
+section is a member of a section group
+@item T
+section is used for thread-local-storage
@end table
The optional @var{type} argument may contain one of the following constants:
section contains data
@item @@nobits
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.
-If @var{flags} contains @code{M} flag, @var{type} argument must be specified
-as well as @var{entsize} argument. Sections with @code{M} flag but not
-@code{S} flag must contain fixed size constants, each @var{entsize} octets
-long. Sections with both @code{M} and @code{S} must contain zero terminated
-strings where each character is @var{entsize} bytes long. The linker may remove
-duplicates within sections with the same name, same entity size and same flags.
+If @var{flags} contains the @code{M} symbol then the @var{type} argument must
+be specified as well as an extra argument - @var{entsize} - like this:
+
+@smallexample
+.section @var{name} , "@var{flags}"M, @@@var{type}, @var{entsize}
+@end smallexample
+
+Sections with the @code{M} flag but not @code{S} flag must contain fixed size
+constants, each @var{entsize} octets long. Sections with both @code{M} and
+@code{S} must contain zero terminated strings where each character is
+@var{entsize} bytes long. The linker may remove duplicates within sections with
+the same name, same entity size and same flags. @var{entsize} must be an
+absolute expression.
+
+If @var{flags} contains the @code{G} symbol then the @var{type} argument must
+be present along with an additional field like this:
+
+@smallexample
+.section @var{name} , "@var{flags}"G, @@@var{type}, @var{GroupName}[, @var{linkage}]
+@end smallexample
+
+The @var{GroupName} field specifies the name of the section group to which this
+particular section belongs. The optional linkage field can contain:
+@table @code
+@item comdat
+indicates that only one copy of this section should be retained
+@item .gnu.linkonce
+an alias for comdat
+@end table
+
+Note - if both the @var{M} and @var{G} flags are present then the fields for
+the Merge flag should come first, like this:
+
+@smallexample
+.section @var{name} , "@var{flags}"MG, @@@var{type}, @var{entsize}, @var{GroupName}[, @var{linkage}]
+@end smallexample
If no flags are specified, the default flags depend upon the section name. If
the section name is not recognized, the default will be for the section to have
section is writable
@item #execinstr
section is executable
+@item #tls
+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 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
+
+Weak symbols are supported in COFF as 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.
+
+@smallexample
+@code{.weak @var{name} [ < = | == > @var{alternate}] [, ...]}
+@end smallexample
+
+On the PE target, weak aliases are supported natively. Weak aliases
+(usually called "weak externals" in PE) are created when an alternate
+name is specified. When a weak symbol is linked and the symbol is not
+defined, the weak symbol becomes an alias for the alternate symbol. If
+one equal sign is used, the linker searches for defined symbols within
+other objects and libraries. This is the usual mode, historically
+called "lazy externals." Otherwise, when two equal signs are used,
+the linker searches for defined symbols only within other objects.
+
+Non-alias weak symbols are supported on PE as a GNU extension.
@node Word
@section @code{.word @var{expressions}}
@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