\input texinfo @c -*-Texinfo-*-
-@c Copyright (c) 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
+@c Copyright (c) 1991, 92, 93, 94, 95, 1996 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, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
+Copyright (C) 1991, 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@titlepage
@title Using @value{AS}
-@subtitle The GNU Assembler
+@subtitle The @sc{gnu} Assembler
@ifclear GENERIC
@subtitle for the @value{TARGET} family
@end ifclear
@sp 13
The Free Software Foundation Inc. thanks The Nice Computer
Company of Australia for loaning Dean Elsner to write the
-first (Vax) version of @code{as} for Project GNU.
+first (Vax) version of @code{as} for Project @sc{gnu}.
The proprietors, management and staff of TNCCA thank FSF for
distracting the boss while they got some work
done.
@tex
{\parskip=0pt
\hfill {\it Using {\tt @value{AS}}}\par
-\hfill Edited by Roland Pesch for Cygnus Support\par
+\hfill Edited by Cygnus Support\par
}
%"boxit" macro for figures:
%Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
* Expressions:: Expressions
* Pseudo Ops:: Assembler Directives
* Machine Dependencies:: Machine Dependent Features
+* Reporting Bugs:: Reporting Bugs
* Acknowledgements:: Who Did What
* Index:: Index
@end menu
@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 ] [ -f ] [ --help ]
- [ -I @var{dir} ] [ -J ] [ -K ] [ -L ] [ -o @var{objfile} ]
- [ -R ] [ --statistics ] [ -v ] [ -version ] [ --version ]
- [ -W ] [ -w ] [ -x ] [ -Z ]
+@value{AS} [ -a[dhlns][=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 ]
@ifset A29K
@c am29k has no machine-dependent assembler options
@end ifset
[ -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
@c HPPA has no machine-dependent assembler options (yet).
@end ifset
@ifset SPARC
- [ -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite | -bump ]
+@c The order here is important. See c-sparc.texi.
+ [ -Av6 | -Av7 | -Av8 | -Asparclite | -Av9 | -Av9a ]
+ [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ]
@end ifset
@ifset Z8000
@c Z8000 has no machine-dependent assembler options
Ignored. This option is accepted for script compatibility with calls to
other assemblers.
+@item --defsym @var{sym}=@var{value}
+Define the symbol @var{sym} to be @var{value} before assembling the input file.
+@var{value} must be an integer constant. As in C, a leading @samp{0x}
+indicates a hexadecimal value, and a leading @samp{0} indicates an octal value.
+
@item -f
``fast''---skip whitespace and comment preprocessing (assume source is
compiler output).
@end table
@end ifset
+@c start-sanitize-d10v
+@ifset D10V
+The following options are available when @value{AS} is configured for
+a D10V processor.
+@table @code
+@cindex D10V optimization
+@cindex optimization, D10V
+@item -O
+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
Intel 80960 processor.
@item -l
Shorten references to undefined symbols, to one word instead of two.
-@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040
-@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32
+@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060
+@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200
Specify what processor in the 68000 family is the target. The default
is normally the 68020, but this can be changed at configuration time.
for the SPARC architecture:
@table @code
-@item -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite
+@item -Av6 | -Av7 | -Av8 | -Asparclite | -Av9 | -Av9a
Explicitly select a variant of the SPARC architecture.
+@item -xarch=v8plus | -xarch=v8plusa
+For compatibility with the Solaris v9 assembler. These options are
+equivalent to -Av9 and -Av9a, respectively.
+
@item -bump
Warn when the assembler switches to another architecture.
@end table
@code{@value{AS}} ignores this option. It is accepted for compatibility with
the native tools.
+@need 900
@item --trap
@itemx --no-trap
@itemx --break
@end ifset
@end ifclear
-@c I think this is premature---pesch@cygnus.com, 17jan1991
+@c I think this is premature---doc@cygnus.com, 17jan1991
@ignore
Throughout this manual, we assume that you are running @dfn{GNU},
the portable operating system from the @dfn{Free Software
doesn't change the meaning of the source.
@c I added "con" prefix to "catenation" just to prove I can overcome my
-@c APL training... pesch@cygnus.com
+@c APL training... doc@cygnus.com
The source program is a concatenation of the text in all the files, in the
order specified.
information for the debugger.
@c link above to some info file(s) like the description of a.out.
-@c don't forget to describe GNU info as well as Unix lossage.
+@c don't forget to describe @sc{gnu} info as well as Unix lossage.
@node Errors
@section Error and Warning Messages
@cindex MRI compatibility mode
The @code{-M} or @code{--mri} option selects MRI compatibility mode. This
changes the syntax and pseudo-op handling of @code{@value{AS}} to make it
-compatible with the @code{ASM68K} assembler from Microtec Research. The exact
-nature of the MRI syntax will not be documented here; see the MRI manuals for
-more information. The purpose of this option is to permit assembling existing
-MRI assembler code using @code{@value{AS}}.
+compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the
+configured target) assembler from Microtec Research. The exact nature of the
+MRI syntax will not be documented here; see the MRI manuals for more
+information. Note in particular that the handling of macros and macro
+arguments is somewhat different. The purpose of this option is to permit
+assembling existing MRI assembler code using @code{@value{AS}}.
The MRI compatibility is not complete. Certain operations of the MRI assembler
depend upon its object file format, and can not be supported using other object
@itemize @bullet
@item global symbols in common section
-The MRI assembler supports common sections which are merged by the linker.
+The m68k MRI assembler supports common sections which are merged by the linker.
Other object file formats do not support this. @code{@value{AS}} handles
common sections by treating them as a single common symbol. It permits local
symbols to be defined within a common section, but it can not support global
@item complex relocations
-The MRI assembler supports relocations against a negated section address, and
+The MRI assemblers support relocations against a negated section address, and
relocations which combine the start addresses of two or more sections. These
are not support by other object file formats.
instead be specified using the @code{-e} option to the linker, or in a linker
script.
-@item @code{IDNT} and @code{NAME} pseudo-ops
+@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops
-The MRI @code{IDNT} and @code{NAME} pseudo-ops assign a module name to the
-output file. This is not supported by other object file formats.
+The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module
+name to the output file. This is not supported by other object file formats.
@item @code{ORG} pseudo-op
-The MRI @code{ORG} pseudo-op begins an absolute section at a given address.
-This differs from the usual @code{@value{AS}} @code{.org} pseudo-op, which
-changes the location within the current section. Absolute sections are not
-supported by other object file formats. The address of a section may be
+The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given
+address. This differs from the usual @code{@value{AS}} @code{.org} pseudo-op,
+which changes the location within the current section. Absolute sections are
+not supported by other object file formats. The address of a section may be
assigned within a linker script.
@end itemize
@item @code{FEQU} pseudo-op
-The @code{FEQU} pseudo-op is not supported.
+The m68k @code{FEQU} pseudo-op is not supported.
@item @code{NOOBJ} pseudo-op
-The @code{NOOBJ} pseudo-op is not supported.
+The m68k @code{NOOBJ} pseudo-op is not supported.
@item @code{OPT} branch control options
-The @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB},
+The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB},
@code{BRL}, and @code{BRW}---are ignored. @code{@value{AS}} automatically
relaxes all branches, whether forward or backward, to an appropriate size, so
these options serve no purpose.
@item @code{OPT} list control options
-The following @code{OPT} list control options are ignored: @code{C},
+The following m68k @code{OPT} list control options are ignored: @code{C},
@code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M},
@code{MEX}, @code{MC}, @code{MD}, @code{X}.
@item other @code{OPT} options
-The following @code{OPT} options are ignored: @code{NEST}, @code{O},
+The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O},
@code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}.
@item @code{OPT} @code{D} option is default
-The @code{OPT} @code{D} option is the default, unlike the MRI assembler.
+The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler.
@code{OPT NOD} may be used to turn it off.
@item @code{XREF} pseudo-op.
-The @code{XREF} pseudo-op is ignored.
+The m68k @code{XREF} pseudo-op is ignored.
+
+@item @code{.debug} pseudo-op
-@item macros
+The i960 @code{.debug} pseudo-op is not supported.
-Macros are not supported directly, but are supported by @code{gasp}.
+@item @code{.extended} pseudo-op
-@item @code{IFC}, @code{IFNC} pseudo-ops.
+The i960 @code{.extended} pseudo-op is not supported.
-The @code{IFC} and @code{IFNC} pseudo-ops are not supported directly, but are
-supported by @code{gasp}.
+@item @code{.list} pseudo-op.
-@item @code{IRP}, @code{IRPC}, @code{REPT}, @code{ENDR} pseudo-ops
+The various options of the i960 @code{.list} pseudo-op are not supported.
+
+@item @code{.optimize} pseudo-op
+
+The i960 @code{.optimize} pseudo-op is not supported.
+
+@item @code{.output} pseudo-op
+
+The i960 @code{.output} pseudo-op is not supported.
+
+@item @code{.setreal} pseudo-op
+
+The i960 @code{.setreal} pseudo-op is not supported.
-The repeating pseudo-ops are not supported directly, but are supported by
-@code{gasp}.
@end itemize
@node o
@cindex line comment character
Anything from the @dfn{line comment} character to the next newline
is considered a comment and is ignored. The line comment character is
+@ifset A29K
+@samp{;} for the AMD 29K family;
+@end ifset
@c start-sanitize-arc
@ifset ARC
@samp{;} on the ARC;
@end ifset
@c end-sanitize-arc
-@ifset VAX
-@samp{#} on the Vax;
-@end ifset
-@ifset I960
-@samp{#} on the i960;
-@end ifset
-@ifset SPARC
-@samp{!} on the SPARC;
-@end ifset
-@ifset M680X0
-@samp{|} on the 680x0;
-@end ifset
-@ifset A29K
-@samp{;} for the AMD 29K family;
-@end ifset
@ifset H8/300
@samp{;} for the H8/300 family;
@end ifset
@ifset HPPA
@samp{;} for the HPPA;
@end ifset
+@ifset I960
+@samp{#} on the i960;
+@end ifset
@ifset SH
@samp{!} for the Hitachi SH;
@end ifset
+@ifset SPARC
+@samp{!} on the SPARC;
+@end ifset
+@ifset M680X0
+@samp{|} on the 680x0;
+@end ifset
+@ifset VAX
+@samp{#} on the Vax;
+@end ifset
@ifset Z8000
@samp{!} for the Z8000;
@end ifset
@cindex instructions and directives
@cindex directives and instructions
@c "key symbol" is not used elsewhere in the document; seems pedantic to
-@c @defn{} it in that case, as was done previously... pesch@cygnus.com,
+@c @defn{} it in that case, as was done previously... doc@cygnus.com,
@c 13feb91.
A statement begins with zero or more labels, optionally followed by a
key symbol which determines what kind of statement it is. The key
@c @item \a
@c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
@c
-@item \b
@cindex @code{\b} (backspace character)
@cindex backspace (@code{\b})
+@item \b
Mnemonic for backspace; for ASCII this is octal code 010.
@c @item \e
@c Mnemonic for EOText; for ASCII this is octal code 004.
@c
-@item \f
@cindex @code{\f} (formfeed character)
@cindex formfeed (@code{\f})
+@item \f
Mnemonic for FormFeed; for ASCII this is octal code 014.
-@item \n
@cindex @code{\n} (newline character)
@cindex newline (@code{\n})
+@item \n
Mnemonic for newline; for ASCII this is octal code 012.
@c @item \p
@c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
@c
-@item \r
@cindex @code{\r} (carriage return character)
@cindex carriage return (@code{\r})
+@item \r
Mnemonic for carriage-Return; for ASCII this is octal code 015.
@c @item \s
@c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
@c other assemblers.
@c
-@item \t
@cindex @code{\t} (tab)
@cindex tab (@code{\t})
+@item \t
Mnemonic for horizontal Tab; for ASCII this is octal code 011.
@c @item \v
@c @item \x @var{digit} @var{digit} @var{digit}
@c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
@c
-@item \ @var{digit} @var{digit} @var{digit}
@cindex @code{\@var{ddd}} (octal character code)
@cindex octal character code (@code{\@var{ddd}})
+@item \ @var{digit} @var{digit} @var{digit}
An octal character code. The numeric code is 3 octal digits.
For compatibility with other Unix systems, 8 and 9 are accepted as digits:
for example, @code{\008} has the value 010, and @code{\009} the value 011.
-@ifset HPPA
-@item \@code{x} @var{hex-digit} @var{hex-digit}
-@cindex @code{\@var{xdd}} (hex character code)
-@cindex hex character code (@code{\@var{xdd}})
-A hex character code. The numeric code is 2 hexadecimal digits. Either
-upper or lower case @code{x} works.
-@end ifset
+@cindex @code{\@var{xd...}} (hex character code)
+@cindex hex character code (@code{\@var{xd...}})
+@item \@code{x} @var{hex-digits...}
+A hex character code. All trailing hex digits are combined. Either upper or
+lower case @code{x} works.
-@item \\
@cindex @code{\\} (@samp{\} character)
@cindex backslash (@code{\\})
+@item \\
Represents one @samp{\} character.
@c @item \'
@c (@xref{Characters,,Character Constants}.) to represent
@c a @samp{'}.
@c
-@item \"
@cindex @code{\"} (doublequote character)
@cindex doublequote (@code{\"})
+@item \"
Represents one @samp{"} character. Needed in strings to represent
this character, because an unescaped @samp{"} would end the string.
@ifset H8
One of the letters @samp{DFPRSX} (in upper or lower case).
@end ifset
-@ifset I960
-One of the letters @samp{DFT} (in upper or lower case).
-@end ifset
@ifset HPPA
The letter @samp{E} (upper case only).
@end ifset
+@ifset I960
+One of the letters @samp{DFT} (in upper or lower case).
+@end ifset
@end ifclear
@item
section-relative address.
@table @b
-@item ASSEMBLER-INTERNAL-LOGIC-ERROR!
@cindex assembler internal logic error
+@item ASSEMBLER-INTERNAL-LOGIC-ERROR!
An internal assembler logic error has been found. This means there is a
bug in the assembler.
-@item expr section
@cindex expr (internal section)
+@item expr section
The assembler stores complex expression internally as combinations of
symbols. When it needs to represent an expression as a symbol, it puts
it in the expr section.
Lowest Precedence
@table @code
-@item +
@cindex addition, permitted arguments
@cindex plus, permitted arguments
@cindex arguments for addition
+@item +
@dfn{Addition}. If either argument is absolute, the result has the section of
the other argument. You may not add together arguments from different
sections.
-@item -
@cindex subtraction, permitted arguments
@cindex minus, permitted arguments
@cindex arguments for subtraction
+@item -
@dfn{Subtraction}. If the right argument is absolute, the
result has the section of the left argument.
If both arguments are in the same section, the result is absolute.
* If:: @code{.if @var{absolute expression}}
* Include:: @code{.include "@var{file}"}
* Int:: @code{.int @var{expressions}}
+* Irp:: @code{.irp @var{symbol},@var{values}}@dots{}
+* Irpc:: @code{.irpc @var{symbol},@var{values}}@dots{}
* Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
* Lflags:: @code{.lflags}
@ifclear no-line-dir
@end ifclear
* Ln:: @code{.ln @var{line-number}}
+* Linkonce:: @code{.linkonce [@var{type}]}
* List:: @code{.list}
* Long:: @code{.long @var{expressions}}
@ignore
* Lsym:: @code{.lsym @var{symbol}, @var{expression}}
@end ignore
+* Macro:: @code{.macro @var{name} @var{args}}@dots{}
+* MRI:: @code{.mri @var{val}}
+
* Nolist:: @code{.nolist}
* Octa:: @code{.octa @var{bignums}}
* Org:: @code{.org @var{new-lc} , @var{fill}}
* P2align:: @code{.p2align @var{abs-expr} , @var{abs-expr}}
* Psize:: @code{.psize @var{lines}, @var{columns}}
* Quad:: @code{.quad @var{bignums}}
+* Rept:: @code{.rept @var{count}}
* Sbttl:: @code{.sbttl "@var{subheading}"}
@ifset COFF
* Scl:: @code{.scl @var{class}}
* Size:: @code{.size}
@end ifset
+* Skip:: @code{.skip @var{size} , @var{fill}}
* Space:: @code{.space @var{size} , @var{fill}}
@ifset have-stabs
* Stab:: @code{.stabd, .stabn, .stabs}
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.
+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.
The way the required alignment is specified varies from system to system.
-For the a29k, HPPA, m86k, m88k, w65, sparc, and i386 using ELF format,
+For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF
+format,
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
a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
@node Balign
-@section @code{.balign @var{abs-expr} , @var{abs-expr}}
+@section @code{.balign[wl] @var{abs-expr} , @var{abs-expr}}
@cindex padding the location counter given number of bytes
@cindex @code{balign} directive
the padding bytes. It (and the comma) may be omitted. If it is
omitted, the padding bytes are zero.
+@cindex @code{balignw} directive
+@cindex @code{balignl} directive
+The @code{.balignw} and @code{.balignl} directives are variants of the
+@code{.balign} directive. The @code{.balignw} directive treats the fill
+pattern as a two byte word value. The @code{.balignl} directives treats the
+fill pattern as a four byte longword value. For example, @code{.balignw
+4,0x368d} will align to a multiple of 4. If it skips two bytes, they will be
+filled in with the value 0x368d (the exact placement of the bytes depends upon
+the endianness of the processor). If it skips 1 or 3 bytes, the fill value is
+undefined.
+
@node Byte
@section @code{.byte @var{expressions}}
(which must be an @var{absolute expression}) is non-zero. The end of
the conditional section of code must be marked by @code{.endif}
(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
-alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
+alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}).
The following variants of @code{.if} are also supported:
@table @code
-@item .ifdef @var{symbol}
@cindex @code{ifdef} directive
+@item .ifdef @var{symbol}
Assembles the following section of code if the specified @var{symbol}
has been defined.
@ignore
-@item .ifeqs
@cindex @code{ifeqs} directive
+@item .ifeqs
Not yet implemented.
@end ignore
-@item .ifndef @var{symbol}
-@itemx ifnotdef @var{symbol}
@cindex @code{ifndef} directive
@cindex @code{ifnotdef} directive
+@item .ifndef @var{symbol}
+@itemx .ifnotdef @var{symbol}
Assembles the following section of code if the specified @var{symbol}
has not been defined. Both spelling variants are equivalent.
@end ifset
@end ifclear
+@node Irp
+@section @code{.irp @var{symbol},@var{values}}@dots{}
+
+@cindex @code{irp} directive
+Evaluate a sequence of statements assigning different values to @var{symbol}.
+The sequence of statements starts at the @code{.irp} directive, and is
+terminated by an @code{.endr} directive. For each @var{value}, @var{symbol} is
+set to @var{value}, and the sequence of statements is assembled. If no
+@var{value} is listed, the sequence of statements is assembled once, with
+@var{symbol} set to the null string. To refer to @var{symbol} within the
+sequence of statements, use @var{\symbol}.
+
+For example, assembling
+
+@example
+ .irp param,1,2,3
+ move d\param,sp@@-
+ .endr
+@end example
+
+is equivalent to assembling
+
+@example
+ move d1,sp@@-
+ move d2,sp@@-
+ move d3,sp@@-
+@end example
+
+@node Irpc
+@section @code{.irpc @var{symbol},@var{values}}@dots{}
+
+@cindex @code{irpc} directive
+Evaluate a sequence of statements assigning different values to @var{symbol}.
+The sequence of statements starts at the @code{.irpc} directive, and is
+terminated by an @code{.endr} directive. For each character in @var{value},
+@var{symbol} is set to the character, and the sequence of statements is
+assembled. If no @var{value} is listed, the sequence of statements is
+assembled once, with @var{symbol} set to the null string. To refer to
+@var{symbol} within the sequence of statements, use @var{\symbol}.
+
+For example, assembling
+
+@example
+ .irpc param,123
+ move d\param,sp@@-
+ .endr
+@end example
+
+is equivalent to assembling
+
+@example
+ move d1,sp@@-
+ move d2,sp@@-
+ move d3,sp@@-
+@end example
+
@node Lcomm
@section @code{.lcomm @var{symbol} , @var{length}}
debugging.
@end ifclear
+@node Linkonce
+@section @code{.linkonce [@var{type}]}
+@cindex COMDAT
+@cindex @code{linkonce} directive
+@cindex common sections
+Mark the current section so that the linker only includes a single copy of it.
+This may be used to include the same section in several different object files,
+but ensure that the linker will only include it once in the final output file.
+The @code{.linkonce} pseudo-op must be used for each instance of the section.
+Duplicate sections are detected based on the section name, so it should be
+unique.
+
+This directive is only supported by a few object file formats; as of this
+writing, the only object file format which supports it is the Portable
+Executable format used on Windows NT.
+
+The @var{type} argument is optional. If specified, it must be one of the
+following strings. For example:
+@smallexample
+.linkonce same_size
+@end smallexample
+Not all types may be supported on all object file formats.
+
+@table @code
+@item discard
+Silently discard duplicate sections. This is the default.
+
+@item one_only
+Warn if there are duplicate sections, but still keep only one copy.
+
+@item same_size
+Warn if any of the duplicates have different sizes.
+
+@item same_contents
+Warn if any of the duplicates do not have exactly the same contents.
+@end table
+
@node Ln
@section @code{.ln @var{line-number}}
@end ifset
@end ifset
+@node MRI
+@section @code{.mri @var{val}}
+
+@cindex @code{mri} directive
+@cindex MRI mode, temporarily
+If @var{val} is non-zero, this tells @code{@value{AS}} to enter MRI mode. If
+@var{val} is zero, this tells @code{@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 List
@section @code{.list}
The new symbol is not flagged as external.
@end ignore
+@node Macro
+@section @code{.macro}
+
+@cindex macros
+The commands @code{.macro} and @code{.endm} allow you to define macros that
+generate assembly output. For example, this definition specifies a macro
+@code{sum} that puts a sequence of numbers into memory:
+
+@example
+ .macro sum from=0, to=5
+ .long \from
+ .if \to-\from
+ sum "(\from+1)",\to
+ .endif
+ .endm
+@end example
+
+@noindent
+With that definition, @samp{SUM 0,5} is equivalent to this assembly input:
+
+@example
+ .long 0
+ .long 1
+ .long 2
+ .long 3
+ .long 4
+ .long 5
+@end example
+
+@ftable @code
+@item .macro @var{macname}
+@itemx .macro @var{macname} @var{macargs} @dots{}
+@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:
+
+@table @code
+@item .macro comm
+Begin the definition of a macro called @code{comm}, which takes no
+arguments.
+
+@item .macro plus1 p, p1
+@itemx .macro plus1 p p1
+Either statement begins the definition of a macro called @code{plus1},
+which takes two arguments; within the macro definition, write
+@samp{\p} or @samp{\p1} to evaluate the arguments.
+
+@item .macro reserve_str p1=0 p2
+Begin the definition of a macro called @code{reserve_str}, with two
+arguments. The first argument has a default value, but not the second.
+After the definition is complete, you can call the macro either as
+@samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to
+@var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str
+,@var{b}} (with @samp{\p1} evaluating as the default, in this case
+@samp{0}, and @samp{\p2} evaluating to @var{b}).
+@end table
+
+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}.
+
+@item .endm
+@cindex @code{endm} directive
+Mark the end of a macro definition.
+
+@item .exitm
+@cindex @code{exitm} directive
+Exit early from the current macro definition.
+
+@cindex number of macros executed
+@cindex macros, count executed
+@item \@@
+@code{@value{AS}} maintains a counter of how many macros it has
+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}.
+
+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
+@end ftable
+
@node Nolist
@section @code{.nolist}
@c double negative used below "not undefined" because this is a specific
@c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
-@c section. pesch@cygnus.com 18feb91
+@c section. doc@cygnus.com 18feb91
Because @code{@value{AS}} tries to assemble programs in one pass, @var{new-lc}
may not be undefined. If you really detest this restriction we eagerly await
a chance to share your improved assembler.
@var{fill} defaults to zero.
@node P2align
-@section @code{.p2align @var{abs-expr} , @var{abs-expr}}
+@section @code{.p2align[wl] @var{abs-expr} , @var{abs-expr}}
@cindex padding the location counter given a power of two
@cindex @code{p2align} directive
the padding bytes. It (and the comma) may be omitted. If it is
omitted, the padding bytes are zero.
+@cindex @code{p2alignw} directive
+@cindex @code{p2alignl} directive
+The @code{.p2alignw} and @code{.p2alignl} directives are variants of the
+@code{.p2align} directive. The @code{.p2alignw} directive treats the fill
+pattern as a two byte word value. The @code{.p2alignl} directives treats the
+fill pattern as a four byte longword value. For example, @code{.p2alignw
+2,0x368d} will align to a multiple of 4. If it skips two bytes, they will be
+filled in with the value 0x368d (the exact placement of the bytes depends upon
+the endianness of the processor). If it skips 1 or 3 bytes, the fill value is
+undefined.
+
@node Psize
@section @code{.psize @var{lines} , @var{columns}}
@cindex integer, 16-byte
@end ifset
+@node Rept
+@section @code{.rept @var{count}}
+
+@cindex @code{rept} directive
+Repeat the sequence of lines between the @code{.rept} directive and the next
+@code{.endr} directive @var{count} times.
+
+For example, assembling
+
+@example
+ .rept 3
+ .long 0
+ .endr
+@end example
+
+is equivalent to assembling
+
+@example
+ .long 0
+ .long 0
+ .long 0
+@end example
+
@node Sbttl
@section @code{.sbttl "@var{subheading}"}
@end ifset
@end ifset
-@ifset COFF
@node Section
-@section @code{.section @var{name}, @var{subsection}}
+@section @code{.section @var{name}}
@cindex @code{section} directive
-@cindex named section (COFF)
-@cindex COFF named section
-Assemble the following code into end of subsection numbered
-@var{subsection} in the COFF named section @var{name}. If you omit
-@var{subsection}, @code{@value{AS}} uses subsection number zero.
-@samp{.section .text} is equivalent to the @code{.text} directive;
-@samp{.section .data} is equivalent to the @code{.data} directive.
-@ifset GENERIC
+@cindex named section
+Use the @code{.section} directive to assemble the following code into a section
+named @var{name}.
+
This directive is only supported for targets that actually support arbitrarily
named sections; on @code{a.out} targets, for example, it is not accepted, even
-with a standard @code{a.out} section name as its parameter.
+with a standard @code{a.out} section name.
+
+@ifset COFF
+For COFF targets, the @code{.section} directive is used in one of the following
+ways:
+@smallexample
+.section @var{name}[, "@var{flags}"]
+.section @var{name}[, @var{subsegment}]
+@end smallexample
+
+If the optional argument is quoted, it is taken as flags to use for the
+section. Each flag is a single character. The following flags are recognized:
+@table @code
+@item b
+bss section (uninitialized data)
+@item n
+section is not loaded
+@item w
+writable section
+@item d
+data section
+@item x
+executable section
+@end table
+
+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 be
+loaded and writable.
+
+If the optional argument to the @code{.section} directive is not quoted, it is
+taken as a subsegment number (@pxref{Sub-Sections}).
@end ifset
+
+@ifset ELF
+For ELF targets, the @code{.section} directive is used like this:
+@smallexample
+.section @var{name}[, "@var{flags}"[, @@@var{type}]]
+@end smallexample
+The optional @var{flags} argument is a quoted string which may contain any
+combintion of the following characters:
+@table @code
+@item a
+section is allocatable
+@item w
+section is writable
+@item x
+section is executable
+@end table
+
+The optional @var{type} argument may contain one of the following constants:
+@table @code
+@item @@progbits
+section contains data
+@item @@nobits
+section does not contain data (i.e., section only occupies space)
+@end table
+
+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
+none of the above flags: it will not be allocated in memory, nor writable, nor
+executable. The section will contain data.
+
+For ELF targets, the assembler supports another type of @code{.section}
+directive for compatibility with the Solaris assembler:
+@smallexample
+.section "@var{name}"[, @var{flags}...]
+@end smallexample
+Note that the section name is quoted. There may be a sequence of comma
+separated flags:
+@table @code
+@item #alloc
+section is allocatable
+@item #write
+section is writable
+@item #execinstr
+section is executable
+@end table
@end ifset
@node Set
@end ifset
@ifclear no-space-dir
+@node Skip
+@section @code{.skip @var{size} , @var{fill}}
+
+@cindex @code{skip} directive
+@cindex filling memory
+This directive emits @var{size} bytes, each of value @var{fill}. Both
+@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}.
+
@node Space
@section @code{.space @var{size} , @var{fill}}
@cindex filling memory
This directive emits @var{size} bytes, each of value @var{fill}. Both
@var{size} and @var{fill} are absolute expressions. If the comma
-and @var{fill} are omitted, @var{fill} is assumed to be zero.
+and @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same
+as @samp{.skip}.
@ifset HPPA
@quotation
is the address of the location counter when the @code{.stabd} was
assembled.
-@item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
@cindex @code{stabn} directive
+@item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
The name of the symbol is set to the empty string @code{""}.
-@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
@cindex @code{stabs} directive
+@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
All five fields are specified.
@end table
@end ifset
subject, see the hardware manufacturer's manual.
@menu
+@ifset A29K
+* AMD29K-Dependent:: AMD 29K Dependent Features
+@end ifset
@c start-sanitize-arc
@ifset ARC
* ARC-Dependent:: ARC Dependent Features
@end ifset
@c end-sanitize-arc
-@ifset VAX
-* Vax-Dependent:: VAX Dependent Features
-@end ifset
-@ifset A29K
-* AMD29K-Dependent:: AMD 29K Dependent Features
+@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
@ifset HPPA
* HPPA-Dependent:: HPPA Dependent Features
@end ifset
-@ifset SH
-* SH-Dependent:: Hitachi SH Dependent Features
+@ifset I80386
+* i386-Dependent:: Intel 80386 Dependent Features
@end ifset
@ifset I960
* i960-Dependent:: Intel 80960 Dependent Features
@ifset M680X0
* M68K-Dependent:: M680x0 Dependent Features
@end ifset
+@ifset MIPS
+* MIPS-Dependent:: MIPS Dependent Features
+@end ifset
+@ifset SH
+* SH-Dependent:: Hitachi SH Dependent Features
+@end ifset
@ifset SPARC
* Sparc-Dependent:: SPARC Dependent Features
@end ifset
@ifset Z8000
* Z8000-Dependent:: Z8000 Dependent Features
@end ifset
-@ifset MIPS
-* MIPS-Dependent:: MIPS Dependent Features
-@end ifset
-@ifset I80386
-* i386-Dependent:: 80386 Dependent Features
+@ifset VAX
+* Vax-Dependent:: VAX Dependent Features
@end ifset
@end menu
@end ifset
@c end-sanitize-arc
-@ifset VAX
-@include c-vax.texi
-@end ifset
-
@ifset A29K
@include c-a29k.texi
@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
@end ifset
@include c-hppa.texi
@end ifset
-@ifset SH
-@include c-sh.texi
+@ifset I80386
+@include c-i386.texi
@end ifset
@ifset I960
@include c-m68k.texi
@end ifset
-@ignore
-@c FIXME! Stop ignoring when filled in.
-@node 32x32
-@chapter 32x32
-
-@section Options
-The 32x32 version of @code{@value{AS}} accepts a @samp{-m32032} option to
-specify thiat it is compiling for a 32032 processor, or a
-@samp{-m32532} to specify that it is compiling for a 32532 option.
-The default (if neither is specified) is chosen when the assembler
-is compiled.
-
-@section Syntax
-I don't know anything about the 32x32 syntax assembled by
-@code{@value{AS}}. Someone who undersands the processor (I've never seen
-one) and the possible syntaxes should write this section.
-
-@section Floating Point
-The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{AS}}
-only creates single or double precision values. I don't know if the
-32x32 understands extended precision numbers.
+@ifset MIPS
+@include c-mips.texi
+@end ifset
-@section 32x32 Machine Directives
-The 32x32 has no machine dependent directives.
+@ifset NS32K
+@include c-ns32k.texi
+@end ifset
-@end ignore
+@ifset SH
+@include c-sh.texi
+@end ifset
@ifset SPARC
@include c-sparc.texi
@end ifset
-@ifset I80386
-@include c-i386.texi
-@end ifset
-
@ifset Z8000
@include c-z8k.texi
@end ifset
-@ifset MIPS
-@include c-mips.texi
+@ifset VAX
+@include c-vax.texi
@end ifset
@ifset GENERIC
@raisesections
@end ifset
+@node Reporting Bugs
+@chapter Reporting Bugs
+@cindex bugs in @code{@value{AS}}
+@cindex reporting bugs in @code{@value{AS}}
+
+Your bug reports play an essential role in making @code{@value{AS}} reliable.
+
+Reporting a bug may help you by bringing a solution to your problem, or it may
+not. But in any case the principal function of a bug report is to help the
+entire community by making the next version of @code{@value{AS}} work better.
+Bug reports are your contribution to the maintenance of @code{@value{AS}}.
+
+In order for a bug report to serve its purpose, you must include the
+information that enables us to fix the bug.
+
+@menu
+* Bug Criteria:: Have you found a bug?
+* Bug Reporting:: How to report bugs
+@end menu
+
+@node Bug Criteria
+@section Have you found a bug?
+@cindex bug criteria
+
+If you are not sure whether you have found a bug, here are some guidelines:
+
+@itemize @bullet
+@cindex fatal signal
+@cindex assembler crash
+@cindex crash of assembler
+@item
+If the assembler gets a fatal signal, for any input whatever, that is a
+@code{@value{AS}} bug. Reliable assemblers never crash.
+
+@cindex error on valid input
+@item
+If @code{@value{AS}} produces an error message for valid input, that is a bug.
+
+@cindex invalid input
+@item
+If @code{@value{AS}} does not produce an error message for invalid input, that
+is a bug. However, you should note that your idea of ``invalid input'' might
+be our idea of ``an extension'' or ``support for traditional practice''.
+
+@item
+If you are an experienced user of assemblers, your suggestions for improvement
+of @code{@value{AS}} are welcome in any case.
+@end itemize
+
+@node Bug Reporting
+@section How to report bugs
+@cindex bug reports
+@cindex @code{@value{AS}} bugs, reporting
+
+A number of companies and individuals offer support for @sc{gnu} products. If
+you obtained @code{@value{AS}} from a support organization, we recommend you
+contact that organization first.
+
+You can find contact information for many support companies and
+individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
+distribution.
+
+In any event, we also recommend that you send bug reports for @code{@value{AS}}
+to @samp{bug-gnu-utils@@prep.ai.mit.edu}.
+
+The fundamental principle of reporting bugs usefully is this:
+@strong{report all the facts}. If you are not sure whether to state a
+fact or leave it out, state it!
+
+Often people omit facts because they think they know what causes the problem
+and assume that some details do not matter. Thus, you might assume that the
+name of a symbol you use in an example does not matter. Well, probably it does
+not, but one cannot be sure. Perhaps the bug is a stray memory reference which
+happens to fetch from the location where that name is stored in memory;
+perhaps, if the name were different, the contents of that location would fool
+the assembler into doing the right thing despite the bug. Play it safe and
+give a specific, complete example. That is the easiest thing for you to do,
+and the most helpful.
+
+Keep in mind that the purpose of a bug report is to enable us to fix the bug if
+it is new to us. Therefore, always write your bug reports on the assumption
+that the bug has not been reported previously.
+
+Sometimes people give a few sketchy facts and ask, ``Does this ring a
+bell?'' Those bug reports are useless, and we urge everyone to
+@emph{refuse to respond to them} except to chide the sender to report
+bugs properly.
+
+To enable us to fix the bug, you should include all these things:
+
+@itemize @bullet
+@item
+The version of @code{@value{AS}}. @code{@value{AS}} announces it if you start
+it with the @samp{--version} argument.
+
+Without this, we will not know whether there is any point in looking for
+the bug in the current version of @code{@value{AS}}.
+
+@item
+Any patches you may have applied to the @code{@value{AS}} source.
+
+@item
+The type of machine you are using, and the operating system name and
+version number.
+
+@item
+What compiler (and its version) was used to compile @code{@value{AS}}---e.g.
+``@code{gcc-2.7}''.
+
+@item
+The command arguments you gave the assembler to assemble your example and
+observe the bug. To guarantee you will not omit something important, list them
+all. A copy of the Makefile (or the output from make) is sufficient.
+
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
+
+@item
+A complete input file that will reproduce the bug. If the bug is observed when
+the assembler is invoked via a compiler, send the assembler source, not the
+high level language source. Most compilers will produce the assembler source
+when run with the @samp{-S} option. If you are using @code{@value{GCC}}, use
+the options @samp{-v --save-temps}; this will save the assembler source in a
+file with an extension of @file{.s}, and also show you exactly how
+@code{@value{AS}} is being run.
+
+@item
+A description of what behavior you observe that you believe is
+incorrect. For example, ``It gets a fatal signal.''
+
+Of course, if the bug is that @code{@value{AS}} gets a fatal signal, then we
+will certainly notice it. But if the bug is incorrect output, we might not
+notice unless it is glaringly wrong. You might as well not give us a chance to
+make a mistake.
+
+Even if the problem you experience is a fatal signal, you should still say so
+explicitly. Suppose something strange is going on, such as, your copy of
+@code{@value{AS}} is out of synch, or you have encountered a bug in the C
+library on your system. (This has happened!) Your copy might crash and ours
+would not. If you told us to expect a crash, then when ours fails to crash, we
+would know that the bug was not happening for us. If you had not told us to
+expect a crash, then we would not be able to draw any conclusion from our
+observations.
+
+@item
+If you wish to suggest changes to the @code{@value{AS}} source, send us context
+diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
+option. Always send diffs from the old file to the new file. If you even
+discuss something in the @code{@value{AS}} source, refer to it by context, not
+by line number.
+
+The line numbers in our development sources will not match those in your
+sources. Your line numbers would convey no useful information to us.
+@end itemize
+
+Here are some things that are not necessary:
+
+@itemize @bullet
+@item
+A description of the envelope of the bug.
+
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
+
+This is often time consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger
+with breakpoints, not by pure deduction from a series of examples.
+We recommend that you save your time for something else.
+
+Of course, if you can find a simpler example to report @emph{instead}
+of the original one, that is a convenience for us. Errors in the
+output will be easier to spot, running under the debugger will take
+less time, and so on.
+
+However, simplification is not vital; if you do not want to do this,
+report the bug anyway and send us the entire test case you used.
+
+@item
+A patch for the bug.
+
+A patch for the bug does help us if it is a good one. But do not omit
+the necessary information, such as the test case, on the assumption that
+a patch is all we need. We might see problems with your patch and decide
+to fix the problem another way, or we might not understand it at all.
+
+Sometimes with a program as complicated as @code{@value{AS}} it is very hard to
+construct an example that will make the program follow a certain path through
+the code. If you do not send us the example, we will not be able to construct
+one, so we will not be able to verify that the bug is fixed.
+
+And if we cannot understand what bug you are trying to fix, or why your
+patch should be an improvement, we will not install it. A test case will
+help us to understand.
+
+@item
+A guess about what the bug is or what it depends on.
+
+Such guesses are usually wrong. Even we cannot guess right about such
+things without first using the debugger to find the facts.
+@end itemize
+
@node Acknowledgements
@chapter Acknowledgements
If you have contributed to @code{@value{AS}} 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 (January 1994), the
-maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
+maintainer, and we'll correct the situation. Currently
+@c (January 1994),
+the maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any
more details?}
Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
-added support for MIPS ECOFF and ELF targets, and made a few other minor
-patches.
+added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and
+PowerPC assembler, and made a few other minor patches.
Steve Chamberlain made @code{@value{AS}} able to generate listings.
Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
and some initial 64-bit support).
+Richard Henderson rewrote the Alpha assembler.
+
Several engineers at Cygnus Support have also provided many small bug fixes and
configuration enhancements.
projects / deliverable / binutils-gdb.git / blobdiff