\input texinfo @c -*-Texinfo-*-
-@c Copyright (c) 1991, 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
+@c Copyright (c) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
@c UPDATE!! On future updates--
@c (1) check for new machine-dep cmdline options in
@c md_parse_option definitions in config/tc-*.c
@ifinfo
This file documents the GNU Assembler "@value{AS}".
-Copyright (C) 1991, 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
+Copyright (C) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1991, 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@c We don't use deffn and friends for the following because they seem
@c to be limited to one line for the header.
@smallexample
-@value{AS} [ -a[dhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ]
+@value{AS} [ -a[cdhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ]
[ -f ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ]
[ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ] [ -version ]
[ --version ] [ -W ] [ -w ] [ -x ] [ -Z ]
[ -mbig-endian | -mlittle-endian ]
@end ifset
@c end-sanitize-arc
-@c start-sanitize-d10v
@ifset D10V
[ -O ]
@end ifset
-@c end-sanitize-d10v
@ifset H8
@c Hitachi family chips have no machine-dependent assembler options
@end ifset
@ifset SPARC
@c The order here is important. See c-sparc.texi.
- [ -Av6 | -Av7 | -Av8 | -Asparclite | -Av9 | -Av9a ]
+ [ -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite | -Av9 | -Av9a ]
[ -xarch=v8plus | -xarch=v8plusa ] [ -bump ]
@end ifset
@ifset Z8000
@end table
@end ifset
-@c start-sanitize-d10v
@ifset D10V
The following options are available when @value{AS} is configured for
a D10V processor.
Optimize output by parallelizing instructions.
@end table
@end ifset
-@c end-sanitize-d10v
@ifset I960
The following options are available when @value{AS} is configured for the
for the SPARC architecture:
@table @code
-@item -Av6 | -Av7 | -Av8 | -Asparclite | -Av9 | -Av9a
+@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite | -Av9 | -Av9a
Explicitly select a variant of the SPARC architecture.
@item -xarch=v8plus | -xarch=v8plusa
assembler.)
@menu
-* a:: -a[dhlns] enable listings
+* a:: -a[cdhlns] enable listings
* D:: -D for compatibility
* f:: -f to work faster
* I:: -I for .include search path
* L:: -L to retain local labels
* M:: -M or --mri to assemble in MRI compatibility mode
+* MD:: --MD for dependency tracking
* o:: -o to name the object file
* R:: -R to join data and text sections
* statistics:: --statistics to see statistics about assembly
@end menu
@node a
-@section Enable Listings: @code{-a[dhlns]}
+@section Enable Listings: @code{-a[cdhlns]}
@kindex -a
+@kindex -ac
@kindex -ad
@kindex -ah
@kindex -al
@samp{-g} be used, and that assembly listings (@samp{-al}) be requested
also.
+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
+omitted from the listing.
+
Use the @samp{-ad} option to omit debugging directives from the
listing.
@end itemize
+@node MD
+@section Dependency tracking: @code{--MD}
+
+@kindex --MD
+@cindex dependency tracking
+@cindex make rules
+
+@code{@value{AS}} can generate a dependency file for the file it creates. This
+file consists of a single rule suitable for @code{make} describing the
+dependencies of the main source file.
+
+The rule is written to the file named in its argument.
+
+This feature is used in the automatic updating of makefiles.
+
@node o
@section Name the Object File: @code{-o}
your program starts running, all the contents of the bss
section are zeroed bytes.
-Addresses in the bss section are allocated with special directives; you
-may not assemble anything directly into the bss section. Hence there
-are no bss subsections. @xref{Comm,,@code{.comm}},
-@pxref{Lcomm,,@code{.lcomm}}.
+The @code{.lcomm} pseudo-op defines a symbol in the bss section; see
+@ref{Lcomm,,@code{.lcomm}}.
+
+The @code{.comm} pseudo-op may be used to declare a common symbol, which is
+another form of uninitialized symbol; see @xref{Comm,,@code{.comm}}.
+
+@ifset GENERIC
+When assembling for a target which supports multiple sections, such as ELF or
+COFF, you may switch into the @code{.bss} section and define symbols as usual;
+see @ref{Section,,@code{.section}}. You may only assemble zero values into the
+section. Typically the section will only contain symbol definitions and
+@code{.skip} directives (@pxref{Skip,,@code{.skip}}).
+@end ifset
@node Symbols
@chapter Symbols
If the label is written @samp{1:} then the digit is @samp{1}.
And so on up through @samp{9:}.
-@item @ctrl{A}
+@item @kbd{C-A}
This unusual character is included so you do not accidentally invent
a symbol of the same name. The character has ASCII value
@samp{\001}.
through @samp{9:}.
@end table
-For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
-@code{3:} is named @code{L3@ctrl{A}44}.
+For instance, the first @code{1:} is named @code{L1@kbd{C-A}1}, the 44th
+@code{3:} is named @code{L3@kbd{C-A}44}.
@node Dot
@section The Special Dot Symbol
* Endif:: @code{.endif}
* Equ:: @code{.equ @var{symbol}, @var{expression}}
+* Equiv:: @code{.equiv @var{symbol}, @var{expression}}
+* Err:: @code{.err}
* Extern:: @code{.extern}
@ifclear no-file-dir
* File:: @code{.file @var{string}}
@end ifset
* String:: @code{.string "@var{str}"}
+@ifset ELF
+* Symver:: @code{.symver @var{name},@var{name2@@nodename}}
+@end ifset
@ifset COFF
* Tag:: @code{.tag @var{structname}}
@end ifset
@end ifset
@node Align
-@section @code{.align @var{abs-expr} , @var{abs-expr}}
+@section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
@cindex padding the location counter
@cindex @code{align} directive
-Pad the location counter (in the current subsection) to a particular
-storage boundary. The first expression (which must be absolute) is the
-alignment required, as described below.
-The second expression (also absolute) gives the value to be stored in
-the padding bytes. It (and the comma) may be omitted. If it is
-omitted, the padding bytes are zero.
-For the alpha, if the section is marked as containing code and the
-padding expression is omitted, then the space is filled with no-ops.
+Pad the location counter (in the current subsection) to a particular storage
+boundary. The first expression (which must be absolute) is the alignment
+required, as described below.
+
+The second expression (also absolute) gives the fill value to be stored in the
+padding bytes. It (and the comma) may be omitted. If it is omitted, the
+padding bytes are normally zero. However, on some systems, if the section is
+marked as containing code and the fill value is omitted, the space is filled
+with no-op instructions.
+
+The third expression is also absolute, and is also optional. If it is present,
+it is the maximum number of bytes that should be skipped by this alignment
+directive. If doing the alignment would require skipping more bytes than the
+specified maximum, then the alignment is not done at all. You can omit the
+fill value (the second argument) entirely by simply using two commas after the
+required alignment; this can be useful if you want the alignment to be filled
+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, and Hitachi SH, and i386 using ELF
a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
@node Balign
-@section @code{.balign[wl] @var{abs-expr} , @var{abs-expr}}
+@section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
@cindex padding the location counter given number of bytes
@cindex @code{balign} directive
the location counter until it is a multiple of 8. If the location counter
is already a multiple of 8, no change is needed.
-The second expression (also absolute) gives the value to be stored in
-the padding bytes. It (and the comma) may be omitted. If it is
-omitted, the padding bytes are zero.
+The second expression (also absolute) gives the fill value to be stored in the
+padding bytes. It (and the comma) may be omitted. If it is omitted, the
+padding bytes are normally zero. However, on some systems, if the section is
+marked as containing code and the fill value is omitted, the space is filled
+with no-op instructions.
+
+The third expression is also absolute, and is also optional. If it is present,
+it is the maximum number of bytes that should be skipped by this alignment
+directive. If doing the alignment would require skipping more bytes than the
+specified maximum, then the alignment is not done at all. You can omit the
+fill value (the second argument) entirely by simply using two commas after the
+required alignment; this can be useful if you want the alignment to be filled
+with no-op instructions when appropriate.
@cindex @code{balignw} directive
@cindex @code{balignl} directive
@cindex @code{comm} directive
@cindex symbol, common
-@code{.comm} declares a named common area in the bss section. Normally
-@code{@value{LD}} reserves memory addresses for it during linking, so no partial
-program defines the location of the symbol. Use @code{.comm} to tell
-@code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}}
-allocates space for each @code{.comm} symbol that is at least as
-long as the longest @code{.comm} request in any of the partial programs
-linked. @var{length} is an absolute expression.
+@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, @code{@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} .equ @var{expression}}.
@end ifset
+@node Equiv
+@section @code{.equiv @var{symbol}, @var{expression}}
+@cindex @code{equiv} directive
+The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that
+the assembler will signal an error if @var{symbol} is already defined.
+
+Except for the contents of the error message, this is roughly equivalent to
+@smallexample
+.ifdef SYM
+.err
+.endif
+.equ SYM,VAL
+@end smallexample
+
+@node Err
+@section @code{.err}
+@cindex @code{err} directive
+If @code{@value{AS}} assembles a @code{.err} directive, it will print an error
+message and, unless the @code{-Z} option was used, it will not generate an
+object file. This can be used to signal error an conditionally compiled code.
+
@node Extern
@section @code{.extern}
is not declared global (@pxref{Global,,@code{.global}}), so is normally
not visible to @code{@value{LD}}.
+@ifset GENERIC
+Some targets permit a third argument to be used with @code{.lcomm}. This
+argument specifies the desired alignment of the symbol in the bss section.
+@end ifset
+
@ifset HPPA
The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
@samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
@var{fill} defaults to zero.
@node P2align
-@section @code{.p2align[wl] @var{abs-expr} , @var{abs-expr}}
+@section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
@cindex padding the location counter given a power of two
@cindex @code{p2align} directive
counter until it a multiple of 8. If the location counter is already a
multiple of 8, no change is needed.
-The second expression (also absolute) gives the value to be stored in
-the padding bytes. It (and the comma) may be omitted. If it is
-omitted, the padding bytes are zero.
+The second expression (also absolute) gives the fill value to be stored in the
+padding bytes. It (and the comma) may be omitted. If it is omitted, the
+padding bytes are normally zero. However, on some systems, if the section is
+marked as containing code and the fill value is omitted, the space is filled
+with no-op instructions.
+
+The third expression is also absolute, and is also optional. If it is present,
+it is the maximum number of bytes that should be skipped by this alignment
+directive. If doing the alignment would require skipping more bytes than the
+specified maximum, then the alignment is not done at all. You can omit the
+fill value (the second argument) entirely by simply using two commas after the
+required alignment; this can be useful if you want the alignment to be filled
+with no-op instructions when appropriate.
@cindex @code{p2alignw} directive
@cindex @code{p2alignl} directive
writable section
@item d
data section
+@item r
+read-only section
@item x
executable section
@end table
Set the value of @var{symbol} to @var{expression}. This
changes @var{symbol}'s value and type to conform to
@var{expression}. If @var{symbol} was flagged as external, it remains
-flagged. (@xref{Symbol Attributes}.)
+flagged (@pxref{Symbol Attributes}).
You may @code{.set} a symbol many times in the same assembly.
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}.
+@ifset ELF
+@node Symver
+@section @code{.symver}
+@cindex @code{symver} directive
+@cindex symbol versioning
+@cindex versions of symbols
+Use the @code{.symver} directive to bind symbols to specific version nodes
+within a source file. This is only supported on ELF platforms, and is
+typically used when assembling files to be linked into a shared library.
+There are cases where it may make sense to use this in objects to be bound
+into an application itself so as to override a versioned symbol from a
+shared library.
+
+For ELF targets, the @code{.symver} directive is used like this:
+@smallexample
+.symver @var{name}, @var{name2@@nodename}
+@end smallexample
+In this case, the symbol @var{name} must exist and be defined within the file
+being assembled. The @code{.versym} directive effectively creates a symbol
+alias with the name @var{name2@@nodename}, and in fact the main reason that we
+just don't try and create a regular alias is that the @var{@@} character isn't
+permitted in symbol names. The @var{name2} part of the name is the actual name
+of the symbol by which it will be externally referenced. The name @var{name}
+itself is merely a name of convenience that is used so that it is possible to
+have definitions for multiple versions of a function within a single source
+file, and so that the compiler can unambiguously know which version of a
+function is being mentioned. The @var{nodename} portion of the alias should be
+the name of a node specified in the version script supplied to the linker when
+building a shared library. If you are attempting to override a versioned
+symbol from a shared library, then @var{nodename} should correspond to the
+nodename of the symbol you are trying to override.
+@end ifset
+
@ifset COFF
@node Tag
@section @code{.tag @var{structname}}
* ARC-Dependent:: ARC Dependent Features
@end ifset
@c end-sanitize-arc
-@c start-sanitize-d10v
@ifset D10V
* D10V-Dependent:: D10V Dependent Features
@end ifset
-@c end-sanitize-d10v
@ifset H8/300
* H8/300-Dependent:: Hitachi H8/300 Dependent Features
@end ifset
@end ifclear
@end ifset
-@c start-sanitize-d10v
@ifset D10V
@include c-d10v.texi
@end ifset
-@c end-sanitize-d10v
@ifset H8/300
@include c-h8300.texi
Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
and some initial 64-bit support).
-Richard Henderson rewrote the Alpha assembler.
+Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD
+support for openVMS/Alpha.
Several engineers at Cygnus Support have also provided many small bug fixes and
configuration enhancements.
projects / deliverable / binutils-gdb.git / blobdiff