\input texinfo @c -*-Texinfo-*-
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007
+@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
@c Free Software Foundation, Inc.
@c UPDATE!! On future updates--
@c (1) check for new machine-dep cmdline options in
@c man begin COPYRIGHT
Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002,
-2006, 2007 Free Software Foundation, Inc.
+2006, 2007, 2008, 2009 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.1
+under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
@vskip 0pt plus 1filll
Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002,
-2006, 2007 Free Software Foundation, Inc.
+2006, 2007, 2008, 2009 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.1
+ under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
* Symbols:: Symbols
* Expressions:: Expressions
* Pseudo Ops:: Assembler Directives
+@ifset ELF
+* Object Attributes:: Object Attributes
+@end ifset
* Machine Dependencies:: Machine Dependent Features
* Reporting Bugs:: Reporting Bugs
* Acknowledgements:: Who Did What
@c to be limited to one line for the header.
@smallexample
@c man begin SYNOPSIS
-@value{AS} [@b{-a}[@b{cdhlns}][=@var{file}]] [@b{--alternate}] [@b{-D}]
+@value{AS} [@b{-a}[@b{cdghlns}][=@var{file}]] [@b{--alternate}] [@b{-D}]
[@b{--debug-prefix-map} @var{old}=@var{new}]
[@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}]
@emph{Target Alpha options:}
[@b{-m@var{cpu}}]
[@b{-mdebug} | @b{-no-mdebug}]
+ [@b{-replace} | @b{-noreplace}]
[@b{-relax}] [@b{-g}] [@b{-G@var{size}}]
[@b{-F}] [@b{-32addr}]
@end ifset
[@b{-O}|@b{-n}|@b{-N}]
@end ifset
@ifset H8
-@c Renesas family chips have no machine-dependent assembler options
+
+@emph{Target H8/300 options:}
+ [-h-tick-hex]
@end ifset
@ifset HPPA
@c HPPA has no machine-dependent assembler options (yet).
@emph{Target i386 options:}
[@b{--32}|@b{--64}] [@b{-n}]
- [@b{-march}=@var{CPU}] [@b{-mtune}=@var{CPU}]
+ [@b{-march}=@var{CPU}[+@var{EXTENSION}@dots{}]] [@b{-mtune}=@var{CPU}]
@end ifset
@ifset I960
@ifset M32C
@emph{Target M32C options:}
- [@b{-m32c}|@b{-m16c}]
+ [@b{-m32c}|@b{-m16c}] [-relax] [-h-tick-hex]
@end ifset
@ifset M32R
[@b{-jsri2bsr}] [@b{-sifilter}] [@b{-relax}]
[@b{-mcpu=[210|340]}]
@end ifset
+@ifset MICROBLAZE
+@emph{Target MICROBLAZE options:}
+@c MicroBlaze has no machine-dependent assembler options.
+@end ifset
@ifset MIPS
@emph{Target MIPS options:}
@emph{Target PowerPC options:}
[@b{-mpwrx}|@b{-mpwr2}|@b{-mpwr}|@b{-m601}|@b{-mppc}|@b{-mppc32}|@b{-m603}|@b{-m604}|
- @b{-m403}|@b{-m405}|@b{-mppc64}|@b{-m620}|@b{-mppc64bridge}|@b{-mbooke}|
- @b{-mbooke32}|@b{-mbooke64}]
- [@b{-mcom}|@b{-many}|@b{-maltivec}] [@b{-memb}]
+ @b{-m403}|@b{-m405}|@b{-mppc64}|@b{-m620}|@b{-mppc64bridge}|@b{-mbooke}]
+ [@b{-mcom}|@b{-many}|@b{-maltivec}|@b{-mvsx}] [@b{-memb}]
[@b{-mregnames}|@b{-mno-regnames}]
[@b{-mrelocatable}|@b{-mrelocatable-lib}]
[@b{-mlittle}|@b{-mlittle-endian}|@b{-mbig}|@b{-mbig-endian}]
[@b{-msolaris}|@b{-mno-solaris}]
@end ifset
+@ifset S390
+
+@emph{Target s390 options:}
+ [@b{-m31}|@b{-m64}] [@b{-mesa}|@b{-mzarch}] [@b{-march}=@var{CPU}]
+ [@b{-mregnames}|@b{-mno-regnames}]
+ [@b{-mwarn-areg-zero}]
+@end ifset
+@ifset SCORE
+
+@emph{Target SCORE options:}
+ [@b{-EB}][@b{-EL}][@b{-FIXDD}][@b{-NWARN}]
+ [@b{-SCORE5}][@b{-SCORE5U}][@b{-SCORE7}][@b{-SCORE3}]
+ [@b{-march=score7}][@b{-march=score3}]
+ [@b{-USE_R1}][@b{-KPIC}][@b{-O0}][@b{-G} @var{num}][@b{-V}]
+@end ifset
@ifset SPARC
@emph{Target SPARC options:}
@table @gcctabopt
@include at-file.texi
-@item -a[cdhlmns]
+@item -a[cdghlmns]
Turn on listings, in any of a variety of ways:
@table @gcctabopt
@item -ad
omit debugging directives
+@item -ag
+include general information, like @value{AS} version and options passed
+
@item -ah
include high-level source
@item -m16c
Assemble M16C instructions (the default).
+@item -relax
+Enable support for link-time relaxations.
+
+@item -h-tick-hex
+Support H'00 style hex constants in addition to 0x00 style.
+
@end table
@end ifset
See the info pages for documentation of the MMIX-specific options.
@end ifset
+@ifset S390
+The following options are available when @value{AS} is configured for the s390
+processor family.
+
+@table @gcctabopt
+@item -m31
+@itemx -m64
+Select the word size, either 31/32 bits or 64 bits.
+@item -mesa
+@item -mzarch
+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}, or @samp{z10}.
+@item -mregnames
+@itemx -mno-regnames
+Allow or disallow symbolic names for registers.
+@item -mwarn-areg-zero
+Warn whenever the operand for a base or index register has been specified
+but evaluates to zero.
+@end table
+@end ifset
+
@ifset XTENSA
The following options are available when @value{AS} is configured for
an Xtensa processor.
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.
+
+@item --rename-section @var{oldname}=@var{newname}
+When generating output sections, rename the @var{oldname} section to
+@var{newname}.
@end table
@end ifset
@c man end
@menu
-* a:: -a[cdhlns] enable listings
+* a:: -a[cdghlns] enable listings
* alternate:: --alternate enable alternate macro syntax
* D:: -D for compatibility
* f:: -f to work faster
@end menu
@node a
-@section Enable Listings: @option{-a[cdhlns]}
+@section Enable Listings: @option{-a[cdghlns]}
@kindex -a
@kindex -ac
@kindex -ad
+@kindex -ag
@kindex -ah
@kindex -al
@kindex -an
@samp{-g} be used, and that assembly listings (@samp{-al}) be requested
also.
+Use the @samp{-ag} option to print a first section with general assembly
+information, like @value{AS} version, switches passed, or time stamp.
+
Use the @samp{-ac} option to omit false conditionals from a listing. Any lines
which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any
other conditional), or a true @code{.if} followed by an @code{.else}, will be
@ifset PPC
@samp{#} for Motorola PowerPC;
@end ifset
+@ifset S390
+@samp{#} for IBM S/390;
+@end ifset
+@ifset SCORE
+@samp{#} for the Sunplus SCORE;
+@end ifset
@ifset SH
@samp{!} for the Renesas / SuperH SH;
@end ifset
equals sign @samp{=}@samp{=} here represents an equivalent of the
@code{.eqv} directive. @xref{Eqv,,@code{.eqv}}.
+@ifset Blackfin
+Blackfin does not support symbol assignment with @samp{=}.
+@end ifset
+
@node Symbol Names
@section Symbol Names
the same local label.
Dollar labels are defined in exactly the same way as ordinary local labels,
-except that instead of being terminated by a colon, they are terminated by a
-dollar sign, e.g., @samp{@b{55$}}.
+except that they have a dollar sign suffix to their numeric value, e.g.,
+@samp{@b{55$:}}.
They can also be distinguished from ordinary local labels by their transformed
names which use ASCII character @samp{\001} (control-A) as the magic character
@command{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
.long .} defines @code{melvin} to contain its own address.
Assigning a value to @code{.} is treated the same as a @code{.org}
-directive. Thus, the expression @samp{.=.+4} is the same as saying
+directive.
@ifclear no-space-dir
+Thus, the expression @samp{.=.+4} is the same as saying
@samp{.space 4}.
@end ifclear
@menu
* Abort:: @code{.abort}
@ifset COFF
-* ABORT (COFF):: @code{.ABORT}
+* ABORT (COFF):: @code{.ABORT}
@end ifset
* Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
* 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 [simple]}, @code{.cfi_endproc}, etc.
-
+* Comm:: @code{.comm @var{symbol} , @var{length} }
* Data:: @code{.data @var{subsection}}
@ifset COFF
* Def:: @code{.def @var{name}}
* Exitm:: @code{.exitm}
* Extern:: @code{.extern}
* Fail:: @code{.fail}
-@ifclear no-file-dir
-* File:: @code{.file @var{string}}
-@end ifclear
-
+* File:: @code{.file}
* Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
* Float:: @code{.float @var{flonums}}
* Func:: @code{.func}
* Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
@ifset ELF
+* Gnu_attribute:: @code{.gnu_attribute @var{tag},@var{value}}
* Hidden:: @code{.hidden @var{names}}
@end ifset
* Linkonce:: @code{.linkonce [@var{type}]}
* List:: @code{.list}
* Ln:: @code{.ln @var{line-number}}
-
-* LNS directives:: @code{.file}, @code{.loc}, etc.
+* Loc:: @code{.loc @var{fileno} @var{lineno}}
+* Loc_mark_labels:: @code{.loc_mark_labels @var{enable}}
+@ifset ELF
+* Local:: @code{.local @var{names}}
+@end ifset
* Long:: @code{.long @var{expressions}}
@ignore
* Scl:: @code{.scl @var{class}}
@end ifset
@ifset COFF-ELF
-* Section:: @code{.section @var{name}}
+* Section:: @code{.section @var{name}[, @var{flags}]}
@end ifset
* Set:: @code{.set @var{symbol}, @var{expression}}
@ifset COFF-ELF
* Size:: @code{.size [@var{name} , @var{expression}]}
@end ifset
-
+@ifclear no-space-dir
* Skip:: @code{.skip @var{size} , @var{fill}}
+@end ifclear
+
* Sleb128:: @code{.sleb128 @var{expressions}}
+@ifclear no-space-dir
* Space:: @code{.space @var{size} , @var{fill}}
+@end ifclear
@ifset have-stabs
* Stab:: @code{.stabd, .stabn, .stabs}
@end ifset
-* String:: @code{.string "@var{str}"}
+* String:: @code{.string "@var{str}"}, @code{.string8 "@var{str}"}, @code{.string16 "@var{str}"}, @code{.string32 "@var{str}"}, @code{.string64 "@var{str}"}
* Struct:: @code{.struct @var{expression}}
@ifset ELF
* SubSection:: @code{.subsection}
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
+For other systems, including ppc, i386 using a.out format, arm and
strongarm, it is the
number of low-order zero bits the location counter must have after
advancement. For example @samp{.align 3} advances the location
described later, which have a consistent behavior across all
architectures (but are specific to GAS).
+@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.
+
+@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 characters.
+
+@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 Ascii
@section @code{.ascii "@var{string}"}@dots{}
@code{.byte} expects zero or more expressions, separated by commas.
Each expression is assembled into the next byte.
-@node Comm
-@section @code{.comm @var{symbol} , @var{length} }
-
-@cindex @code{comm} directive
-@cindex symbol, common
-@code{.comm} declares a common symbol named @var{symbol}. When linking, a
-common symbol in one object file may be merged with a defined or common symbol
-of the same name in another object file. If @code{@value{LD}} does not see a
-definition for the symbol--just one or more common symbols--then it will
-allocate @var{length} bytes of uninitialized memory. @var{length} must be an
-absolute expression. If @code{@value{LD}} sees multiple common symbols with
-the same name, and they do not all have the same size, it will allocate space
-using the largest size.
-
-@ifset ELF
-When using ELF, the @code{.comm} directive takes an optional third argument.
-This is the desired alignment of the symbol, specified as a byte boundary (for
-example, an alignment of 16 means that the least significant 4 bits of the
-address should be zero). The alignment must be an absolute expression, and it
-must be a power of two. If @code{@value{LD}} allocates uninitialized memory
-for the common symbol, it will use the alignment when placing the symbol. If
-no alignment is specified, @command{@value{AS}} will set the alignment to the
-largest power of two less than or equal to the size of the symbol, up to a
-maximum of 16.
-@end ifset
-
-@ifset HPPA
-The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
-@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
-@end ifset
-
@node CFI directives
@section @code{.cfi_startproc [simple]}
@cindex @code{cfi_startproc} directive
data structures. Don't forget to close the function by
@code{.cfi_endproc}.
+@section @code{.cfi_sections @var{section_list}}
+@cindex @code{cfi_sections} directive
+@code{.cfi_sections} may be used to specify whether CFI directives
+should emit @code{.eh_frame} section and/or @code{.debug_frame} section.
+If @var{section_list} is @code{.eh_frame}, @code{.eh_frame} is emitted,
+if @var{section_list} is @code{.debug_frame}, @code{.debug_frame} is emitted.
+To emit both use @code{.eh_frame, .debug_frame}. The default if this
+directive is not used is @code{.cfi_sections .eh_frame}.
+
Unless @code{.cfi_startproc} is used along with parameter @code{simple}
it also emits some architecture dependent initial CFI instructions.
might use this to add OS-specific CFI opcodes, or generic CFI
opcodes that GAS does not yet support.
-@node LNS directives
-@section @code{.file @var{fileno} @var{filename}}
-@cindex @code{file} directive
-When emitting dwarf2 line number information @code{.file} assigns filenames
-to the @code{.debug_line} file name table. The @var{fileno} operand should
-be a unique positive integer to use as the index of the entry in the table.
-The @var{filename} operand is a C string literal.
-
-The detail of filename indices is exposed to the user because the filename
-table is shared with the @code{.debug_info} section of the dwarf2 debugging
-information, and thus the user must know the exact indices that table
-entries will have.
+@section @code{.cfi_val_encoded_addr @var{register}, @var{encoding}, @var{label}}
+The current value of @var{register} is @var{label}. The value of @var{label}
+will be encoded in the output file according to @var{encoding}; see the
+description of @code{.cfi_personality} for details on this encoding.
-@section @code{.loc @var{fileno} @var{lineno} [@var{column}] [@var{options}]}
-@cindex @code{loc} directive
-The @code{.loc} directive will add row to the @code{.debug_line} line
-number matrix corresponding to the immediately following assembly
-instruction. The @var{fileno}, @var{lineno}, and optional @var{column}
-arguments will be applied to the @code{.debug_line} state machine before
-the row is added.
+The usefulness of equating a register to a fixed label is probably
+limited to the return address register. Here, it can be useful to
+mark a code segment that has only one return address which is reached
+by a direct branch and no copy of the return address exists in memory
+or another register.
-The @var{options} are a sequence of the following tokens in any order:
-
-@table @code
-@item basic_block
-This option will set the @code{basic_block} register in the
-@code{.debug_line} state machine to @code{true}.
-
-@item prologue_end
-This option will set the @code{prologue_end} register in the
-@code{.debug_line} state machine to @code{true}.
-
-@item epilogue_begin
-This option will set the @code{epilogue_begin} register in the
-@code{.debug_line} state machine to @code{true}.
-
-@item is_stmt @var{value}
-This option will set the @code{is_stmt} register in the
-@code{.debug_line} state machine to @code{value}, which must be
-either 0 or 1.
+@node Comm
+@section @code{.comm @var{symbol} , @var{length} }
-@item isa @var{value}
-This directive will set the @code{isa} register in the @code{.debug_line}
-state machine to @var{value}, which must be an unsigned integer.
+@cindex @code{comm} directive
+@cindex symbol, common
+@code{.comm} declares a common symbol named @var{symbol}. When linking, a
+common symbol in one object file may be merged with a defined or common symbol
+of the same name in another object file. If @code{@value{LD}} does not see a
+definition for the symbol--just one or more common symbols--then it will
+allocate @var{length} bytes of uninitialized memory. @var{length} must be an
+absolute expression. If @code{@value{LD}} sees multiple common symbols with
+the same name, and they do not all have the same size, it will allocate space
+using the largest size.
-@end table
+@ifset COFF-ELF
+When using ELF or (as a GNU extension) PE, the @code{.comm} directive takes
+an optional third argument. This is the desired alignment of the symbol,
+specified for ELF as a byte boundary (for example, an alignment of 16 means
+that the least significant 4 bits of the address should be zero), and for PE
+as a power of two (for example, an alignment of 5 means aligned to a 32-byte
+boundary). The alignment must be an absolute expression, and it must be a
+power of two. If @code{@value{LD}} allocates uninitialized memory for the
+common symbol, it will use the alignment when placing the symbol. If no
+alignment is specified, @command{@value{AS}} will set the alignment to the
+largest power of two less than or equal to the size of the symbol, up to a
+maximum of 16 on ELF, or the default section alignment of 4 on PE@footnote{This
+is not the same as the executable image file alignment controlled by @code{@value{LD}}'s
+@samp{--section-alignment} option; image file sections in PE are aligned to
+multiples of 4096, which is far too large an alignment for ordinary variables.
+It is rather the default alignment for (non-debug) sections within object
+(@samp{*.o}) files, which are less strictly aligned.}.
+@end ifset
-@section @code{.loc_mark_blocks @var{enable}}
-@cindex @code{loc_mark_blocks} directive
-The @code{.loc_mark_blocks} directive makes the assembler emit an entry
-to the @code{.debug_line} line number matrix with the @code{basic_block}
-register in the state machine set whenever a code label is seen.
-The @var{enable} argument should be either 1 or 0, to enable or disable
-this function respectively.
+@ifset HPPA
+The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
+@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
+@end ifset
@node Data
@section @code{.data @var{subsection}}
include the value of @var{expression}. This can occasionally be useful inside
complex nested macros or conditional assembly.
-@ifclear no-file-dir
@node File
-@section @code{.file @var{string}}
-
+@section @code{.file}
@cindex @code{file} directive
+
+@ifclear no-file-dir
+There are two different versions of the @code{.file} directive. Targets
+that support DWARF2 line number information use the DWARF2 version of
+@code{.file}. Other targets use the default version.
+
+@subheading Default Version
+
@cindex logical file name
@cindex file name, logical
-@code{.file} tells @command{@value{AS}} that we are about to start a new logical
-file. @var{string} is the new file name. In general, the filename is
+This version of the @code{.file} directive tells @command{@value{AS}} that we
+are about to start a new logical file. The syntax is:
+
+@smallexample
+.file @var{string}
+@end smallexample
+
+@var{string} is the new file name. In general, the filename is
recognized whether or not it is surrounded by quotes @samp{"}; but if you wish
to specify an empty file name, you must give the quotes--@code{""}. This
statement may go away in future: it is only recognized to be compatible with
old @command{@value{AS}} programs.
+
+@subheading DWARF2 Version
@end ifclear
+When emitting DWARF2 line number information, @code{.file} assigns filenames
+to the @code{.debug_line} file name table. The syntax is:
+
+@smallexample
+.file @var{fileno} @var{filename}
+@end smallexample
+
+The @var{fileno} operand should be a unique positive integer to use as the
+index of the entry in the table. The @var{filename} operand is a C string
+literal.
+
+The detail of filename indices is exposed to the user because the filename
+table is shared with the @code{.debug_info} section of the DWARF2 debugging
+information, and thus the user must know the exact indices that table
+entries will have.
+
@node Fill
@section @code{.fill @var{repeat} , @var{size} , @var{value}}
@end ifset
@ifset ELF
+@node Gnu_attribute
+@section @code{.gnu_attribute @var{tag},@var{value}}
+Record a @sc{gnu} object attribute for this file. @xref{Object Attributes}.
+
@node Hidden
@section @code{.hidden @var{names}}
@section @code{.line @var{line-number}}
@cindex @code{line} directive
-@end ifclear
-@ifset no-line-dir
-@node Ln
-@section @code{.ln @var{line-number}}
-
-@cindex @code{ln} directive
-@end ifset
@cindex logical line number
@ifset aout-bout
Change the logical line number. @var{line-number} must be an absolute
reported as on logical line number @var{line-number} @minus{} 1. One day
@command{@value{AS}} will no longer support this directive: it is recognized only
for compatibility with existing assembler programs.
-
@end ifset
-@ifclear no-line-dir
Even though this is a directive associated with the @code{a.out} or
@code{b.out} object-code formats, @command{@value{AS}} still recognizes it
when producing COFF output, and treats @samp{.line} as though it
Warn if any of the duplicates do not have exactly the same contents.
@end table
+@node List
+@section @code{.list}
+
+@cindex @code{list} directive
+@cindex listing control, turning on
+Control (in conjunction with the @code{.nolist} directive) whether or
+not assembly listings are generated. These two directives maintain an
+internal counter (which is zero initially). @code{.list} increments the
+counter, and @code{.nolist} decrements it. Assembly listings are
+generated whenever the counter is greater than zero.
+
+By default, listings are disabled. When you enable them (with the
+@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
+the initial value of the listing counter is one.
+
@node Ln
@section @code{.ln @var{line-number}}
@end ifset
@end ifset
-@node MRI
-@section @code{.mri @var{val}}
+@node Loc
+@section @code{.loc @var{fileno} @var{lineno} [@var{column}] [@var{options}]}
+@cindex @code{loc} directive
+When emitting DWARF2 line number information,
+the @code{.loc} directive will add a row to the @code{.debug_line} line
+number matrix corresponding to the immediately following assembly
+instruction. The @var{fileno}, @var{lineno}, and optional @var{column}
+arguments will be applied to the @code{.debug_line} state machine before
+the row is added.
-@cindex @code{mri} directive
-@cindex MRI mode, temporarily
-If @var{val} is non-zero, this tells @command{@value{AS}} to enter MRI mode. If
-@var{val} is zero, this tells @command{@value{AS}} to exit MRI mode. This change
-affects code assembled until the next @code{.mri} directive, or until the end
-of the file. @xref{M, MRI mode, MRI mode}.
+The @var{options} are a sequence of the following tokens in any order:
-@node List
-@section @code{.list}
+@table @code
+@item basic_block
+This option will set the @code{basic_block} register in the
+@code{.debug_line} state machine to @code{true}.
-@cindex @code{list} directive
-@cindex listing control, turning on
-Control (in conjunction with the @code{.nolist} directive) whether or
-not assembly listings are generated. These two directives maintain an
-internal counter (which is zero initially). @code{.list} increments the
-counter, and @code{.nolist} decrements it. Assembly listings are
-generated whenever the counter is greater than zero.
+@item prologue_end
+This option will set the @code{prologue_end} register in the
+@code{.debug_line} state machine to @code{true}.
-By default, listings are disabled. When you enable them (with the
-@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
-the initial value of the listing counter is one.
+@item epilogue_begin
+This option will set the @code{epilogue_begin} register in the
+@code{.debug_line} state machine to @code{true}.
+
+@item is_stmt @var{value}
+This option will set the @code{is_stmt} register in the
+@code{.debug_line} state machine to @code{value}, which must be
+either 0 or 1.
+
+@item isa @var{value}
+This directive will set the @code{isa} register in the @code{.debug_line}
+state machine to @var{value}, which must be an unsigned integer.
+
+@item discriminator @var{value}
+This directive will set the @code{discriminator} register in the @code{.debug_line}
+state machine to @var{value}, which must be an unsigned integer.
+
+@end table
+
+@node Loc_mark_labels
+@section @code{.loc_mark_labels @var{enable}}
+@cindex @code{loc_mark_labels} directive
+When emitting DWARF2 line number information,
+the @code{.loc_mark_labels} directive makes the assembler emit an entry
+to the @code{.debug_line} line number matrix with the @code{basic_block}
+register in the state machine set whenever a code label is seen.
+The @var{enable} argument should be either 1 or 0, to enable or disable
+this function respectively.
+
+@ifset ELF
+@node Local
+@section @code{.local @var{names}}
+
+@cindex @code{local} directive
+This directive, which is available for ELF targets, marks each symbol in
+the comma-separated list of @code{names} as a local symbol so that it
+will not be externally visible. If the symbols do not already exist,
+they will be created.
+
+For targets where the @code{.lcomm} directive (@pxref{Lcomm}) does not
+accept an alignment argument, which is the case for most ELF targets,
+the @code{.local} directive can be used in combination with @code{.comm}
+(@pxref{Comm}) to define aligned local common data.
+@end ifset
@node Long
@section @code{.long @var{expressions}}
@xref{Altmacro,,@code{.altmacro}}.
@end ftable
-@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.
-
-@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 characters.
-
-@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!}.
+@node MRI
+@section @code{.mri @var{val}}
-@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
+@cindex @code{mri} directive
+@cindex MRI mode, temporarily
+If @var{val} is non-zero, this tells @command{@value{AS}} to enter MRI mode. If
+@var{val} is zero, this tells @command{@value{AS}} to exit MRI mode. This change
+affects code assembled until the next @code{.mri} directive, or until the end
+of the file. @xref{M, MRI mode, MRI mode}.
@node Noaltmacro
@section @code{.noaltmacro}
the endianness of the processor). If it skips 1 or 3 bytes, the fill value is
undefined.
+@ifset ELF
+@node PopSection
+@section @code{.popsection}
+
+@cindex @code{popsection} directive
+@cindex Section Stack
+This is one of the ELF section stack manipulation directives. The others are
+@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}),
+@code{.pushsection} (@pxref{PushSection}), and @code{.previous}
+(@pxref{Previous}).
+
+This directive replaces the current section (and subsection) with the top
+section (and subsection) on the section stack. This section is popped off the
+stack.
+@end ifset
+
@ifset ELF
@node Previous
@section @code{.previous}
(@pxref{PopSection}).
This directive swaps the current section (and subsection) with most recently
-referenced section (and subsection) prior to this one. Multiple
+referenced section/subsection pair prior to this one. Multiple
@code{.previous} directives in a row will flip between two sections (and their
-subsections).
+subsections). For example:
-In terms of the section stack, this directive swaps the current section with
-the top section on the section stack.
-@end ifset
+@smallexample
+.section A
+ .subsection 1
+ .word 0x1234
+ .subsection 2
+ .word 0x5678
+.previous
+ .word 0x9abc
+@end smallexample
-@ifset ELF
-@node PopSection
-@section @code{.popsection}
+Will place 0x1234 and 0x9abc into subsection 1 and 0x5678 into subsection 2 of
+section A. Whilst:
-@cindex @code{popsection} directive
-@cindex Section Stack
-This is one of the ELF section stack manipulation directives. The others are
-@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}),
-@code{.pushsection} (@pxref{PushSection}), and @code{.previous}
-(@pxref{Previous}).
+@smallexample
+.section A
+.subsection 1
+ # Now in section A subsection 1
+ .word 0x1234
+.section B
+.subsection 0
+ # Now in section B subsection 0
+ .word 0x5678
+.subsection 1
+ # Now in section B subsection 1
+ .word 0x9abc
+.previous
+ # Now in section B subsection 0
+ .word 0xdef0
+@end smallexample
-This directive replaces the current section (and subsection) with the top
-section (and subsection) on the section stack. This section is popped off the
-stack.
+Will place 0x1234 into section A, 0x5678 and 0xdef0 into subsection 0 of
+section B and 0x9abc into subsection 1 of section B.
+
+In terms of the section stack, this directive swaps the current section with
+the top section on the section stack.
@end ifset
@node Print
@ifset ELF
@node PushSection
-@section @code{.pushsection @var{name} , @var{subsection}}
+@section @code{.pushsection @var{name} [, @var{subsection}] [, "@var{flags}"[, @@@var{type}[,@var{arguments}]]]}
@cindex @code{pushsection} directive
@cindex Section Stack
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}.
+subsection with @code{name} and @code{subsection}. The optional
+@code{flags}, @code{type} and @code{arguments} are treated the same
+as in the @code{.section} (@pxref{Section}) directive.
@end ifset
@node Quad
@smallexample
.section @var{name}[, "@var{flags}"]
-.section @var{name}[, @var{subsegment}]
+.section @var{name}[, @var{subsection}]
@end smallexample
If the optional argument is quoted, it is taken as flags to use for the
shared section (meaningful for PE targets)
@item a
ignored. (For compatibility with the ELF version)
+@item y
+section is not readable (meaningful for PE targets)
@end table
If no flags are specified, the default flags depend upon the section name. If
will be as if no flags had been specified at all.
If the optional argument to the @code{.section} directive is not quoted, it is
-taken as a subsegment number (@pxref{Sub-Sections}).
+taken as a subsection number (@pxref{Sub-Sections}).
@end ifset
@ifset ELF
@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.
+absolute expression. For sections with both @code{M} and @code{S}, a string
+which is a suffix of a larger string is considered a duplicate. Thus
+@code{"def"} will be merged with @code{"abcdef"}; A reference to the first
+@code{"def"} will be changed to a reference to @code{"abcdef"+3}.
If @var{flags} contains the @code{G} symbol then the @var{type} argument must
be present along with an additional field like this:
@end ifset
@end ifset
-@node Sleb128
-@section @code{.sleb128 @var{expressions}}
-
-@cindex @code{sleb128} directive
-@var{sleb128} stands for ``signed little endian base 128.'' This is a
-compact, variable length representation of numbers used by the DWARF
-symbolic debugging format. @xref{Uleb128, ,@code{.uleb128}}.
-
@ifclear no-space-dir
@node Skip
@section @code{.skip @var{size} , @var{fill}}
@var{size} and @var{fill} are absolute expressions. If the comma and
@var{fill} are omitted, @var{fill} is assumed to be zero. This is the same as
@samp{.space}.
+@end ifclear
+
+@node Sleb128
+@section @code{.sleb128 @var{expressions}}
+@cindex @code{sleb128} directive
+@var{sleb128} stands for ``signed little endian base 128.'' This is a
+compact, variable length representation of numbers used by the DWARF
+symbolic debugging format. @xref{Uleb128, ,@code{.uleb128}}.
+
+@ifclear no-space-dir
@node Space
@section @code{.space @var{size} , @var{fill}}
@c end have-stabs
@node String
-@section @code{.string} "@var{str}"
+@section @code{.string} "@var{str}", @code{.string8} "@var{str}", @code{.string16}
+"@var{str}", @code{.string32} "@var{str}", @code{.string64} "@var{str}"
@cindex string, copying to object file
+@cindex string8, copying to object file
+@cindex string16, copying to object file
+@cindex string32, copying to object file
+@cindex string64, copying to object file
@cindex @code{string} directive
+@cindex @code{string8} directive
+@cindex @code{string16} directive
+@cindex @code{string32} directive
+@cindex @code{string64} directive
Copy the characters in @var{str} to the object file. You may specify more than
one string to copy, separated by commas. Unless otherwise specified for a
particular machine, the assembler marks the end of each string with a 0 byte.
You can use any of the escape sequences described in @ref{Strings,,Strings}.
+The variants @code{string16}, @code{string32} and @code{string64} differ from
+the @code{string} pseudo opcode in that each 8-bit character from @var{str} is
+copied and expanded to 16, 32 or 64 bits respectively. The expanded characters
+are stored in target endianness byte order.
+
+Example:
+@smallexample
+ .string32 "BYE"
+expands to:
+ .string "B\0\0\0Y\0\0\0E\0\0\0" /* On little endian targets. */
+ .string "\0\0\0B\0\0\0Y\0\0\0E" /* On big endian targets. */
+@end smallexample
+
+
@node Struct
@section @code{.struct @var{expression}}
The syntaxes supported are:
@smallexample
- .type <name> STT_FUNCTION
- .type <name> STT_OBJECT
+ .type <name> STT_<TYPE_IN_UPPER_CASE>
+ .type <name>,#<type>
+ .type <name>,@@<type>
+ .type <name>,%<type>
+ .type <name>,"<type>"
+@end smallexample
- .type <name>,#function
- .type <name>,#object
+The types supported are:
- .type <name>,@@function
- .type <name>,@@object
+@table @gcctabopt
+@item STT_FUNC
+@itemx function
+Mark the symbol as being a function name.
+
+@item STT_GNU_IFUNC
+@itemx gnu_indirect_function
+Mark the symbol as an indirect function when evaluated during reloc
+processing. (This is only supported on Linux targeted assemblers).
+
+@item STT_OBJECT
+@itemx object
+Mark the symbol as being a data object.
+
+@item STT_TLS
+@itemx tls_object
+Mark the symbol as being a thead-local data object.
+
+@item STT_COMMON
+@itemx common
+Mark the symbol as being a common data object.
+
+@item STT_NOTYPE
+@itemx notype
+Does not mark the symbol in any way. It is supported just for completeness.
+
+@item gnu_unique_object
+Marks the symbol as being a globally unique data object. The dynamic linker
+will make sure that in the entire process there is just one symbol with this
+name and type in use. (This is only supported on Linux targeted assemblers).
+
+@end table
+
+Note: Some targets support extra types in addition to those listed above.
- .type <name>,%function
- .type <name>,%object
-
- .type <name>,"function"
- .type <name>,"object"
-@end smallexample
@end ifset
@end ifset
@item .line
@end table
+@ifset ELF
+@node Object Attributes
+@chapter Object Attributes
+@cindex object attributes
+
+@command{@value{AS}} assembles source files written for a specific architecture
+into object files for that architecture. But not all object files are alike.
+Many architectures support incompatible variations. For instance, floating
+point arguments might be passed in floating point registers if the object file
+requires hardware floating point support---or floating point arguments might be
+passed in integer registers if the object file supports processors with no
+hardware floating point unit. Or, if two objects are built for different
+generations of the same architecture, the combination may require the
+newer generation at run-time.
+
+This information is useful during and after linking. At link time,
+@command{@value{LD}} can warn about incompatible object files. After link
+time, tools like @command{gdb} can use it to process the linked file
+correctly.
+
+Compatibility information is recorded as a series of object attributes. Each
+attribute has a @dfn{vendor}, @dfn{tag}, and @dfn{value}. The vendor is a
+string, and indicates who sets the meaning of the tag. The tag is an integer,
+and indicates what property the attribute describes. The value may be a string
+or an integer, and indicates how the property affects this object. Missing
+attributes are the same as attributes with a zero value or empty string value.
+
+Object attributes were developed as part of the ABI for the ARM Architecture.
+The file format is documented in @cite{ELF for the ARM Architecture}.
+
+@menu
+* GNU Object Attributes:: @sc{gnu} Object Attributes
+* Defining New Object Attributes:: Defining New Object Attributes
+@end menu
+
+@node GNU Object Attributes
+@section @sc{gnu} Object Attributes
+
+The @code{.gnu_attribute} directive records an object attribute
+with vendor @samp{gnu}.
+
+Except for @samp{Tag_compatibility}, which has both an integer and a string for
+its value, @sc{gnu} attributes have a string value if the tag number is odd and
+an integer value if the tag number is even. The second bit (@code{@var{tag} &
+2} is set for architecture-independent attributes and clear for
+architecture-dependent ones.
+
+@subsection Common @sc{gnu} attributes
+
+These attributes are valid on all architectures.
+
+@table @r
+@item Tag_compatibility (32)
+The compatibility attribute takes an integer flag value and a vendor name. If
+the flag value is 0, the file is compatible with other toolchains. If it is 1,
+then the file is only compatible with the named toolchain. If it is greater
+than 1, the file can only be processed by other toolchains under some private
+arrangement indicated by the flag value and the vendor name.
+@end table
+
+@subsection MIPS Attributes
+
+@table @r
+@item Tag_GNU_MIPS_ABI_FP (4)
+The floating-point ABI used by this object file. The value will be:
+
+@itemize @bullet
+@item
+0 for files not affected by the floating-point ABI.
+@item
+1 for files using the hardware floating-point with a standard double-precision
+FPU.
+@item
+2 for files using the hardware floating-point ABI with a single-precision FPU.
+@item
+3 for files using the software floating-point ABI.
+@item
+4 for files using the hardware floating-point ABI with 64-bit wide
+double-precision floating-point registers and 32-bit wide general
+purpose registers.
+@end itemize
+@end table
+
+@subsection PowerPC Attributes
+
+@table @r
+@item Tag_GNU_Power_ABI_FP (4)
+The floating-point ABI used by this object file. The value will be:
+
+@itemize @bullet
+@item
+0 for files not affected by the floating-point ABI.
+@item
+1 for files using double-precision hardware floating-point ABI.
+@item
+2 for files using the software floating-point ABI.
+@item
+3 for files using single-precision hardware floating-point ABI.
+@end itemize
+
+@item Tag_GNU_Power_ABI_Vector (8)
+The vector ABI used by this object file. The value will be:
+
+@itemize @bullet
+@item
+0 for files not affected by the vector ABI.
+@item
+1 for files using general purpose registers to pass vectors.
+@item
+2 for files using AltiVec registers to pass vectors.
+@item
+3 for files using SPE registers to pass vectors.
+@end itemize
+@end table
+
+@node Defining New Object Attributes
+@section Defining New Object Attributes
+
+If you want to define a new @sc{gnu} object attribute, here are the places you
+will need to modify. New attributes should be discussed on the @samp{binutils}
+mailing list.
+
+@itemize @bullet
+@item
+This manual, which is the official register of attributes.
+@item
+The header for your architecture @file{include/elf}, to define the tag.
+@item
+The @file{bfd} support file for your architecture, to merge the attribute
+and issue any appropriate link warnings.
+@item
+Test cases in @file{ld/testsuite} for merging and link warnings.
+@item
+@file{binutils/readelf.c} to display your attribute.
+@item
+GCC, if you want the compiler to mark the attribute automatically.
+@end itemize
+
+@end ifset
+
@ifset GENERIC
@node Machine Dependencies
@chapter Machine Dependent Features
@ifset AVR
* AVR-Dependent:: AVR Dependent Features
@end ifset
-@ifset BFIN
-* BFIN-Dependent:: BFIN Dependent Features
+@ifset Blackfin
+* Blackfin-Dependent:: Blackfin Dependent Features
@end ifset
@ifset CR16
* CR16-Dependent:: CR16 Dependent Features
@ifset IP2K
* IP2K-Dependent:: IP2K Dependent Features
@end ifset
+@ifset LM32
+* LM32-Dependent:: LM32 Dependent Features
+@end ifset
@ifset M32C
* M32C-Dependent:: M32C Dependent Features
@end ifset
@ifset M68HC11
* M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features
@end ifset
+@ifset MICROBLAZE
+* MicroBlaze-Dependent:: MICROBLAZE Dependent Features
+@end ifset
@ifset MIPS
* MIPS-Dependent:: MIPS Dependent Features
@end ifset
@ifset PPC
* PPC-Dependent:: PowerPC Dependent Features
@end ifset
+@ifset S390
+* S/390-Dependent:: IBM S/390 Dependent Features
+@end ifset
+@ifset SCORE
+* SCORE-Dependent:: SCORE Dependent Features
+@end ifset
@ifset SPARC
* Sparc-Dependent:: SPARC Dependent Features
@end ifset
@include c-avr.texi
@end ifset
-@ifset BFIN
+@ifset Blackfin
@include c-bfin.texi
@end ifset
@include c-ip2k.texi
@end ifset
+@ifset LM32
+@include c-lm32.texi
+@end ifset
+
@ifset M32C
@include c-m32c.texi
@end ifset
@include c-m68hc11.texi
@end ifset
+@ifset MICROBLAZE
+@include c-microblaze.texi
+@end ifset
+
@ifset MIPS
@include c-mips.texi
@end ifset
@include c-ppc.texi
@end ifset
+@ifset S390
+@include c-s390.texi
+@end ifset
+
+@ifset SCORE
+@include c-score.texi
+@end ifset
+
@ifset SH
@include c-sh.texi
@include c-sh64.texi
Several engineers at Cygnus Support have also provided many small bug fixes and
configuration enhancements.
+Jon Beniston added support for the Lattice Mico32 architecture.
+
Many others have contributed large or small bugfixes and enhancements. If
you have contributed significant work and are not mentioned on this list, and
want to be, let us know. Some of the history has been lost; we are not
intentionally leaving anyone out.
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
@include fdl.texi
@node AS Index
projects / msp430-binutils.git / blobdiff