\input texinfo @c -*-Texinfo-*-
-@c Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 2000, 2001
+@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
+@c 2001
@c Free Software Foundation, Inc.
@c UPDATE!! On future updates--
@c (1) check for new machine-dep cmdline options in
@include asconfig.texi
@include gasver.texi
@c ---
+@c man begin NAME
+@ifset man
+@c Configure for the generation of man pages
+@set AS as
+@set TARGET TARGET
+@set GENERIC
+@set A29K
+@set ARC
+@set ARM
+@set D10V
+@set D30V
+@set H8/300
+@set H8/500
+@set HPPA
+@set I370
+@set I80386
+@set I860
+@set I960
+@set M32R
+@set M68HC11
+@set M680X0
+@set M880X0
+@set MCORE
+@set MIPS
+@set PDP11
+@set PJ
+@set SH
+@set SPARC
+@set C54X
+@set V850
+@set VAX
+@end ifset
+@c man end
@c common OR combinations of conditions
@ifset AOUT
@set aout-bout
@ifinfo
This file documents the GNU Assembler "@value{AS}".
+@c man begin COPYRIGHT
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 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
- 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
- section entitled "GNU Free Documentation License".
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+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
+section entitled "GNU Free Documentation License".
+
+@c man end
@ignore
Permission is granted to process this file through Tex and print the
Here is a brief summary of how to invoke @code{@value{AS}}. For details,
@pxref{Invoking,,Comand-Line Options}.
+@c man title AS the portable GNU assembler.
+
+@c man begin SEEALSO
+gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
+@c man end
+
@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
+@c man begin SYNOPSIS
@value{AS} [ -a[cdhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ]
- [ -f ] [ --gstabs ] [ --gdwarf2 ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ]
+ [ -f ] [ --gstabs ] [ --gdwarf2 ] [ --help ] [ -I @var{dir} ]
+ [ -J ] [ -K ] [ -L ]
+ [ --listing--lhs-width=NUM ][ --listing-lhs-width2=NUM ]
+ [ --listing-rhs-width=NUM ][ --listing-cont-lines=NUM ]
[ --keep-locals ] [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ]
[ -version ] [ --version ] [ -W ] [ --warn ] [ --fatal-warnings ]
[ -w ] [ -x ] [ -Z ] [ --target-help ]
[ -EB | -EL ]
@end ifset
@ifset ARM
- [ -m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 | -m[arm]6 | -m[arm]60 |
- -m[arm]600 | -m[arm]610 | -m[arm]620 | -m[arm]7[t][[d]m[i]][fe] | -m[arm]70 |
- -m[arm]700 | -m[arm]710[c] | -m[arm]7100 | -m[arm]7500 | -m[arm]8 |
- -m[arm]810 | -m[arm]9 | -m[arm]920 | -m[arm]920t | -m[arm]9tdmi |
+ [ -m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 |
+ -m[arm]6 | -m[arm]60 | -m[arm]600 | -m[arm]610 |
+ -m[arm]620 | -m[arm]7[t][[d]m[i]][fe] | -m[arm]70 |
+ -m[arm]700 | -m[arm]710[c] | -m[arm]7100 |
+ -m[arm]7500 | -m[arm]8 | -m[arm]810 | -m[arm]9 |
+ -m[arm]920 | -m[arm]920t | -m[arm]9tdmi |
-mstrongarm | -mstrongarm110 | -mstrongarm1100 ]
- [ -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m | -m[arm]v4 | -m[arm]v4t |
- -m[arm]v5 | -[arm]v5t | -[arm]v5te ]
+ [ -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m |
+ -m[arm]v4 | -m[arm]v4t | -m[arm]v5 | -[arm]v5t |
+ -[arm]v5te ]
[ -mthumb | -mall ]
[ -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu ]
[ -EB | -EL ]
- [ -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant ]
- [ -mthumb-interwork ]
- [ -moabi ]
- [ -k ]
+ [ -mapcs-32 | -mapcs-26 | -mapcs-float |
+ -mapcs-reentrant ]
+ [ -mthumb-interwork ] [ -moabi ] [ -k ]
@end ifset
@ifset D10V
[ -O ]
@c The order here is important. See c-sparc.texi.
[ -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
-Av8plus | -Av8plusa | -Av9 | -Av9a ]
- [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ] [ -32 | -64 ]
+ [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ]
+ [ -32 | -64 ]
@end ifset
@ifset TIC54X
[ -mcpu=54[123589] | -mcpu=54[56]lp ] [ -mfar-mode | -mf ]
@end ifset
@ifset I960
@c see md_parse_option in tc-i960.c
- [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
+ [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB |
+ -AKC | -AMC ]
[ -b ] [ -no-relax ]
@end ifset
@ifset M32R
- [ --m32rx | --[no-]warn-explicit-parallel-conflicts | --W[n]p ]
+ [ --m32rx | --[no-]warn-explicit-parallel-conflicts |
+ --W[n]p ]
@end ifset
@ifset M680X0
[ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
@end ifset
@ifset M68HC11
[ -m68hc11 | -m68hc12 ]
- [ --force-long-branchs ] [ --short-branchs ] [ --strict-direct-mode ]
- [ --print-insn-syntax ] [ --print-opcodes ] [ --generate-example ]
+ [ --force-long-branchs ] [ --short-branchs ]
+ [ --strict-direct-mode ] [ --print-insn-syntax ]
+ [ --print-opcodes ] [ --generate-example ]
@end ifset
@ifset MIPS
[ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ]
[ -mips1 ] [ -mips2 ] [ -mips3 ] [ -mips4 ] [ -mips5 ]
[ -mips32 ] [ -mips64 ]
[ -m4650 ] [ -no-m4650 ]
- [ --trap ] [ --break ]
+ [ --trap ] [ --break ] [ -n ]
[ --emulation=@var{name} ]
@end ifset
[ -- | @var{files} @dots{} ]
+@c man end
@end smallexample
+@c man begin OPTIONS
+
@table @code
@item -a[cdhlmns]
Turn on listings, in any of a variety of ways:
these start with @samp{L}, but different systems have different local
label prefixes.
+@item --listing-lhs-width=@var{number}
+Set the maximum width, in words, of the output data column for an assembler
+listing to @var{number}.
+
+@item --listing-lhs-width2=@var{number}
+Set the maximum width, in words, of the output data column for continuation
+lines in an assembler listing to @var{number}.
+
+@item --listing-rhs-width=@var{number}
+Set the maximum width of an input source line, as displayed in a listing, to
+@var{number} bytes.
+
+@item --listing-cont-lines=@var{number}
+Set the maximum number of lines printed in a listing for a single line of input
+to @var{number} + 1.
+
@item -o @var{objfile}
Name the object-file output from @code{@value{AS}} @var{objfile}.
@item -l
Shorten references to undefined symbols, to one word instead of two.
-@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060
-@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200
+@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030
+@itemx | -m68040 | -m68060 | -m68302 | -m68331 | -m68332
+@itemx | -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.
(and only work for Instruction Set Architecture level 2 and higher);
@samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a
break exception.
+
+@item -n
+When this option is used, @code{@value{AS}} will issue a warning every
+time it generates a nop instruction from a macro.
@end table
@end ifset
@end table
@end ifset
+@c man end
+
@menu
* Manual:: Structure of this Manual
* GNU Assembler:: The GNU Assembler
@node GNU Assembler
@section The GNU Assembler
+@c man begin DESCRIPTION
+
@sc{gnu} @code{as} is really a family of assemblers.
@ifclear GENERIC
This manual describes @code{@value{AS}}, a member of that family which is
incompatible versions of 680x0 assembly language syntax.
@end ifset
+@c man end
+
Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
program in one pass of the source file. This has a subtle impact on the
@kbd{.org} directive (@pxref{Org,,@code{.org}}).
@section Command Line
@cindex command line conventions
+
After the program name @code{@value{AS}}, the command line may contain
options and file names. Options may appear in any order, and may be
before, after, or between file names. The order of file names is
The source program is a concatenation of the text in all the files, in the
order specified.
+@c man begin DESCRIPTION
Each time you run @code{@value{AS}} it assembles exactly one source
program. The source program is made up of one or more files.
(The standard input is also a file.)
If the source is empty, @code{@value{AS}} produces a small, empty object
file.
+@c man end
+
@subheading Filenames and Line-numbers
@cindex input file linenumbers
@node Errors
@section Error and Warning Messages
+@c man begin DESCRIPTION
+
@cindex error messages
@cindex warning messages
@cindex messages from assembler
that @code{@value{AS}} could keep assembling a flawed program; errors report a
grave problem that stops the assembly.
+@c man end
+
@cindex format of warning messages
Warning messages have the format
to particular machine architectures.
@end ifset
+@c man begin DESCRIPTION
+
If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2),
you can use the @samp{-Wa} option to pass arguments through to the assembler.
The assembler arguments must be separated from each other (and the @samp{-Wa})
precisely what options it passes to each compilation pass, including the
assembler.)
+@c man end
+
@menu
* a:: -a[cdhlns] enable listings
* D:: -D for compatibility
@end ifset
* L:: -L to retain local labels
+* listing:: --listing-XXX to configure listing output
* M:: -M or --mri to assemble in MRI compatibility mode
* MD:: --MD for dependency tracking
* o:: -o to name the object file
The letters after @samp{-a} may be combined into one option,
@emph{e.g.}, @samp{-aln}.
+Note if the assembler source is coming from the standard input (eg because it
+is being created by @code{@value{GCC}} and the @samp{-pipe} command line switch
+is being used) then the listing will not contain any comments or preprocessor
+directives. This is because the listing code buffers input source lines from
+stdin only after they have been preprocessed by the assembler. This reduces
+memory usage and makes the code more efficient.
+
@node D
@section @code{-D}
On the HPPA local labels begin with @samp{L$}.
@end ifset
+@node listing
+@section Configuringh listing output: @code{--listing}
+
+The listing feature of the assembler can be enabled via the command line switch
+@samp{-a} (@pxref{a}). This feature combines the input source file(s) with a
+hex dump of the corresponding locations in the output object file, and displays
+them as a listing file. The format of this listing can be controlled by pseudo
+ops inside the assembler source (@pxref{List} @pxref{Title} @pxref{Sbttl}
+@pxref{Psize} @pxref{Eject}) and also by the following switches:
+
+@table @code
+@item --listing-lhs-width=@samp{number}
+@kindex --listing-lhs-width
+@cindex Width of first line disassembly output
+Sets the maximum width, in words, of the first line of the hex byte dump. This
+dump appears on the left hand side of the listing output.
+
+@item --listing-lhs-width2=@samp{number}
+@kindex --listing-lhs-width2
+@cindex Width of continuation lines of disassembly output
+Sets the maximum width, in words, of any further lines of the hex byte dump for
+a given inut source line. If this value is not specified, it defaults to being
+the same as the value specified for @samp{--listing-lhs-width}. If neither
+switch is used the default is to one.
+
+@item --listing-rhs-width=@samp{number}
+@kindex --listing-rhs-width
+@cindex Width of source line output
+Sets the maximum width, in characters, of the source line that is displayed
+alongside the hex dump. The default value for this parameter is 100. The
+source line is displayed on the right hand side of the listing output.
+
+@item --listing-cont-lines=@samp{number}
+@kindex --listing-cont-lines
+@cindex Maximum number of continuation lines
+Sets the maximum number of continuation lines of hex dump that will be
+displayed for a given single line of source input. The default value is 4.
+@end table
+
@node M
@section Assemble in MRI Compatibility Mode: @code{-M}
@ifset M68HC11
@samp{#} on the 68HC11 and 68HC12;
@end ifset
+@ifset M880X0
+@samp{;} on the M880x0;
+@end ifset
@ifset VAX
@samp{#} on the Vax;
@end ifset
@samp{#} on the V850;
@end ifset
see @ref{Machine Dependencies}. @refill
-@c FIXME What about m88k, i860?
+@c FIXME What about i860?
@ifset GENERIC
On some machines there are two different line comment characters. One
@end table
@item
-Lowest Precedence
+Low Precedence
@table @code
@cindex addition, permitted arguments
If both arguments are in the same section, the result is absolute.
You may not subtract arguments from different sections.
@c FIXME is there still something useful to say about undefined - undefined ?
+
+@cindex comparison expressions
+@cindex expressions, comparison
+@item ==
+@dfn{Is Equal To}
+@item <>
+@dfn{Is Not Equal To}
+@item <
+@dfn{Is Less Than}
+@itemx >
+@dfn{Is Greater Than}
+@itemx >=
+@dfn{Is Greater Than Or Equal To}
+@itemx <=
+@dfn{Is Less Than Or Equal To}
+
+The comparison operators can be used as infix operators. A true results has a
+value of -1 whereas a false result has a value of 0. Note, these operators
+perform signed comparisons.
+@end table
+
+@item Lowest Precedence
+
+@table @code
+@item &&
+@dfn{Logical And}.
+
+@item ||
+@dfn{Logical Or}.
+
+These two logical operations can be used to combine the results of sub
+expressions. Note, unlike the comparison operators a true result returns a
+value of 1 but a false results does still return 0. Also note that the logical
+or operator has a slightly lower precedence than logical and.
+
@end table
@end enumerate
* hword:: @code{.hword @var{expressions}}
* Ident:: @code{.ident}
* If:: @code{.if @var{absolute expression}}
+* Incbin:: @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]}
* Include:: @code{.include "@var{file}"}
* Int:: @code{.int @var{expressions}}
@ifset ELF
@cindex @code{fill} directive
@cindex writing patterns in memory
@cindex patterns, writing in memory
-@var{result}, @var{size} and @var{value} are absolute expressions.
+@var{repeat}, @var{size} and @var{value} are absolute expressions.
This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
may be zero or more. @var{Size} may be zero or more, but if it is
more than 8, then it is deemed to have the value 8, compatible with
following section of code if the two strings are not the same.
@end table
+@node Incbin
+@section @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]}
+
+@cindex @code{incbin} directive
+@cindex binary files, including
+The @code{incbin} directive includes @var{file} verbatim at the current
+location. You can control the search paths used with the @samp{-I} command-line
+option (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
+around @var{file}.
+
+The @var{skip} argument skips a number of bytes from the start of the
+@var{file}. The @var{count} argument indicates the maximum number of bytes to
+read. Note that the data from is not aligned in any way, make sure to proper
+alignment is provided before and after the @code{incbin} directive.
+
@node Include
@section @code{.include "@var{file}"}
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.
+loaded and writable. Note the @code{n} and @code{w} flags remove attributes
+from the section, rather than adding them, so if they are used on their own it
+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}).
@ifset M68HC11
* M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features
@end ifset
+@ifset M880X0
+* M88K-Dependent:: M880x0 Dependent Features
+@end ifset
@ifset MIPS
* MIPS-Dependent:: MIPS Dependent Features
@end ifset
@include c-m68hc11.texi
@end ifset
+@ifset M880X0
+@include c-m88k.texi
+@end ifset
+
@ifset MIPS
@include c-mips.texi
@end ifset
projects / deliverable / binutils-gdb.git / blobdiff