gas/

[deliverable/binutils-gdb.git] / gas / doc / as.texinfo

diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
index 800d447cc5211d819ba7436ea17a44e805cd4057..051ab70df62d0a02fd4bf81b0fafadda0722c142 100644 (file)
--- a/gas/doc/as.texinfo
+++ b/gas/doc/as.texinfo
@@ -227,8 +227,8 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
 @smallexample
 @c man begin SYNOPSIS
 @value{AS} [@b{-a}[@b{cdhlns}][=@var{file}]] [@b{--alternate}] [@b{-D}]
 @smallexample
 @c man begin SYNOPSIS
 @value{AS} [@b{-a}[@b{cdhlns}][=@var{file}]] [@b{--alternate}] [@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}]
+ [@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{--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}]


@@ -268,7 +268,7 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
    [@b{-EB}|@b{-EL}]
    [@b{-mapcs-32}|@b{-mapcs-26}|@b{-mapcs-float}|
     @b{-mapcs-reentrant}]
    [@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
 
 @end ifset
 @ifset CRIS
 


@@ -276,6 +276,7 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
    [@b{--underscore} | @b{--no-underscore}]
    [@b{--pic}] [@b{-N}]
    [@b{--emulation=criself} | @b{--emulation=crisaout}]
    [@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
 @c Deprecated -- deliberately not documented.
 @c [@b{-h}] [@b{-H}]
 @end ifset


@@ -314,6 +315,7 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
    [@b{-mconstant-gp}|@b{-mauto-pic}]
    [@b{-milp32}|@b{-milp64}|@b{-mlp64}|@b{-mp64}]
    [@b{-mle}|@b{mbe}]
    [@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
    [@b{-x}|@b{-xexplicit}] [@b{-xauto}] [@b{-xdebug}]
 @end ifset
 @ifset IP2K


@@ -420,9 +422,10 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
 @ifset XTENSA
 
 @emph{Target Xtensa options:}
 @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-]target-align}] [@b{--[no-]longcalls}]

+ [@b{--[no-]transform}]
+ [@b{--rename-section} @var{oldname}=@var{newname}]

 @end ifset
 @c man end
 @end smallexample
 @end ifset
 @c man end
 @end smallexample


@@ -479,6 +482,12 @@ indicates a hexadecimal value, and a leading @samp{0} indicates an octal value.
 ``fast''---skip whitespace and comment preprocessing (assume source is
 compiler output).
 
 ``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.
 @item --gstabs
 Generate stabs debugging information for each assembler line.  This
 may help debugging assembler code, if the debugger can handle it.


@@ -490,7 +499,7 @@ debuggers crash or refuse to read your program.  This
 may help debugging assembler code.  Currently the only GNU extension is
 the location of the current working directory at assembling time.
 
 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.
 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.


@@ -608,7 +617,7 @@ Select which Floating Point architecture is the target.
 Select which floating point ABI is in use.
 @item -mthumb
 Enable Thumb only instruction decoding.
 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.
 Select which procedure calling convention is in use.
 @item -EB | -EL
 Select either big-endian (-EB) or little-endian (-EL) output.


@@ -1055,28 +1064,19 @@ The following options are available when @value{AS} is configured for
 an Xtensa processor.
 
 @table @gcctabopt
 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
 @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
 
 @item --target-align | --no-target-align
 Enable or disable automatic alignment to reduce branch penalties at the


@@ -1086,6 +1086,12 @@ expense of some code density.  The default is @option{--target-@-align}.
 Enable or disable transformation of call instructions to allow calls
 across a greater range of addresses.  The default is
 @option{--no-@-longcalls}.
 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
 
 @end table
 @end ifset
 


@@ -3721,6 +3727,7 @@ Some machine configurations provide additional directives.
 * Equ::                         @code{.equ @var{symbol}, @var{expression}}
 * Equiv::                       @code{.equiv @var{symbol}, @var{expression}}
 * Err::                                @code{.err}
 * 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}
 * Exitm::                      @code{.exitm}
 * Extern::                      @code{.extern}
 * Fail::                       @code{.fail}


@@ -3837,6 +3844,7 @@ Some machine configurations provide additional directives.
 * VTableInherit::               @code{.vtable_inherit @var{child}, @var{parent}}
 @end ifset
 
 * VTableInherit::               @code{.vtable_inherit @var{child}, @var{parent}}
 @end ifset
 

+* Warning::                    @code{.warning @var{string}}

 * Weak::                        @code{.weak @var{names}}
 * Word::                        @code{.word @var{expressions}}
 * Deprecated::                  Deprecated Directives
 * Weak::                        @code{.weak @var{names}}
 * Word::                        @code{.word @var{expressions}}
 * Deprecated::                  Deprecated Directives


@@ -4235,6 +4243,19 @@ If @command{@value{AS}} assembles a @code{.err} directive, it will print an erro
 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.
 
 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}.
 @node Exitm
 @section @code{.exitm}
 Exit early from the current macro definition.  @xref{Macro}.


@@ -5285,8 +5306,16 @@ section contains data
 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
 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
 
 @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.
 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.


@@ -5838,20 +5867,26 @@ formatted note of type NT_VERSION.  The note's name is set to @code{string}.
 @node VTableEntry
 @section @code{.vtable_entry @var{table}, @var{offset}}
 
 @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}}
 
 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
 
 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
 

+@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}}
 
 @node Weak
 @section @code{.weak @var{names}}
 


@@ -5859,24 +5894,13 @@ parent name of @code{0} is treated as refering the @code{*ABS*} section.
 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.
 
 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.
 

-Weak symbols are supported in COFF as a GNU extension.  This directive
-sets the weak attribute on the comma separated list of symbol
+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.
 
 @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.
+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}}
 
 @node Word
 @section @code{.word @var{expressions}}


@@ -6016,6 +6040,9 @@ subject, see the hardware manufacturer's manual.
 @ifset I960
 * i960-Dependent::              Intel 80960 Dependent Features
 @end ifset
 @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
 @ifset IP2K
 * IP2K-Dependent::              IP2K Dependent Features
 @end ifset


@@ -6450,7 +6477,7 @@ things without first using the debugger to find the facts.
 @node Acknowledgements
 @chapter Acknowledgements
 
 @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), 
 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), 


@@ -6511,7 +6538,7 @@ Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
 added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and
 PowerPC assembler, and made a few other minor patches.
 
 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.
 
 
 Hewlett-Packard contributed support for the HP9000/300.