NAME
AS - the portable GNU assembler.
DESCRIPTION
GNU as is really a family of assemblers. If you use (or have used) the GNU assembler on one
architecture, you should find a fairly similar environment when you use it on another
architecture. Each version has much in common with the others, including object file
formats, most assembler directives (often called pseudoops) and assembler syntax.
as is primarily intended to assemble the output of the GNU C compiler for use by the linker .
Nevertheless, we've tried to make as assemble correctly everything that other assemblers
for the same machine would assemble. Any exceptions are documented explicitly. This
doesn't mean as always uses the same syntax as another assembler for the same
architecture; for example, we know of several incompatible versions of 680x0 assembly
language syntax.
Each time you run 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.)
You give as a command line that has zero or more input file names. The input files are read
(from left file name to right). A command line argument (in any position) that has no special
meaning is taken to be an input file name.
If you give as no file names it attempts to read one input file from the as standard input, which
is normally your terminal. You may have to type ctlD to tell as there is no more program to
assemble.
Use - if you need to explicitly name the standard input file in your command line.
If the source is empty, as produces a small, empty object file.
as may write warnings and error messages to the standard error file (usually your terminal).
This should not happen when a compiler runs as automatically. Warnings report an
assumption made so that as could keep assembling a flawed program; errors report a grave
problem that stops the assembly.
If you are invoking as via the GNU C compiler (version 2), you can use the -Wa option to
pass arguments through to the assembler. The assembler arguments must be separated
from each other (and the -Wa) by commas. For example:
gcc c g O Wa,alh,L file.c
This passes two options to the assembler: -alh (emit a listing to standard output with with
highlevel and assembly source) and -L (retain local symbols in the symbol table).
Usually you do not need to use this -Wa mechanism, since many compiler commandline
options are automatically passed to the assembler by the compiler. (You can call the GNU
compiler driver with the -v option to see precisely what options it passes to each compilation
pass, including the assembler.)
OPTIONS
-a[cdhlmns]
Turn on listings, in any of a variety of ways:
-ac
omit false conditionals
-ad
omit debugging directives
-ah
include highlevel source
-al
include assembly
-am
include macro expansions
-an
omit forms processing
-as
include symbols
=file
set the name of the listing file
You may combine these options; for example, use -aln for assembly listing without
forms processing. The =file option, if used, must be the last one. By itself, -a defaults to
-ahls.
-D
Ignored. This option is accepted for script compatibility with calls to other assemblers.
defsym sym=value
Define the symbol sym to be value before assembling the input file. value must be an
integer constant. As in C, a leading 0x indicates a hexadecimal value, and a leading 0
indicates an octal value.
-f ``fast''---skip whitespace and comment preprocessing (assume source is compiler
output).
gstabs
Generate stabs debugging information for each assembler line. This may help debugging
assembler code, if the debugger can handle it.
gdwarf2
Generate DWARF2 debugging information for each assembler line. This may help
debugging assembler code, if the debugger can handle it. Note - this option is only
supported by some targets, not all of them.
help
Print a summary of the command line options and exit.
targethelp
Print a summary of all target specific options and exit.
-I dir
Add directory dir to the search list for .include directives.
-J Don't warn about signed overflow.
-K
This option is accepted but has no effect on the TARGET family.
-L
keeplocals
Keep (in the symbol table) local symbols. On traditional a.out systems these start with L,
but different systems have different local label prefixes.
-o objfile
Name the objectfile output from as objfile.
-R
Fold the data section into the text section.
statistics
Print the maximum space (in bytes) and total time (in seconds) used by assembly.
striplocalabsolute
Remove local absolute symbols from the outgoing symbol table.
-v
-version
Print the as version.
version
Print the as version and exit.
-W
nowarn
Suppress warning messages.
fatalwarnings
Treat warnings as errors.
warn
Don't suppress warning messages or treat them as errors.
-w
Ignored.
-x Ignored.
-Z Generate an object file even after errors.
-- ï files ...
Standard input, or source files to assemble.
The following options are available when as is configured for an ARC processor.
-marc[5ï6ï7ï8]
This option selects the core processor variant.
-EB ï -EL
Select either bigendian (-EB) or littleendian (-EL) output.
The following options are available when as is configured for the ARM processor family.
-m[arm][1ï2ï3ï6ï7ï8ï9][...]
Specify which ARM processor variant is the target.
-m[arm]v[2ï2aï3ï3mï4ï4tï5ï5t]
Specify which ARM architecture variant is used by the target.
-mthumb ï -mall
Enable or disable Thumb only instruction decoding.
-mfpa10 ï -mfpa11 ï -mfpeold ï -mnofpu
Select which Floating Point architecture is the target.
-mapcs32 ï -mapcs26 ï -mapcsfloat ï -mapcsreentrant ï -moabi
Select which procedure calling convention is in use.
-EB ï -EL
Select either bigendian (-EB) or littleendian (-EL) output.
-mthumbinterwork
Specify that the code has been generated with interworking between Thumb and ARM
code in mind.
-k Specify that PIC code has been generated.
The following options are available when as is configured for a D10V processor.
-O
Optimize output by parallelizing instructions.
The following options are available when as is configured for a D30V processor.
-O
Optimize output by parallelizing instructions.
-n Warn when nops are generated.
-N
Warn when a nop after a 32-bit multiply instruction is generated.
The following options are available when as is configured for the Intel 80960 processor.
-ACA ï -ACA_A ï -ACB ï -ACC ï -AKA ï -AKB ï -AKC ï -AMC
Specify which variant of the 960 architecture is the target.
-b Add code to collect statistics about branches taken.
-norelax
Do not alter compareandbranch instructions for long displacements; error if necessary.
The following options are available when as is configured for the Mitsubishi M32R series.
m32rx
Specify which processor in the M32R family is the target. The default is normally the
M32R, but this option changes it to the M32RX.
warnexplicitparallelconflicts or --Wp
Produce warning messages when questionable parallel constructs are encountered.
nowarnexplicitparallelconflicts or --Wnp
Do not produce warning messages when questionable parallel constructs are
encountered.
The following options are available when as is configured for the Motorola 68000 series.
-l Shorten references to undefined symbols, to one word instead of two.
-m68000 ï -m68008 ï -m68010 ï -m68020 ï -m68030
ï -m68040 ï -m68060 ï -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.
-m68881 ï -m68882 ï -mno68881 ï -mno68882
The target machine does (or does not) have a floatingpoint coprocessor. The default is
to assume a coprocessor for 68020, 68030, and cpu32. Although the basic 68000 is not
compatible with the 68881, a combination of the two can be specified, since it's possible
to do emulation of the coprocessor instructions with the main processor.
-m68851 ï -mno68851
The target machine does (or does not) have a memorymanagement unit coprocessor.
The default is to assume an MMU for 68020 and up.
The following options are available when as is configured for a picoJava processor.
-mb
Generate ``big endian'' format output.
-ml
Generate ``little endian'' format output.
The following options are available when as is configured for the Motorola 68HC11 or
68HC12 series.
-m68hc11 ï -m68hc12
Specify what processor is the target. The default is defined by the configuration option
when building the assembler.
forcelongbranchs
Relative branches are turned into absolute ones. This concerns conditional branches,
unconditional branches and branches to a sub routine.
-S ï --shortbranchs
Do not turn relative branchs into absolute ones when the offset is out of range.
strictdirectmode
Do not turn the direct addressing mode into extended addressing mode when the
instruction does not support direct addressing mode.
printinsnsyntax
Print the syntax of instruction in case of error.
printopcodes
print the list of instructions with syntax and then exit.
generateexample
print an example of instruction for each possible instruction and then exit. This option is
only useful for testing as.
The following options are available when as is configured for the SPARC architecture:
-Av6 ï -Av7 ï -Av8 ï -Asparclet ï -Asparclite
-Av8plus ï -Av8plusa ï -Av9 ï -Av9a
Explicitly select a variant of the SPARC architecture.
-Av8plus and -Av8plusa select a 32 bit environment. -Av9 and -Av9a select a 64 bit
environment.
-Av8plusa and -Av9a enable the SPARC V9 instruction set with UltraSPARC
extensions.
-xarch=v8plus ï -xarch=v8plusa
For compatibility with the Solaris v9 assembler. These options are equivalent to
-Av8plus and -Av8plusa, respectively.
-bump
Warn when the assembler switches to another architecture.
The following options are available when as is configured for a MIPS processor.
-G num
This option sets the largest size of an object that can be referenced implicitly with the gp
register. It is only accepted for targets that use ECOFF format, such as a DECstation
running Ultrix. The default value is 8.
-EB
Generate ``big endian'' format output.
-EL
Generate ``little endian'' format output.
-mips1
-mips2
-mips3
-mips4
-mips32
Generate code for a particular MIPS Instruction Set Architecture level. -mips1
corresponds to the R2000 and R3000 processors, -mips2 to the R6000 processor, and
-mips3 to the R4000 processor. -mips5, -mips32, and -mips64 correspond to
generic MIPS V, MIPS32, and MIPS64 ISA processors, respectively.
-m4650
-nom4650
Generate code for the MIPS R4650 chip. This tells the assembler to accept the mad and
madu instruction, and to not schedule nop instructions around accesses to the HI and LO
registers. -nom4650 turns off this option.
-mcpu=CPU
Generate code for a particular MIPS cpu. It is exactly equivalent to -mcpu, except that
there are more value of cpu understood.
emulation=name
This option causes as to emulate as configured for some other target, in all respects,
including output format (choosing between ELF and ECOFF only), handling of
pseudoopcodes which may generate debugging information or store symbol table
information, and default endianness. The available configuration names are: mipsecoff,
mipself, mipslecoff, mipsbecoff, mipslelf, mipsbelf. The first two do not alter the
default endianness from that of the primary target for which the assembler was
configured; the others change the default to little or bigendian as indicated by the b or l
in the name. Using -EB or -EL will override the endianness selection in any case.
This option is currently supported only when the primary target as is configured for is a
MIPS ELF or ECOFF target. Furthermore, the primary target or others specified with
enabletargets=... at configuration time must include support for the other format, if
both are to be available. For example, the Irix 5 configuration includes support for both.
Eventually, this option will support more configurations, with more finegrained control
over the assembler's behavior, and will be supported for more processors.
-nocpp
as ignores this option. It is accepted for compatibility with the native tools.
trap
notrap
break
nobreak
Control how to deal with multiplication overflow and division by zero. trap or
nobreak (which are synonyms) take a trap exception (and only work for Instruction
Set Architecture level 2 and higher); break or notrap (also synonyms, and the
default) take a break exception.
The following options are available when as is configured for an MCore processor.
-jsri2bsr
-nojsri2bsr
Enable or disable the JSRI to BSR transformation. By default this is enabled. The
command line option -nojsri2bsr can be used to disable it.
-sifilter
-nosifilter
Enable or disable the silicon filter behaviour. By default this is disabled. The default can
be overridden by the -sifilter command line option.
-relax
Alter jump instructions for long displacements.
-mcpu=[210ï340]
Select the cpu type on the target hardware. This controls which instructions can be
assembled.
-EB
Assemble for a big endian target.
-EL
Assemble for a little endian target.
SEE ALSO
gcc (1), ld (1), and the Info entries for binutils and ld.
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 FrontCover Texts, and with no
BackCover Texts. A copy of the license is included in the section entitled ``GNU Free
Documentation License''.