\input texinfo @c -*-Texinfo-*-
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001, 2002
+@c 2001, 2002, 2003, 2004, 2005
@c Free Software Foundation, Inc.
@c UPDATE!! On future updates--
@c (1) check for new machine-dep cmdline options in
@c defaults, config file may override:
@set have-stabs
@c ---
+@c man begin NAME
+@c ---
@include asconfig.texi
@include gasver.texi
@c ---
-@c man begin NAME
-@ifset man
-@c Configure for the generation of man pages
-@set AS as
-@set TARGET TARGET
-@set GENERIC
-@set A29K
-@set ALPHA
-@set ARC
-@set ARM
-@set CRIS
-@set D10V
-@set D30V
-@set H8/300
-@set H8/500
-@set HPPA
-@set I370
-@set I80386
-@set I860
-@set I960
-@set IA-64
-@set IP2K
-@set M32R
-@set M68HC11
-@set M680X0
-@set M880X0
-@set MCORE
-@set MIPS
-@set MMIX
-@set PDP11
-@set PJ
-@set PPC
-@set SH
-@set SPARC
-@set TIC54X
-@set V850
-@set VAX
-@set XTENSA
-@end ifset
@c man end
+@c ---
@c common OR combinations of conditions
@ifset COFF
@set COFF-ELF
@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{--gdwarf2}] [@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{-version}] [@b{--version}] [@b{-W}] [@b{--warn}] [@b{--fatal-warnings}]
- [@b{-w}] [@b{-x}] [@b{-Z}] [@b{--target-help}] [@var{target-options}]
- [@b{--}|@var{files} @dots{}]
+@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{--reduce-memory-overheads}] [@b{--statistics}]
+ [@b{-v}] [@b{-version}] [@b{--version}] [@b{-W}] [@b{--warn}]
+ [@b{--fatal-warnings}] [@b{-w}] [@b{-x}] [@b{-Z}] [@b{--target-help}]
+ [@var{target-options}] [@b{--}|@var{files} @dots{}]
@c
@c Target dependent options are listed below. Keep the list sorted.
@c Add an empty line for separation.
@c Don't document the deprecated options
[@b{-mcpu}=@var{processor}[+@var{extension}@dots{}]]
[@b{-march}=@var{architecture}[+@var{extension}@dots{}]]
- [@b{-mfpu}=@var{floating-point-fromat}]
+ [@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
[@b{-O}|@b{-n}|@b{-N}]
@end ifset
@ifset H8
-@c Hitachi family chips have no machine-dependent assembler options
+@c Renesas family chips have no machine-dependent assembler options
@end ifset
@ifset HPPA
@c HPPA has no machine-dependent assembler options (yet).
@ifset I80386
@emph{Target i386 options:}
- [@b{--32}|@b{--64}]
+ [@b{--32}|@b{--64}] [@b{-n}]
@end ifset
@ifset I960
[@b{-mconstant-gp}|@b{-mauto-pic}]
[@b{-milp32}|@b{-milp64}|@b{-mlp64}|@b{-mp64}]
[@b{-mle}|@b{mbe}]
+ [@b{-mtune=itanium1}|@b{-mtune=itanium2}]
+ [@b{-munwind-check=warning}|@b{-munwind-check=error}]
+ [@b{-mhint.b=ok}|@b{-mhint.b=warning}|@b{-mhint.b=error}]
[@b{-x}|@b{-xexplicit}] [@b{-xauto}] [@b{-xdebug}]
@end ifset
@ifset IP2K
@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}]
- [@b{-mips64}]
+ [@b{-mips64}] [@b{-mips64r2}]
[@b{-construct-floats}] [@b{-no-construct-floats}]
[@b{-trap}] [@b{-no-break}] [@b{-break}] [@b{-no-trap}]
[@b{-mfix7000}] [@b{-mno-fix7000}]
[@b{-mips3d}] [@b{-no-mips3d}]
[@b{-mdmx}] [@b{-no-mdmx}]
[@b{-mdebug}] [@b{-no-mdebug}]
+ [@b{-mpdr}] [@b{-mno-pdr}]
@end ifset
@ifset MMIX
@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.
-@item --gdwarf2
+@item --gstabs+
+Generate stabs debugging information for each assembler line, with GNU
+extensions that probably only gdb can handle, and that could make other
+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.
+
+@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.
@item -R
Fold the data section into the text section.
+@kindex --hash-size=@var{number}
+Set the default size of GAS's hash tables to a prime number close to
+@var{number}. Increasing this value can reduce the length of time it takes the
+assembler to perform its tasks, at the expense of increasing the assembler's
+memory requirements. Similarly reducing this value can reduce the memory
+requirements at the expense of speed.
+
+@item --reduce-memory-overheads
+This option reduces GAS's memory requirements, at the expense of making the
+assembly processes slower. Currently this switch is a synonym for
+@samp{--hash-size=4051}, but in the future it may have other effects as well.
+
@item --statistics
Print the maximum space (in bytes) and total time (in seconds) used by
assembly.
Specify which ARM architecture variant is used by the target.
@item -mfpu=@var{floating-point-format}
Select which Floating Point architecture is the target.
+@item -mfloat-abi=@var{abi}
+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.
@ifset M32R
The following options are available when @value{AS} is configured for the
-Mitsubishi M32R series.
+Renesas M32R (formerly Mitsubishi M32R) series.
@table @gcctabopt
@itemx -mips32
@itemx -mips32r2
@itemx -mips64
+@itemx -mips64r2
Generate code for a particular @sc{mips} Instruction Set Architecture level.
@samp{-mips1} is an alias for @samp{-march=r3000}, @samp{-mips2} is an
alias for @samp{-march=r6000}, @samp{-mips3} is an alias for
@samp{-march=r4000} and @samp{-mips4} is an alias for @samp{-march=r8000}.
-@samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, and @samp{-mips64}
+@samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, @samp{-mips64}, and
+@samp{-mips64r2}
correspond to generic
-@samp{MIPS V}, @samp{MIPS32}, @samp{MIPS32 Release 2}, and
-@samp{MIPS64} ISA processors,
-respectively.
+@samp{MIPS V}, @samp{MIPS32}, @samp{MIPS32 Release 2}, @samp{MIPS64},
+and @samp{MIPS64 Release 2}
+ISA processors, respectively.
@item -march=@var{CPU}
Generate code for a particular @sc{mips} cpu.
Cause stabs-style debugging output to go into an ECOFF-style .mdebug
section instead of the standard ELF .stabs sections.
+@item -mpdr
+@itemx -mno-pdr
+Control generation of @code{.pdr} sections.
+
@item -mgp32
@itemx -mfp32
The register sizes are normally inferred from the ISA and ABI, but these
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
@ifclear GENERIC
@ifset H8/300
For information on the H8/300 machine instruction set, see @cite{H8/300
-Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H,
-see @cite{H8/300H Series Programming Manual} (Hitachi).
+Series Programming Manual}. For the H8/300H, see @cite{H8/300H Series
+Programming Manual} (Renesas).
@end ifset
@ifset H8/500
For information on the H8/500 machine instruction set, see @cite{H8/500
-Series Programming Manual} (Hitachi M21T001).
+Series Programming Manual} (Renesas M21T001).
@end ifset
@ifset SH
-For information on the Hitachi SH machine instruction set, see
-@cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
+For information on the Renesas (formerly Hitachi) / SuperH SH machine instruction set,
+see @cite{SH-Microcomputer User's Manual} (Renesas) or
+@cite{SH-4 32-bit CPU Core Architecture} (SuperH) and
+@cite{SuperH (SH) 64-Bit RISC Series} (SuperH).
@end ifset
@ifset Z8000
For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
@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}
@samp{;} for picoJava;
@end ifset
@ifset PPC
-@samp{;} for Motorola PowerPC;
+@samp{#} for Motorola PowerPC;
@end ifset
@ifset SH
-@samp{!} for the Hitachi SH;
+@samp{!} for the Renesas / SuperH SH;
@end ifset
@ifset SPARC
@samp{!} on the SPARC;
@ifset H8
A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
H8/300) a dollar sign (@samp{$}); or (for the
-Hitachi-SH or the
+Renesas-SH or the
H8/500) a semicolon
(@samp{;}). The newline or separator character is considered part of
the preceding statement. Newlines and separators within character
@end ifset
@ifset H8
(or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
-Hitachi SH or
-H8/500)
+Renesas SH or H8/500)
@end ifset
@end ifset
@end ifclear
@end ignore
On the H8/300, H8/500,
-Hitachi SH,
+Renesas / SuperH SH,
and AMD 29K architectures, the letter must be
one of the letters @samp{DFPRSX} (in upper or lower case).
the proper run-time addresses.
@ifset H8
For the H8/300 and H8/500,
-and for the Hitachi SH,
+and for the Renesas / SuperH SH,
@command{@value{AS}} pads sections if needed to
ensure they end on a word (sixteen bit) boundary.
@end ifset
@ifset H8
On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
boundary (two bytes).
-The same is true on the Hitachi SH.
+The same is true on the Renesas SH.
@end ifset
@ifset I960
@c FIXME section padding (alignment)?
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
@ifset SPECIAL-SYMS
@ifset H8
Symbol names begin with a letter or with one of @samp{._}. On the
-Hitachi SH or the
-H8/500, you can also use @code{$} in symbol names. That character may
-be followed by any string of digits, letters, dollar signs (save on the
-H8/300), and underscores.
+Renesas SH or the H8/500, you can also use @code{$} in symbol names. That
+character may be followed by any string of digits, letters, dollar signs (save
+on the H8/300), and underscores.
@end ifset
@end ifset
@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}}
* Byte:: @code{.byte @var{expressions}}
* Comm:: @code{.comm @var{symbol} , @var{length} }
+
+* CFI directives:: @code{.cfi_startproc}, @code{.cfi_endproc}, etc.
+
* Data:: @code{.data @var{subsection}}
@ifset COFF
* Def:: @code{.def @var{name}}
* 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
with no-op instructions when appropriate.
The way the required alignment is specified varies from system to system.
-For the a29k, hppa, m68k, m88k, w65, sparc, Xtensa, and Hitachi SH, and i386 using ELF
-format,
-the first expression is the
+For the a29k, arc, hppa, i386 using ELF, i860, iq2000, m68k, m88k, or32,
+s390, sparc, tic4x, tic80 and xtensa, the first expression is the
alignment request in bytes. For example @samp{.align 8} advances
the location counter until it is a multiple of 8. If the location counter
-is already a multiple of 8, no change is needed.
+is already a multiple of 8, no change is needed. For the tic54x, the
+first expression is the alignment request in words.
For other systems, including the i386 using a.out format, and the arm and
strongarm, it is the
@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
@end ifset
+@node CFI directives
+@section @code{.cfi_startproc}
+@cindex @code{cfi_startproc} directive
+@code{.cfi_startproc} is used at the beginning of each function that
+should have an entry in @code{.eh_frame}. It initializes some internal
+data structures and emits architecture dependent initial CFI instructions.
+Don't forget to close the function by
+@code{.cfi_endproc}.
+
+@section @code{.cfi_endproc}
+@cindex @code{cfi_endproc} directive
+@code{.cfi_endproc} is used at the end of a function where it closes its
+unwind entry previously opened by
+@code{.cfi_startproc}. and emits it to @code{.eh_frame}.
+
+@section @code{.cfi_def_cfa @var{register}, @var{offset}}
+@code{.cfi_def_cfa} defines a rule for computing CFA as: @i{take
+address from @var{register} and add @var{offset} to it}.
+
+@section @code{.cfi_def_cfa_register @var{register}}
+@code{.cfi_def_cfa_register} modifies a rule for computing CFA. From
+now on @var{register} will be used instead of the old one. Offset
+remains the same.
+
+@section @code{.cfi_def_cfa_offset @var{offset}}
+@code{.cfi_def_cfa_offset} modifies a rule for computing CFA. Register
+remains the same, but @var{offset} is new. Note that it is the
+absolute offset that will be added to a defined register to compute
+CFA address.
+
+@section @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.
+
+@section @code{.cfi_offset @var{register}, @var{offset}}
+Previous value of @var{register} is saved at offset @var{offset} from
+CFA.
+
+@section @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}
+using the known displacement of the CFA register from the CFA.
+This is often easier to use, because the number will match the
+code it's annotating.
+
+@section @code{.cfi_window_save}
+SPARC register window has been saved.
+
+@section @code{.cfi_escape} @var{expression}[, @dots{}]
+Allows the user to add arbitrary bytes to the unwind info. One
+might use this to add OS-specific CFI opcodes, or generic CFI
+opcodes that GAS does not yet support.
+
@node Data
@section @code{.data @var{subsection}}
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}.
@cindex @code{func} directive
@code{.func} emits debugging information to denote function @var{name}, and
is ignored unless the file is assembled with debugging enabled.
-Only @samp{--gstabs} is currently supported.
+Only @samp{--gstabs[+]} is currently supported.
@var{label} is the entry point of the function and if omitted @var{name}
prepended with the @samp{leading char} is used.
@samp{leading char} is usually @code{_} or nothing, depending on the target.
@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}}).
has been defined. Note a symbol which has been referenced but not yet defined
is considered to be undefined.
+@cindex @code{ifb} directive
+@item .ifb @var{text}
+Assembles the following section of code if the operand is blank (empty).
+
@cindex @code{ifc} directive
@item .ifc @var{string1},@var{string2}
Assembles the following section of code if the two strings are the same. The
@item .iflt @var{absolute expression}
Assembles the following section of code if the argument is less than zero.
+@cindex @code{ifnb} directive
+@item .ifnb @var{text}
+Like @code{.ifb}, but the sense of the test is reversed: this assembles the
+following section of code if the operand is non-blank (non-empty).
+
@cindex @code{ifnc} directive
@item .ifnc @var{string1},@var{string2}.
Like @code{.ifc}, but the sense of the test is reversed: this assembles the
@ifclear GENERIC
@ifset H8
On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
-integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits
+integers. On the H8/300H and the Renesas SH, however, @code{.int} emits
32-bit integers.
@end ifset
@end ifclear
@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}}).
move d3,sp@@-
@end example
+For some caveats with the spelling of @var{symbol}, see also the discussion
+at @xref{Macro}.
+
@node Irpc
@section @code{.irpc @var{symbol},@var{values}}@dots{}
move d3,sp@@-
@end example
+For some caveats with the spelling of @var{symbol}, see also the discussion
+at @xref{Macro}.
+
@node Lcomm
@section @code{.lcomm @var{symbol} , @var{length}}
@cindex @code{macro} directive
Begin the definition of a macro called @var{macname}. If your macro
definition requires arguments, specify their names after the macro name,
-separated by commas or spaces. You can supply a default value for any
-macro argument by following the name with @samp{=@var{deflt}}. For
-example, these are all valid @code{.macro} statements:
+separated by commas or spaces. You can qualify the macro argument to
+indicate whether all invocations must specify a non-blank value (through
+@samp{:@code{req}}), or whether it takes all of the remaining arguments
+(through @samp{:@code{vararg}}). You can supply a default value for any
+macro argument by following the name with @samp{=@var{deflt}}. You
+cannot define two macros with the same @var{macname} unless it has been
+subject to the @code{.purgem} directive (@xref{Purgem}.) between the two
+definitions. For example, these are all valid @code{.macro} statements:
@table @code
@item .macro comm
@samp{0}, and @samp{\p2} evaluating to @var{b}).
@end table
+@item .macro m p1:req, p2=0, p3:vararg
+Begin the definition of a macro called @code{m}, with at least three
+arguments. The first argument must always have a value specified, but
+not the second, which instead has a default value. The third formal
+will get assigned all remaining arguments specified at invocation time.
+
When you call a macro, you can specify the argument values either by
position, or by keyword. For example, @samp{sum 9,17} is equivalent to
@samp{sum to=17, from=9}.
+Note that since each of the @var{macargs} can be an identifier exactly
+as any other one permitted by the target architecture, there may be
+occasional problems if the target hand-crafts special meanings to certain
+characters when they occur in a special position. For example, if colon
+(@code{:}) is generally permitted to be part of a symbol name, but the
+architecture specific code special-cases it when occuring as the final
+character of a symbol (to denote a label), then the macro parameter
+replacement code will have no way of knowing that and consider the whole
+construct (including the colon) an identifier, and check only this
+identifier for being the subject to parameter substitution. In this
+example, besides the potential of just separating identifier and colon
+by white space, using alternate macro syntax (@xref{Altmacro}.) and
+ampersand (@code{&}) as the character to separate literal text from macro
+parameters (or macro parameters from one another) would provide a way to
+achieve the same effect:
+
+@example
+ .altmacro
+ .macro label l
+l&:
+ .endm
+@end example
+
+This applies identically to the identifiers used in @code{.irp} (@xref{Irp}.)
+and @code{.irpc} (@xref{Irpc}.).
+
@item .endm
@cindex @code{endm} directive
Mark the end of a macro definition.
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}
@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 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}}
* D30V-Dependent:: D30V Dependent Features
@end ifset
@ifset H8/300
-* H8/300-Dependent:: Hitachi H8/300 Dependent Features
+* H8/300-Dependent:: Renesas H8/300 Dependent Features
@end ifset
@ifset H8/500
-* H8/500-Dependent:: Hitachi H8/500 Dependent Features
+* H8/500-Dependent:: Renesas H8/500 Dependent Features
@end ifset
@ifset HPPA
* HPPA-Dependent:: HPPA Dependent Features
@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
* MSP430-Dependent:: MSP430 Dependent Features
@end ifset
@ifset SH
-* SH-Dependent:: Hitachi SH Dependent Features
-* SH64-Dependent:: Hitachi SH64 Dependent Features
+* SH-Dependent:: Renesas / SuperH SH Dependent Features
+* SH64-Dependent:: SuperH SH64 Dependent Features
@end ifset
@ifset PDP11
* PDP-11-Dependent:: PDP-11 Dependent Features
@include c-cris.texi
@end ifset
-@ifset Hitachi-all
+@ifset Renesas-all
@ifclear GENERIC
@node Machine Dependencies
@chapter Machine Dependent Features
-The machine instruction sets are different on each Hitachi chip family,
+The machine instruction sets are different on each Renesas chip family,
and there are also some syntax differences among the families. This
chapter describes the specific @command{@value{AS}} features for each
family.
@menu
-* H8/300-Dependent:: Hitachi H8/300 Dependent Features
-* H8/500-Dependent:: Hitachi H8/500 Dependent Features
-* SH-Dependent:: Hitachi SH Dependent Features
+* H8/300-Dependent:: Renesas H8/300 Dependent Features
+* H8/500-Dependent:: Renesas H8/500 Dependent Features
+* SH-Dependent:: Renesas SH Dependent Features
@end menu
@lowersections
@end ifclear
@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),
(which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to
support a.out format.
-Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k,
+Support for the Zilog Z8k and Renesas H8/300 and H8/500 processors (tc-z8k,
tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
use BFD for some low-level operations, for use with the H8/300 and AMD 29k
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