8369 lines
229 KiB
Groff
8369 lines
229 KiB
Groff
.Dd 2015-03-02
|
|
.Dt AS 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm as
|
|
.Nd Using as (machine specific)
|
|
.Sh Using as
|
|
This file is a user guide to the GNU assembler
|
|
.Xr as
|
|
version "2.17.50 [FreeBSD] 2007-07-03". This version of the file describes
|
|
.Xr as
|
|
configured to generate code for machine specific architectures.
|
|
.Pp
|
|
This document is distributed under the terms of the GNU Free Documentation
|
|
License. A copy of the license is included in the section entitled \(lqGNU Free
|
|
Documentation License\(rq.
|
|
.Pp
|
|
.Sh Overview
|
|
Here is a brief summary of how to invoke
|
|
.Xr as .
|
|
For details, see Invoking,,Command-Line Options.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
as [-a[cdhlns][=file]] [--alternate] [-D]
|
|
[--defsym sym=val] [-f] [-g] [--gstabs]
|
|
[--gstabs+] [--gdwarf-2] [--help] [-I dir] [-J]
|
|
[-K] [-L] [--listing-lhs-width=NUM]
|
|
[--listing-lhs-width2=NUM] [--listing-rhs-width=NUM]
|
|
[--listing-cont-lines=NUM] [--keep-locals] [-o
|
|
objfile] [-R] [--reduce-memory-overheads] [--statistics]
|
|
[-v] [-version] [--version] [-W] [--warn]
|
|
[--fatal-warnings] [-w] [-x] [-Z] [@FILE]
|
|
[--target-help] [target-options]
|
|
[--|files ...]
|
|
|
|
Target ARM options:
|
|
[-mcpu=processor[+extension...]]
|
|
[-march=architecture[+extension...]]
|
|
[-mfpu=floating-point-format]
|
|
[-mfloat-abi=abi]
|
|
[-meabi=ver]
|
|
[-mthumb]
|
|
[-EB|-EL]
|
|
[-mapcs-32|-mapcs-26|-mapcs-float|
|
|
-mapcs-reentrant]
|
|
[-mthumb-interwork] [-k]
|
|
|
|
|
|
Target i386 options:
|
|
[--32|--64] [-n]
|
|
[-march=CPU] [-mtune=CPU]
|
|
|
|
|
|
Target IA-64 options:
|
|
[-mconstant-gp|-mauto-pic]
|
|
[-milp32|-milp64|-mlp64|-mp64]
|
|
[-mle|mbe]
|
|
[-mtune=itanium1|-mtune=itanium2]
|
|
[-munwind-check=warning|-munwind-check=error]
|
|
[-mhint.b=ok|-mhint.b=warning|-mhint.b=error]
|
|
[-x|-xexplicit] [-xauto] [-xdebug]
|
|
|
|
|
|
Target MIPS options:
|
|
[-nocpp] [-EL] [-EB] [-O[optimization level]]
|
|
[-g[debug level]] [-G num] [-KPIC] [-call_shared]
|
|
[-non_shared] [-xgot [-mvxworks-pic]
|
|
[-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32]
|
|
[-march=CPU] [-mtune=CPU] [-mips1] [-mips2]
|
|
[-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2]
|
|
[-mips64] [-mips64r2]
|
|
[-construct-floats] [-no-construct-floats]
|
|
[-trap] [-no-break] [-break] [-no-trap]
|
|
[-mfix7000] [-mno-fix7000]
|
|
[-mips16] [-no-mips16]
|
|
[-msmartmips] [-mno-smartmips]
|
|
[-mips3d] [-no-mips3d]
|
|
[-mdmx] [-no-mdmx]
|
|
[-mdsp] [-mno-dsp]
|
|
[-mdspr2] [-mno-dspr2]
|
|
[-mmt] [-mno-mt]
|
|
[-mdebug] [-no-mdebug]
|
|
[-mpdr] [-mno-pdr]
|
|
|
|
|
|
Target PowerPC options:
|
|
[-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604|
|
|
-m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke|
|
|
-mbooke32|-mbooke64]
|
|
[-mcom|-many|-maltivec] [-memb]
|
|
[-mregnames|-mno-regnames]
|
|
[-mrelocatable|-mrelocatable-lib]
|
|
[-mlittle|-mlittle-endian|-mbig|-mbig-endian]
|
|
[-msolaris|-mno-solaris]
|
|
|
|
|
|
Target SPARC options:
|
|
[-Av6|-Av7|-Av8|-Asparclet|-Asparclite
|
|
-Av8plus|-Av8plusa|-Av9|-Av9a]
|
|
[-xarch=v8plus|-xarch=v8plusa] [-bump]
|
|
[-32|-64]
|
|
|
|
|
|
|
|
.Ed
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It @ Va file
|
|
Read command-line options from
|
|
.Va file .
|
|
The options read are inserted in place of the original @
|
|
.Va file
|
|
option. If
|
|
.Va file
|
|
does not exist, or cannot be read, then the option will be treated literally,
|
|
and not removed.
|
|
.Pp
|
|
Options in
|
|
.Va file
|
|
are separated by whitespace. A whitespace character may be included in an
|
|
option by surrounding the entire option in either single or double quotes.
|
|
Any character (including a backslash) may be included by prefixing the character
|
|
to be included with a backslash. The
|
|
.Va file
|
|
may itself contain additional @
|
|
.Va file
|
|
options; any such options will be processed recursively.
|
|
.Pp
|
|
.It -a[cdhlmns]
|
|
Turn on listings, in any of a variety of ways:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It -ac
|
|
omit false conditionals
|
|
.Pp
|
|
.It -ad
|
|
omit debugging directives
|
|
.Pp
|
|
.It -ah
|
|
include high-level source
|
|
.Pp
|
|
.It -al
|
|
include assembly
|
|
.Pp
|
|
.It -am
|
|
include macro expansions
|
|
.Pp
|
|
.It -an
|
|
omit forms processing
|
|
.Pp
|
|
.It -as
|
|
include symbols
|
|
.Pp
|
|
.It =file
|
|
set the name of the listing file
|
|
.El
|
|
.Pp
|
|
You may combine these options; for example, use
|
|
.Li -aln
|
|
for assembly listing without forms processing. The
|
|
.Li =file
|
|
option, if used, must be the last one. By itself,
|
|
.Li -a
|
|
defaults to
|
|
.Li -ahls .
|
|
.Pp
|
|
.It --alternate
|
|
Begin in alternate macro mode.See Section
|
|
.Dq Altmacro .
|
|
.Pp
|
|
.It -D
|
|
Ignored. This option is accepted for script compatibility with calls to other
|
|
assemblers.
|
|
.Pp
|
|
.It --defsym Va sym= Va value
|
|
Define the symbol
|
|
.Va sym
|
|
to be
|
|
.Va value
|
|
before assembling the input file.
|
|
.Va value
|
|
must be an integer constant. As in C, a leading
|
|
.Li 0x
|
|
indicates a hexadecimal value, and a leading
|
|
.Li 0
|
|
indicates an octal value. The value of the symbol can be overridden inside
|
|
a source file via the use of a
|
|
.Li .set
|
|
pseudo-op.
|
|
.Pp
|
|
.It -f
|
|
\(lqfast\(rq---skip whitespace and comment preprocessing (assume source is compiler
|
|
output).
|
|
.Pp
|
|
.It -g
|
|
.It --gen-debug
|
|
Generate debugging information for each assembler source line using whichever
|
|
debug format is preferred by the target. This currently means either STABS,
|
|
ECOFF or DWARF2.
|
|
.Pp
|
|
.It --gstabs
|
|
Generate stabs debugging information for each assembler line. This may help
|
|
debugging assembler code, if the debugger can handle it.
|
|
.Pp
|
|
.It --gstabs+
|
|
Generate stabs debugging information for each assembler line, with GNU extensions
|
|
that probably only gdb can handle, and that could make other debuggers crash
|
|
or refuse to read your program. This may help debugging assembler code. Currently
|
|
the only GNU extension is the location of the current working directory at
|
|
assembling time.
|
|
.Pp
|
|
.It --gdwarf-2
|
|
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.
|
|
.Pp
|
|
.It --help
|
|
Print a summary of the command line options and exit.
|
|
.Pp
|
|
.It --target-help
|
|
Print a summary of all target specific options and exit.
|
|
.Pp
|
|
.It -I Va dir
|
|
Add directory
|
|
.Va dir
|
|
to the search list for
|
|
.Li .include
|
|
directives.
|
|
.Pp
|
|
.It -J
|
|
Don't warn about signed overflow.
|
|
.Pp
|
|
.It -K
|
|
This option is accepted but has no effect on the machine specific family.
|
|
.Pp
|
|
.It -L
|
|
.It --keep-locals
|
|
Keep (in the symbol table) local symbols. These symbols start with system-specific
|
|
local label prefixes, typically
|
|
.Li .L
|
|
for ELF systems or
|
|
.Li L
|
|
for traditional a.out systems.See Section
|
|
.Dq Symbol Names .
|
|
.Pp
|
|
.It --listing-lhs-width= Va number
|
|
Set the maximum width, in words, of the output data column for an assembler
|
|
listing to
|
|
.Va number .
|
|
.Pp
|
|
.It --listing-lhs-width2= Va number
|
|
Set the maximum width, in words, of the output data column for continuation
|
|
lines in an assembler listing to
|
|
.Va number .
|
|
.Pp
|
|
.It --listing-rhs-width= Va number
|
|
Set the maximum width of an input source line, as displayed in a listing,
|
|
to
|
|
.Va number
|
|
bytes.
|
|
.Pp
|
|
.It --listing-cont-lines= Va number
|
|
Set the maximum number of lines printed in a listing for a single line of
|
|
input to
|
|
.Va number
|
|
+ 1.
|
|
.Pp
|
|
.It -o Va objfile
|
|
Name the object-file output from
|
|
.Xr as
|
|
.Va objfile .
|
|
.Pp
|
|
.It -R
|
|
Fold the data section into the text section.
|
|
.Pp
|
|
Set the default size of GAS's hash tables to a prime number close to
|
|
.Va number .
|
|
Increasing this value can reduce the length of time it takes the assembler
|
|
to perform its tasks, at the expense of increasing the assembler's memory
|
|
requirements. Similarly reducing this value can reduce the memory requirements
|
|
at the expense of speed.
|
|
.Pp
|
|
.It --reduce-memory-overheads
|
|
This option reduces GAS's memory requirements, at the expense of making the
|
|
assembly processes slower. Currently this switch is a synonym for
|
|
.Li --hash-size=4051 ,
|
|
but in the future it may have other effects as well.
|
|
.Pp
|
|
.It --statistics
|
|
Print the maximum space (in bytes) and total time (in seconds) used by assembly.
|
|
.Pp
|
|
.It --strip-local-absolute
|
|
Remove local absolute symbols from the outgoing symbol table.
|
|
.Pp
|
|
.It -v
|
|
.It -version
|
|
Print the
|
|
.Xr as
|
|
version.
|
|
.Pp
|
|
.It --version
|
|
Print the
|
|
.Xr as
|
|
version and exit.
|
|
.Pp
|
|
.It -W
|
|
.It --no-warn
|
|
Suppress warning messages.
|
|
.Pp
|
|
.It --fatal-warnings
|
|
Treat warnings as errors.
|
|
.Pp
|
|
.It --warn
|
|
Don't suppress warning messages or treat them as errors.
|
|
.Pp
|
|
.It -w
|
|
Ignored.
|
|
.Pp
|
|
.It -x
|
|
Ignored.
|
|
.Pp
|
|
.It -Z
|
|
Generate an object file even after errors.
|
|
.Pp
|
|
.It -- | Va files ...
|
|
Standard input, or source files to assemble.
|
|
.Pp
|
|
.El
|
|
The following options are available when as is configured for the ARM processor
|
|
family.
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It -mcpu= Va processor[+ Va extension...]
|
|
Specify which ARM processor variant is the target.
|
|
.It -march= Va architecture[+ Va extension...]
|
|
Specify which ARM architecture variant is used by the target.
|
|
.It -mfpu= Va floating-point-format
|
|
Select which Floating Point architecture is the target.
|
|
.It -mfloat-abi= Va abi
|
|
Select which floating point ABI is in use.
|
|
.It -mthumb
|
|
Enable Thumb only instruction decoding.
|
|
.It -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant
|
|
Select which procedure calling convention is in use.
|
|
.It -EB | -EL
|
|
Select either big-endian (-EB) or little-endian (-EL) output.
|
|
.It -mthumb-interwork
|
|
Specify that the code has been generated with interworking between Thumb and
|
|
ARM code in mind.
|
|
.It -k
|
|
Specify that PIC code has been generated.
|
|
.El
|
|
.Pp
|
|
The following options are available when
|
|
.Xr as
|
|
is configured for the SPARC architecture:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
|
|
.It -Av8plus | -Av8plusa | -Av9 | -Av9a
|
|
Explicitly select a variant of the SPARC architecture.
|
|
.Pp
|
|
.Li -Av8plus
|
|
and
|
|
.Li -Av8plusa
|
|
select a 32 bit environment.
|
|
.Li -Av9
|
|
and
|
|
.Li -Av9a
|
|
select a 64 bit environment.
|
|
.Pp
|
|
.Li -Av8plusa
|
|
and
|
|
.Li -Av9a
|
|
enable the SPARC V9 instruction set with UltraSPARC extensions.
|
|
.Pp
|
|
.It -xarch=v8plus | -xarch=v8plusa
|
|
For compatibility with the Solaris v9 assembler. These options are equivalent
|
|
to -Av8plus and -Av8plusa, respectively.
|
|
.Pp
|
|
.It -bump
|
|
Warn when the assembler switches to another architecture.
|
|
.El
|
|
.Pp
|
|
The following options are available when as is configured for a mips processor.
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It -G Va num
|
|
This option sets the largest size of an object that can be referenced implicitly
|
|
with the
|
|
.Li gp
|
|
register. It is only accepted for targets that use ECOFF format, such as a
|
|
DECstation running Ultrix. The default value is 8.
|
|
.Pp
|
|
.It -EB
|
|
Generate \(lqbig endian\(rq format output.
|
|
.Pp
|
|
.It -EL
|
|
Generate \(lqlittle endian\(rq format output.
|
|
.Pp
|
|
.It -mips1
|
|
.It -mips2
|
|
.It -mips3
|
|
.It -mips4
|
|
.It -mips5
|
|
.It -mips32
|
|
.It -mips32r2
|
|
.It -mips64
|
|
.It -mips64r2
|
|
Generate code for a particular mips Instruction Set Architecture level.
|
|
.Li -mips1
|
|
is an alias for
|
|
.Li -march=r3000 ,
|
|
.Li -mips2
|
|
is an alias for
|
|
.Li -march=r6000 ,
|
|
.Li -mips3
|
|
is an alias for
|
|
.Li -march=r4000
|
|
and
|
|
.Li -mips4
|
|
is an alias for
|
|
.Li -march=r8000 .
|
|
.Li -mips5 ,
|
|
.Li -mips32 ,
|
|
.Li -mips32r2 ,
|
|
.Li -mips64 ,
|
|
and
|
|
.Li -mips64r2
|
|
correspond to generic
|
|
.Li MIPS V ,
|
|
.Li MIPS32 ,
|
|
.Li MIPS32 Release 2 ,
|
|
.Li MIPS64 ,
|
|
and
|
|
.Li MIPS64 Release 2
|
|
ISA processors, respectively.
|
|
.Pp
|
|
.It -march= Va CPU
|
|
Generate code for a particular mips cpu.
|
|
.Pp
|
|
.It -mtune= Va cpu
|
|
Schedule and tune for a particular mips cpu.
|
|
.Pp
|
|
.It -mfix7000
|
|
.It -mno-fix7000
|
|
Cause nops to be inserted if the read of the destination register of an mfhi
|
|
or mflo instruction occurs in the following two instructions.
|
|
.Pp
|
|
.It -mdebug
|
|
.It -no-mdebug
|
|
Cause stabs-style debugging output to go into an ECOFF-style .mdebug section
|
|
instead of the standard ELF .stabs sections.
|
|
.Pp
|
|
.It -mpdr
|
|
.It -mno-pdr
|
|
Control generation of
|
|
.Li .pdr
|
|
sections.
|
|
.Pp
|
|
.It -mgp32
|
|
.It -mfp32
|
|
The register sizes are normally inferred from the ISA and ABI, but these flags
|
|
force a certain group of registers to be treated as 32 bits wide at all times.
|
|
.Li -mgp32
|
|
controls the size of general-purpose registers and
|
|
.Li -mfp32
|
|
controls the size of floating-point registers.
|
|
.Pp
|
|
.It -mips16
|
|
.It -no-mips16
|
|
Generate code for the MIPS 16 processor. This is equivalent to putting
|
|
.Li .set mips16
|
|
at the start of the assembly file.
|
|
.Li -no-mips16
|
|
turns off this option.
|
|
.Pp
|
|
.It -msmartmips
|
|
.It -mno-smartmips
|
|
Enables the SmartMIPS extension to the MIPS32 instruction set. This is equivalent
|
|
to putting
|
|
.Li .set smartmips
|
|
at the start of the assembly file.
|
|
.Li -mno-smartmips
|
|
turns off this option.
|
|
.Pp
|
|
.It -mips3d
|
|
.It -no-mips3d
|
|
Generate code for the MIPS-3D Application Specific Extension. This tells the
|
|
assembler to accept MIPS-3D instructions.
|
|
.Li -no-mips3d
|
|
turns off this option.
|
|
.Pp
|
|
.It -mdmx
|
|
.It -no-mdmx
|
|
Generate code for the MDMX Application Specific Extension. This tells the
|
|
assembler to accept MDMX instructions.
|
|
.Li -no-mdmx
|
|
turns off this option.
|
|
.Pp
|
|
.It -mdsp
|
|
.It -mno-dsp
|
|
Generate code for the DSP Release 1 Application Specific Extension. This tells
|
|
the assembler to accept DSP Release 1 instructions.
|
|
.Li -mno-dsp
|
|
turns off this option.
|
|
.Pp
|
|
.It -mdspr2
|
|
.It -mno-dspr2
|
|
Generate code for the DSP Release 2 Application Specific Extension. This option
|
|
implies -mdsp. This tells the assembler to accept DSP Release 2 instructions.
|
|
.Li -mno-dspr2
|
|
turns off this option.
|
|
.Pp
|
|
.It -mmt
|
|
.It -mno-mt
|
|
Generate code for the MT Application Specific Extension. This tells the assembler
|
|
to accept MT instructions.
|
|
.Li -mno-mt
|
|
turns off this option.
|
|
.Pp
|
|
.It --construct-floats
|
|
.It --no-construct-floats
|
|
The
|
|
.Li --no-construct-floats
|
|
option disables the construction of double width floating point constants
|
|
by loading the two halves of the value into the two single width floating
|
|
point registers that make up the double width register. By default
|
|
.Li --construct-floats
|
|
is selected, allowing construction of these floating point constants.
|
|
.Pp
|
|
.It --emulation= Va name
|
|
This option causes
|
|
.Xr as
|
|
to emulate
|
|
.Xr as
|
|
configured for some other target, in all respects, including output format
|
|
(choosing between ELF and ECOFF only), handling of pseudo-opcodes which may
|
|
generate debugging information or store symbol table information, and default
|
|
endianness. The available configuration names are:
|
|
.Li mipsecoff ,
|
|
.Li mipself ,
|
|
.Li mipslecoff ,
|
|
.Li mipsbecoff ,
|
|
.Li mipslelf ,
|
|
.Li 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 big-endian as indicated by the
|
|
.Li b
|
|
or
|
|
.Li l
|
|
in the name. Using
|
|
.Li -EB
|
|
or
|
|
.Li -EL
|
|
will override the endianness selection in any case.
|
|
.Pp
|
|
This option is currently supported only when the primary target
|
|
.Xr as
|
|
is configured for is a mips ELF or ECOFF target. Furthermore, the primary
|
|
target or others specified with
|
|
.Li --enable-targets=...
|
|
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.
|
|
.Pp
|
|
Eventually, this option will support more configurations, with more fine-grained
|
|
control over the assembler's behavior, and will be supported for more processors.
|
|
.Pp
|
|
.It -nocpp
|
|
.Xr as
|
|
ignores this option. It is accepted for compatibility with the native tools.
|
|
.Pp
|
|
.It --trap
|
|
.It --no-trap
|
|
.It --break
|
|
.It --no-break
|
|
Control how to deal with multiplication overflow and division by zero.
|
|
.Li --trap
|
|
or
|
|
.Li --no-break
|
|
(which are synonyms) take a trap exception (and only work for Instruction
|
|
Set Architecture level 2 and higher);
|
|
.Li --break
|
|
or
|
|
.Li --no-trap
|
|
(also synonyms, and the default) take a break exception.
|
|
.Pp
|
|
.It -n
|
|
When this option is used,
|
|
.Xr as
|
|
will issue a warning every time it generates a nop instruction from a macro.
|
|
.El
|
|
.Pp
|
|
.Ss Structure of this Manual
|
|
This manual is intended to describe what you need to know to use GNU
|
|
.Xr as .
|
|
We cover the syntax expected in source files, including notation for symbols,
|
|
constants, and expressions; the directives that
|
|
.Xr as
|
|
understands; and of course how to invoke
|
|
.Xr as .
|
|
.Pp
|
|
We also cover special features in the machine specific configuration of
|
|
.Xr as ,
|
|
including assembler directives.
|
|
.Pp
|
|
On the other hand, this manual is
|
|
.Em not
|
|
intended as an introduction to programming in assembly language---let alone
|
|
programming in general! In a similar vein, we make no attempt to introduce
|
|
the machine architecture; we do
|
|
.Em not
|
|
describe the instruction set, standard mnemonics, registers or addressing
|
|
modes that are standard to a particular architecture.
|
|
.Pp
|
|
.Ss The GNU Assembler
|
|
GNU
|
|
.Xr as
|
|
is really a family of assemblers. This manual describes
|
|
.Xr as ,
|
|
a member of that family which is configured for the machine specific architectures.
|
|
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
|
|
.Em pseudo-ops )
|
|
and assembler syntax.
|
|
.Pp
|
|
.Xr as
|
|
is primarily intended to assemble the output of the GNU C compiler
|
|
.Li gcc
|
|
for use by the linker
|
|
.Li ld .
|
|
Nevertheless, we've tried to make
|
|
.Xr as
|
|
assemble correctly everything that other assemblers for the same machine would
|
|
assemble.
|
|
.Pp
|
|
Unlike older assemblers,
|
|
.Xr as
|
|
is designed to assemble a source program in one pass of the source file. This
|
|
has a subtle impact on the
|
|
.Li .org
|
|
directive (see Section
|
|
.Dq Org ) .
|
|
.Pp
|
|
.Ss Object File Formats
|
|
The GNU assembler can be configured to produce several alternative object
|
|
file formats. For the most part, this does not affect how you write assembly
|
|
language programs; but directives for debugging symbols are typically different
|
|
in different file formats.See Section
|
|
.Dq Symbol Attributes .
|
|
For the machine specific target,
|
|
.Xr as
|
|
is configured to produce ELF format object files.
|
|
.Pp
|
|
.Ss Command Line
|
|
After the program name
|
|
.Xr 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 significant.
|
|
.Pp
|
|
.Pa --
|
|
(two hyphens) by itself names the standard input file explicitly, as one of
|
|
the files for
|
|
.Xr as
|
|
to assemble.
|
|
.Pp
|
|
Except for
|
|
.Li --
|
|
any command line argument that begins with a hyphen (
|
|
.Li - )
|
|
is an option. Each option changes the behavior of
|
|
.Xr as .
|
|
No option changes the way another option works. An option is a
|
|
.Li -
|
|
followed by one or more letters; the case of the letter is important. All
|
|
options are optional.
|
|
.Pp
|
|
Some options expect exactly one file name to follow them. The file name may
|
|
either immediately follow the option's letter (compatible with older assemblers)
|
|
or it may be the next command argument (GNU standard). These two command lines
|
|
are equivalent:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
as -o my-object-file.o mumble.s
|
|
as -omy-object-file.o mumble.s
|
|
.Ed
|
|
.Pp
|
|
.Ss Input Files
|
|
We use the phrase
|
|
.Em source program ,
|
|
abbreviated
|
|
.Em source ,
|
|
to describe the program input to one run of
|
|
.Xr as .
|
|
The program may be in one or more files; how the source is partitioned into
|
|
files doesn't change the meaning of the source.
|
|
.Pp
|
|
The source program is a concatenation of the text in all the files, in the
|
|
order specified.
|
|
.Pp
|
|
Each time you run
|
|
.Xr 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.)
|
|
.Pp
|
|
You give
|
|
.Xr 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.
|
|
.Pp
|
|
If you give
|
|
.Xr as
|
|
no file names it attempts to read one input file from the
|
|
.Xr as
|
|
standard input, which is normally your terminal. You may have to type ctl-D
|
|
to tell
|
|
.Xr as
|
|
there is no more program to assemble.
|
|
.Pp
|
|
Use
|
|
.Li --
|
|
if you need to explicitly name the standard input file in your command line.
|
|
.Pp
|
|
If the source is empty,
|
|
.Xr as
|
|
produces a small, empty object file.
|
|
.Pp
|
|
.Em Filenames and Line-numbers
|
|
.Pp
|
|
There are two ways of locating a line in the input file (or files) and either
|
|
may be used in reporting error messages. One way refers to a line number in
|
|
a physical file; the other refers to a line number in a \(lqlogical\(rq file.See Section
|
|
.Dq Errors .
|
|
.Pp
|
|
.Em Physical files
|
|
are those files named in the command line given to
|
|
.Xr as .
|
|
.Pp
|
|
.Em Logical files
|
|
are simply names declared explicitly by assembler directives; they bear no
|
|
relation to physical files. Logical file names help error messages reflect
|
|
the original source file, when
|
|
.Xr as
|
|
source is itself synthesized from other files.
|
|
.Xr as
|
|
understands the
|
|
.Li #
|
|
directives emitted by the
|
|
.Li gcc
|
|
preprocessor. See also File,,
|
|
.Li .file
|
|
\&.
|
|
.Pp
|
|
.Ss Output (Object) File
|
|
Every time you run
|
|
.Xr as
|
|
it produces an output file, which is your assembly language program translated
|
|
into numbers. This file is the object file. Its default name is
|
|
.Li a.out .
|
|
You can give it another name by using the
|
|
.Op -o
|
|
option. Conventionally, object file names end with
|
|
.Pa .o .
|
|
The default name is used for historical reasons: older assemblers were capable
|
|
of assembling self-contained programs directly into a runnable program. (For
|
|
some formats, this isn't currently possible, but it can be done for the
|
|
.Li a.out
|
|
format.)
|
|
.Pp
|
|
The object file is meant for input to the linker
|
|
.Li ld .
|
|
It contains assembled program code, information to help
|
|
.Li ld
|
|
integrate the assembled program into a runnable file, and (optionally) symbolic
|
|
information for the debugger.
|
|
.Pp
|
|
.Ss Error and Warning Messages
|
|
.Xr as
|
|
may write warnings and error messages to the standard error file (usually
|
|
your terminal). This should not happen when a compiler runs
|
|
.Xr as
|
|
automatically. Warnings report an assumption made so that
|
|
.Xr as
|
|
could keep assembling a flawed program; errors report a grave problem that
|
|
stops the assembly.
|
|
.Pp
|
|
Warning messages have the format
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
file_name:NNN:Warning Message Text
|
|
.Ed
|
|
.Pp
|
|
(where
|
|
.Sy NNN
|
|
is a line number). If a logical file name has been given (see Section
|
|
.Dq File )
|
|
it is used for the filename, otherwise the name of the current input file
|
|
is used. If a logical line number was given then it is used to calculate the
|
|
number printed, otherwise the actual line in the current source file is printed.
|
|
The message text is intended to be self explanatory (in the grand Unix tradition).
|
|
.Pp
|
|
Error messages have the format
|
|
.Bd -literal -offset indent
|
|
file_name:NNN:FATAL:Error Message Text
|
|
.Ed
|
|
The file name and line number are derived as for warning messages. The actual
|
|
message text may be rather less explanatory because many of them aren't supposed
|
|
to happen.
|
|
.Pp
|
|
.Sh Command-Line Options
|
|
This chapter describes command-line options available in
|
|
.Em all
|
|
versions of the GNU assembler; see Machine Dependencies, for options specific
|
|
to the machine specific target.
|
|
.Pp
|
|
If you are invoking
|
|
.Xr as
|
|
via the GNU C compiler, you can use the
|
|
.Li -Wa
|
|
option to pass arguments through to the assembler. The assembler arguments
|
|
must be separated from each other (and the
|
|
.Li -Wa )
|
|
by commas. For example:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
gcc -c -g -O -Wa,-alh,-L file.c
|
|
.Ed
|
|
.Pp
|
|
This passes two options to the assembler:
|
|
.Li -alh
|
|
(emit a listing to standard output with high-level and assembly source) and
|
|
.Li -L
|
|
(retain local symbols in the symbol table).
|
|
.Pp
|
|
Usually you do not need to use this
|
|
.Li -Wa
|
|
mechanism, since many compiler command-line options are automatically passed
|
|
to the assembler by the compiler. (You can call the GNU compiler driver with
|
|
the
|
|
.Li -v
|
|
option to see precisely what options it passes to each compilation pass, including
|
|
the assembler.)
|
|
.Pp
|
|
.Ss Enable Listings: Op -a[cdhlns]
|
|
These options enable listing output from the assembler. By itself,
|
|
.Li -a
|
|
requests high-level, assembly, and symbols listing. You can use other letters
|
|
to select specific options for the list:
|
|
.Li -ah
|
|
requests a high-level language listing,
|
|
.Li -al
|
|
requests an output-program assembly listing, and
|
|
.Li -as
|
|
requests a symbol table listing. High-level listings require that a compiler
|
|
debugging option like
|
|
.Li -g
|
|
be used, and that assembly listings (
|
|
.Li -al )
|
|
be requested also.
|
|
.Pp
|
|
Use the
|
|
.Li -ac
|
|
option to omit false conditionals from a listing. Any lines which are not
|
|
assembled because of a false
|
|
.Li .if
|
|
(or
|
|
.Li .ifdef ,
|
|
or any other conditional), or a true
|
|
.Li .if
|
|
followed by an
|
|
.Li .else ,
|
|
will be omitted from the listing.
|
|
.Pp
|
|
Use the
|
|
.Li -ad
|
|
option to omit debugging directives from the listing.
|
|
.Pp
|
|
Once you have specified one of these options, you can further control listing
|
|
output and its appearance using the directives
|
|
.Li .list ,
|
|
.Li .nolist ,
|
|
.Li .psize ,
|
|
.Li .eject ,
|
|
.Li .title ,
|
|
and
|
|
.Li .sbttl .
|
|
The
|
|
.Li -an
|
|
option turns off all forms processing. If you do not request listing output
|
|
with one of the
|
|
.Li -a
|
|
options, the listing-control directives have no effect.
|
|
.Pp
|
|
The letters after
|
|
.Li -a
|
|
may be combined into one option,
|
|
.Em e.g. ,
|
|
.Li -aln .
|
|
.Pp
|
|
Note if the assembler source is coming from the standard input (e.g., because
|
|
it is being created by
|
|
.Li gcc
|
|
and the
|
|
.Li -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.
|
|
.Pp
|
|
.Ss Op --alternate
|
|
Begin in alternate macro mode, see Altmacro,,
|
|
.Li .altmacro
|
|
\&.
|
|
.Pp
|
|
.Ss Op -D
|
|
This option has no effect whatsoever, but it is accepted to make it more likely
|
|
that scripts written for other assemblers also work with
|
|
.Xr as .
|
|
.Pp
|
|
.Ss Work Faster: Op -f
|
|
.Li -f
|
|
should only be used when assembling programs written by a (trusted) compiler.
|
|
.Li -f
|
|
stops the assembler from doing whitespace and comment preprocessing on the
|
|
input file(s) before assembling them.See Section
|
|
.Dq Preprocessing .
|
|
.Pp
|
|
.Qo
|
|
.Em Warning:
|
|
if you use
|
|
.Li -f
|
|
when the files actually need to be preprocessed (if they contain comments,
|
|
for example),
|
|
.Xr as
|
|
does not work correctly.
|
|
.Qc
|
|
.Pp
|
|
.Ss Li .include Search Path: Op -I Va path
|
|
Use this option to add a
|
|
.Va path
|
|
to the list of directories
|
|
.Xr as
|
|
searches for files specified in
|
|
.Li .include
|
|
directives (see Section
|
|
.Dq Include ) .
|
|
You may use
|
|
.Op -I
|
|
as many times as necessary to include a variety of paths. The current working
|
|
directory is always searched first; after that,
|
|
.Xr as
|
|
searches any
|
|
.Li -I
|
|
directories in the same order as they were specified (left to right) on the
|
|
command line.
|
|
.Pp
|
|
.Ss Difference Tables: Op -K
|
|
On the machine specific family, this option is allowed, but has no effect.
|
|
It is permitted for compatibility with the GNU assembler on other platforms,
|
|
where it can be used to warn when the assembler alters the machine code generated
|
|
for
|
|
.Li .word
|
|
directives in difference tables. The machine specific family does not have
|
|
the addressing limitations that sometimes lead to this alteration on other
|
|
platforms.
|
|
.Pp
|
|
.Ss Include Local Symbols: Op -L
|
|
Symbols beginning with system-specific local label prefixes, typically
|
|
.Li .L
|
|
for ELF systems or
|
|
.Li L
|
|
for traditional a.out systems, are called
|
|
.Em local symbols .
|
|
See Section.Dq Symbol Names .
|
|
Normally you do not see such symbols when debugging, because they are intended
|
|
for the use of programs (like compilers) that compose assembler programs,
|
|
not for your notice. Normally both
|
|
.Xr as
|
|
and
|
|
.Li ld
|
|
discard such symbols, so you do not normally debug with them.
|
|
.Pp
|
|
This option tells
|
|
.Xr as
|
|
to retain those local symbols in the object file. Usually if you do this you
|
|
also tell the linker
|
|
.Li ld
|
|
to preserve those symbols.
|
|
.Pp
|
|
.Ss Configuring listing output: Op --listing
|
|
The listing feature of the assembler can be enabled via the command line switch
|
|
.Li -a
|
|
(see Section
|
|
.Dq 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 directives inside the assembler
|
|
source (i.e.,
|
|
.Li .list
|
|
(see Section
|
|
.Dq List ) ,
|
|
.Li .title
|
|
(see Section
|
|
.Dq Title ) ,
|
|
.Li .sbttl
|
|
(see Section
|
|
.Dq Sbttl ) ,
|
|
.Li .psize
|
|
(see Section
|
|
.Dq Psize ) ,
|
|
and
|
|
.Li .eject
|
|
(see Section
|
|
.Dq Eject )
|
|
and also by the following switches:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It --listing-lhs-width= Li number
|
|
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.
|
|
.Pp
|
|
.It --listing-lhs-width2= Li number
|
|
Sets the maximum width, in words, of any further lines of the hex byte dump
|
|
for a given input source line. If this value is not specified, it defaults
|
|
to being the same as the value specified for
|
|
.Li --listing-lhs-width .
|
|
If neither switch is used the default is to one.
|
|
.Pp
|
|
.It --listing-rhs-width= Li number
|
|
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.
|
|
.Pp
|
|
.It --listing-cont-lines= Li number
|
|
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.
|
|
.El
|
|
.Pp
|
|
.Ss Assemble in MRI Compatibility Mode: Op -M
|
|
The
|
|
.Op -M
|
|
or
|
|
.Op --mri
|
|
option selects MRI compatibility mode. This changes the syntax and pseudo-op
|
|
handling of
|
|
.Xr as
|
|
to make it compatible with the
|
|
.Li ASM68K
|
|
or the
|
|
.Li 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
|
|
.Xr as .
|
|
.Pp
|
|
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
|
|
file formats. Supporting these would require enhancing each object file format
|
|
individually. These are:
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
global symbols in common section
|
|
.Pp
|
|
The m68k MRI assembler supports common sections which are merged by the linker.
|
|
Other object file formats do not support this.
|
|
.Xr 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 symbols, since it has no way to describe them.
|
|
.Pp
|
|
.It
|
|
complex relocations
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.It
|
|
.Li END
|
|
pseudo-op specifying start address
|
|
.Pp
|
|
The MRI
|
|
.Li END
|
|
pseudo-op permits the specification of a start address. This is not supported
|
|
by other object file formats. The start address may instead be specified using
|
|
the
|
|
.Op -e
|
|
option to the linker, or in a linker script.
|
|
.Pp
|
|
.It
|
|
.Li IDNT ,
|
|
.Li .ident
|
|
and
|
|
.Li NAME
|
|
pseudo-ops
|
|
.Pp
|
|
The MRI
|
|
.Li IDNT ,
|
|
.Li .ident
|
|
and
|
|
.Li NAME
|
|
pseudo-ops assign a module name to the output file. This is not supported
|
|
by other object file formats.
|
|
.Pp
|
|
.It
|
|
.Li ORG
|
|
pseudo-op
|
|
.Pp
|
|
The m68k MRI
|
|
.Li ORG
|
|
pseudo-op begins an absolute section at a given address. This differs from
|
|
the usual
|
|
.Xr as
|
|
.Li .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.
|
|
.El
|
|
.Pp
|
|
There are some other features of the MRI assembler which are not supported
|
|
by
|
|
.Xr as ,
|
|
typically either because they are difficult or because they seem of little
|
|
consequence. Some of these may be supported in future releases.
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
EBCDIC strings
|
|
.Pp
|
|
EBCDIC strings are not supported.
|
|
.Pp
|
|
.It
|
|
packed binary coded decimal
|
|
.Pp
|
|
Packed binary coded decimal is not supported. This means that the
|
|
.Li DC.P
|
|
and
|
|
.Li DCB.P
|
|
pseudo-ops are not supported.
|
|
.Pp
|
|
.It
|
|
.Li FEQU
|
|
pseudo-op
|
|
.Pp
|
|
The m68k
|
|
.Li FEQU
|
|
pseudo-op is not supported.
|
|
.Pp
|
|
.It
|
|
.Li NOOBJ
|
|
pseudo-op
|
|
.Pp
|
|
The m68k
|
|
.Li NOOBJ
|
|
pseudo-op is not supported.
|
|
.Pp
|
|
.It
|
|
.Li OPT
|
|
branch control options
|
|
.Pp
|
|
The m68k
|
|
.Li OPT
|
|
branch control options---
|
|
.Li B ,
|
|
.Li BRS ,
|
|
.Li BRB ,
|
|
.Li BRL ,
|
|
and
|
|
.Li BRW
|
|
---are ignored.
|
|
.Xr as
|
|
automatically relaxes all branches, whether forward or backward, to an appropriate
|
|
size, so these options serve no purpose.
|
|
.Pp
|
|
.It
|
|
.Li OPT
|
|
list control options
|
|
.Pp
|
|
The following m68k
|
|
.Li OPT
|
|
list control options are ignored:
|
|
.Li C ,
|
|
.Li CEX ,
|
|
.Li CL ,
|
|
.Li CRE ,
|
|
.Li E ,
|
|
.Li G ,
|
|
.Li I ,
|
|
.Li M ,
|
|
.Li MEX ,
|
|
.Li MC ,
|
|
.Li MD ,
|
|
.Li X .
|
|
.Pp
|
|
.It
|
|
other
|
|
.Li OPT
|
|
options
|
|
.Pp
|
|
The following m68k
|
|
.Li OPT
|
|
options are ignored:
|
|
.Li NEST ,
|
|
.Li O ,
|
|
.Li OLD ,
|
|
.Li OP ,
|
|
.Li P ,
|
|
.Li PCO ,
|
|
.Li PCR ,
|
|
.Li PCS ,
|
|
.Li R .
|
|
.Pp
|
|
.It
|
|
.Li OPT
|
|
.Li D
|
|
option is default
|
|
.Pp
|
|
The m68k
|
|
.Li OPT
|
|
.Li D
|
|
option is the default, unlike the MRI assembler.
|
|
.Li OPT NOD
|
|
may be used to turn it off.
|
|
.Pp
|
|
.It
|
|
.Li XREF
|
|
pseudo-op.
|
|
.Pp
|
|
The m68k
|
|
.Li XREF
|
|
pseudo-op is ignored.
|
|
.Pp
|
|
.It
|
|
.Li .debug
|
|
pseudo-op
|
|
.Pp
|
|
The i960
|
|
.Li .debug
|
|
pseudo-op is not supported.
|
|
.Pp
|
|
.It
|
|
.Li .extended
|
|
pseudo-op
|
|
.Pp
|
|
The i960
|
|
.Li .extended
|
|
pseudo-op is not supported.
|
|
.Pp
|
|
.It
|
|
.Li .list
|
|
pseudo-op.
|
|
.Pp
|
|
The various options of the i960
|
|
.Li .list
|
|
pseudo-op are not supported.
|
|
.Pp
|
|
.It
|
|
.Li .optimize
|
|
pseudo-op
|
|
.Pp
|
|
The i960
|
|
.Li .optimize
|
|
pseudo-op is not supported.
|
|
.Pp
|
|
.It
|
|
.Li .output
|
|
pseudo-op
|
|
.Pp
|
|
The i960
|
|
.Li .output
|
|
pseudo-op is not supported.
|
|
.Pp
|
|
.It
|
|
.Li .setreal
|
|
pseudo-op
|
|
.Pp
|
|
The i960
|
|
.Li .setreal
|
|
pseudo-op is not supported.
|
|
.Pp
|
|
.El
|
|
.Ss Dependency Tracking: Op --MD
|
|
.Xr as
|
|
can generate a dependency file for the file it creates. This file consists
|
|
of a single rule suitable for
|
|
.Li make
|
|
describing the dependencies of the main source file.
|
|
.Pp
|
|
The rule is written to the file named in its argument.
|
|
.Pp
|
|
This feature is used in the automatic updating of makefiles.
|
|
.Pp
|
|
.Ss Name the Object File: Op -o
|
|
There is always one object file output when you run
|
|
.Xr as .
|
|
By default it has the name
|
|
.Pa a.out .
|
|
You use this option (which takes exactly one filename) to give the object
|
|
file a different name.
|
|
.Pp
|
|
Whatever the object file is called,
|
|
.Xr as
|
|
overwrites any existing file of the same name.
|
|
.Pp
|
|
.Ss Join Data and Text Sections: Op -R
|
|
.Op -R
|
|
tells
|
|
.Xr as
|
|
to write the object file as if all data-section data lives in the text section.
|
|
This is only done at the very last moment: your binary data are the same,
|
|
but data section parts are relocated differently. The data section part of
|
|
your object file is zero bytes long because all its bytes are appended to
|
|
the text section. (See Section
|
|
.Dq Sections . )
|
|
.Pp
|
|
When you specify
|
|
.Op -R
|
|
it would be possible to generate shorter address displacements (because we
|
|
do not have to cross between text and data section). We refrain from doing
|
|
this simply for compatibility with older versions of
|
|
.Xr as .
|
|
In future,
|
|
.Op -R
|
|
may work this way.
|
|
.Pp
|
|
When
|
|
.Xr as
|
|
is configured for COFF or ELF output, this option is only useful if you use
|
|
sections named
|
|
.Li .text
|
|
and
|
|
.Li .data .
|
|
.Pp
|
|
.Ss Display Assembly Statistics: Op --statistics
|
|
Use
|
|
.Li --statistics
|
|
to display two statistics about the resources used by
|
|
.Xr as :
|
|
the maximum amount of space allocated during the assembly (in bytes), and
|
|
the total execution time taken for the assembly (in cpu seconds).
|
|
.Pp
|
|
.Ss Compatible Output: Op --traditional-format
|
|
For some targets, the output of
|
|
.Xr as
|
|
is different in some ways from the output of some existing assembler. This
|
|
switch requests
|
|
.Xr as
|
|
to use the traditional format instead.
|
|
.Pp
|
|
For example, it disables the exception frame optimizations which
|
|
.Xr as
|
|
normally does by default on
|
|
.Li gcc
|
|
output.
|
|
.Pp
|
|
.Ss Announce Version: Op -v
|
|
You can find out what version of as is running by including the option
|
|
.Li -v
|
|
(which you can also spell as
|
|
.Li -version )
|
|
on the command line.
|
|
.Pp
|
|
.Ss Control Warnings: Op -W, Op --warn, Op --no-warn, Op --fatal-warnings
|
|
.Xr as
|
|
should never give a warning or error message when assembling compiler output.
|
|
But programs written by people often cause
|
|
.Xr as
|
|
to give a warning that a particular assumption was made. All such warnings
|
|
are directed to the standard error file.
|
|
.Pp
|
|
If you use the
|
|
.Op -W
|
|
and
|
|
.Op --no-warn
|
|
options, no warnings are issued. This only affects the warning messages: it
|
|
does not change any particular of how
|
|
.Xr as
|
|
assembles your file. Errors, which stop the assembly, are still reported.
|
|
.Pp
|
|
If you use the
|
|
.Op --fatal-warnings
|
|
option,
|
|
.Xr as
|
|
considers files that generate warnings to be in error.
|
|
.Pp
|
|
You can switch these options off again by specifying
|
|
.Op --warn ,
|
|
which causes warnings to be output as usual.
|
|
.Pp
|
|
.Ss Generate Object File in Spite of Errors: Op -Z
|
|
After an error message,
|
|
.Xr as
|
|
normally produces no output. If for some reason you are interested in object
|
|
file output even after
|
|
.Xr as
|
|
gives an error message on your program, use the
|
|
.Li -Z
|
|
option. If there are any errors,
|
|
.Xr as
|
|
continues anyways, and writes an object file after a final warning message
|
|
of the form
|
|
.Li Va n errors, Va m warnings, generating bad object file.
|
|
.Pp
|
|
.Sh Syntax
|
|
This chapter describes the machine-independent syntax allowed in a source
|
|
file.
|
|
.Xr as
|
|
syntax is similar to what many other assemblers use; it is inspired by the
|
|
BSD 4.2 assembler.
|
|
.Pp
|
|
.Ss Preprocessing
|
|
The
|
|
.Xr as
|
|
internal preprocessor:
|
|
.Bl -bullet
|
|
.It
|
|
adjusts and removes extra whitespace. It leaves one space or tab before the
|
|
keywords on a line, and turns any other whitespace on the line into a single
|
|
space.
|
|
.Pp
|
|
.It
|
|
removes all comments, replacing them with a single space, or an appropriate
|
|
number of newlines.
|
|
.Pp
|
|
.It
|
|
converts character constants into the appropriate numeric values.
|
|
.El
|
|
.Pp
|
|
It does not do macro processing, include file handling, or anything else you
|
|
may get from your C compiler's preprocessor. You can do include file processing
|
|
with the
|
|
.Li .include
|
|
directive (see Section
|
|
.Dq Include ) .
|
|
You can use the GNU C compiler driver to get other \(lqCPP\(rq style preprocessing
|
|
by giving the input file a
|
|
.Li .S
|
|
suffix.See Section
|
|
.Dq Overall Options .
|
|
.Pp
|
|
Excess whitespace, comments, and character constants cannot be used in the
|
|
portions of the input text that are not preprocessed.
|
|
.Pp
|
|
If the first line of an input file is
|
|
.Li #NO_APP
|
|
or if you use the
|
|
.Li -f
|
|
option, whitespace and comments are not removed from the input file. Within
|
|
an input file, you can ask for whitespace and comment removal in specific
|
|
portions of the by putting a line that says
|
|
.Li #APP
|
|
before the text that may contain whitespace or comments, and putting a line
|
|
that says
|
|
.Li #NO_APP
|
|
after this text. This feature is mainly intend to support
|
|
.Li asm
|
|
statements in compilers whose output is otherwise free of comments and whitespace.
|
|
.Pp
|
|
.Ss Whitespace
|
|
.Em Whitespace
|
|
is one or more blanks or tabs, in any order. Whitespace is used to separate
|
|
symbols, and to make programs neater for people to read. Unless within character
|
|
constants (see Section
|
|
.Dq Characters ) ,
|
|
any whitespace means the same as exactly one space.
|
|
.Pp
|
|
.Ss Comments
|
|
There are two ways of rendering comments to
|
|
.Xr as .
|
|
In both cases the comment is equivalent to one space.
|
|
.Pp
|
|
Anything from
|
|
.Li /*
|
|
through the next
|
|
.Li */
|
|
is a comment. This means you may not nest these comments.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
/*
|
|
The only way to include a newline ('\en') in a comment
|
|
is to use this sort of comment.
|
|
*/
|
|
|
|
/* This sort of comment does not nest. */
|
|
.Ed
|
|
.Pp
|
|
Anything from the
|
|
.Em line comment
|
|
character to the next newline is considered a comment and is ignored. The
|
|
line comment character is
|
|
.Li @
|
|
on the ARM;
|
|
.Li #
|
|
on the i386 and x86-64;
|
|
.Li #
|
|
for Motorola PowerPC;
|
|
.Li !
|
|
on the SPARC; see Machine Dependencies.
|
|
.Pp
|
|
To be compatible with past assemblers, lines that begin with
|
|
.Li #
|
|
have a special interpretation. Following the
|
|
.Li #
|
|
should be an absolute expression (see Section
|
|
.Dq Expressions ) :
|
|
the logical line number of the
|
|
.Em next
|
|
line. Then a string (see Section
|
|
.Dq Strings )
|
|
is allowed: if present it is a new logical file name. The rest of the line,
|
|
if any, should be whitespace.
|
|
.Pp
|
|
If the first non-whitespace characters on the line are not numeric, the line
|
|
is ignored. (Just like a comment.)
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
# This is an ordinary comment.
|
|
# 42-6 "new_file_name" # New logical file name
|
|
# This is logical line # 36.
|
|
.Ed
|
|
This feature is deprecated, and may disappear from future versions of
|
|
.Xr as .
|
|
.Pp
|
|
.Ss Symbols
|
|
A
|
|
.Em symbol
|
|
is one or more characters chosen from the set of all letters (both upper and
|
|
lower case), digits and the three characters
|
|
.Li _.$ .
|
|
No symbol may begin with a digit. Case is significant. There is no length
|
|
limit: all characters are significant. Symbols are delimited by characters
|
|
not in that set, or by the beginning of a file (since the source program must
|
|
end with a newline, the end of a file is not a possible symbol delimiter).See Section
|
|
.Dq Symbols .
|
|
.Pp
|
|
.Ss Statements
|
|
A
|
|
.Em statement
|
|
ends at a newline character (
|
|
.Li \en )
|
|
or at a semicolon (
|
|
.Li ; ) .
|
|
The newline or semicolon is considered part of the preceding statement. Newlines
|
|
and semicolons within character constants are an exception: they do not end
|
|
statements.
|
|
.Pp
|
|
It is an error to end any statement with end-of-file: the last character of
|
|
any input file should be a newline.
|
|
.Pp
|
|
An empty statement is allowed, and may include whitespace. It is ignored.
|
|
.Pp
|
|
A statement begins with zero or more labels, optionally followed by a key
|
|
symbol which determines what kind of statement it is. The key symbol determines
|
|
the syntax of the rest of the statement. If the symbol begins with a dot
|
|
.Li .
|
|
then the statement is an assembler directive: typically valid for any computer.
|
|
If the symbol begins with a letter the statement is an assembly language
|
|
.Em instruction :
|
|
it assembles into a machine language instruction.
|
|
.Pp
|
|
A label is a symbol immediately followed by a colon (
|
|
.Li : ) .
|
|
Whitespace before a label or after a colon is permitted, but you may not have
|
|
whitespace between a label's symbol and its colon.See Section
|
|
.Dq Labels .
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
label: .directive followed by something
|
|
another_label: # This is an empty statement.
|
|
instruction operand_1, operand_2, ...
|
|
.Ed
|
|
.Pp
|
|
.Ss Constants
|
|
A constant is a number, written so that its value is known by inspection,
|
|
without knowing any context. Like this:
|
|
.Bd -literal -offset indent
|
|
|
|
\&.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\eJ # All the same value.
|
|
\&.ascii "Ring the bell\e7" # A string constant.
|
|
\&.octa 0x123456789abcdef0123456789ABCDEF0 # A biGNUm.
|
|
\&.float 0f-314159265358979323846264338327\e
|
|
95028841971.693993751E-40 # - pi, a flonum.
|
|
|
|
.Ed
|
|
.Pp
|
|
.Em Character Constants
|
|
.Pp
|
|
There are two kinds of character constants. A
|
|
.Em character
|
|
stands for one character in one byte and its value may be used in numeric
|
|
expressions. String constants (properly called string
|
|
.Em literals )
|
|
are potentially many bytes and their values may not be used in arithmetic
|
|
expressions.
|
|
.Pp
|
|
.No Strings
|
|
.Pp
|
|
A
|
|
.Em string
|
|
is written between double-quotes. It may contain double-quotes or null characters.
|
|
The way to get special characters into a string is to
|
|
.Em escape
|
|
these characters: precede them with a backslash
|
|
.Li \e
|
|
character. For example
|
|
.Li \e\e
|
|
represents one backslash: the first
|
|
.Li \e
|
|
is an escape which tells
|
|
.Xr as
|
|
to interpret the second character literally as a backslash (which prevents
|
|
.Xr as
|
|
from recognizing the second
|
|
.Li \e
|
|
as an escape character). The complete list of escapes follows.
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It \eb
|
|
Mnemonic for backspace; for ASCII this is octal code 010.
|
|
.Pp
|
|
.It \ef
|
|
Mnemonic for FormFeed; for ASCII this is octal code 014.
|
|
.Pp
|
|
.It \en
|
|
Mnemonic for newline; for ASCII this is octal code 012.
|
|
.Pp
|
|
.It \er
|
|
Mnemonic for carriage-Return; for ASCII this is octal code 015.
|
|
.Pp
|
|
.It \et
|
|
Mnemonic for horizontal Tab; for ASCII this is octal code 011.
|
|
.Pp
|
|
.It \e Va digit Va digit Va 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,
|
|
.Li \e008
|
|
has the value 010, and
|
|
.Li \e009
|
|
the value 011.
|
|
.Pp
|
|
.It \e Li x Va hex-digits...
|
|
A hex character code. All trailing hex digits are combined. Either upper or
|
|
lower case
|
|
.Li x
|
|
works.
|
|
.Pp
|
|
.It \e\e
|
|
Represents one
|
|
.Li \e
|
|
character.
|
|
.Pp
|
|
.It \e"
|
|
Represents one
|
|
.Li "
|
|
character. Needed in strings to represent this character, because an unescaped
|
|
.Li "
|
|
would end the string.
|
|
.Pp
|
|
.It \e Va anything-else
|
|
Any other character when escaped by
|
|
.Li \e
|
|
gives a warning, but assembles as if the
|
|
.Li \e
|
|
was not present. The idea is that if you used an escape sequence you clearly
|
|
didn't want the literal interpretation of the following character. However
|
|
.Xr as
|
|
has no other interpretation, so
|
|
.Xr as
|
|
knows it is giving you the wrong code and warns you of the fact.
|
|
.El
|
|
.Pp
|
|
Which characters are escapable, and what those escapes represent, varies widely
|
|
among assemblers. The current set is what we think the BSD 4.2 assembler recognizes,
|
|
and is a subset of what most C compilers recognize. If you are in doubt, do
|
|
not use an escape sequence.
|
|
.Pp
|
|
.No Characters
|
|
.Pp
|
|
A single character may be written as a single quote immediately followed by
|
|
that character. The same escapes apply to characters as to strings. So if
|
|
you want to write the character backslash, you must write
|
|
.Li '\e\e
|
|
where the first
|
|
.Li \e
|
|
escapes the second
|
|
.Li \e .
|
|
As you can see, the quote is an acute accent, not a grave accent. A newline
|
|
(or semicolon
|
|
.Li ; )
|
|
immediately following an acute accent is taken as a literal character and
|
|
does not count as the end of a statement. The value of a character constant
|
|
in a numeric expression is the machine's byte-wide code for that character.
|
|
.Xr as
|
|
assumes your character code is ASCII:
|
|
.Li 'A
|
|
means 65,
|
|
.Li 'B
|
|
means 66, and so on.
|
|
.Pp
|
|
.Em Number Constants
|
|
.Pp
|
|
.Xr as
|
|
distinguishes three kinds of numbers according to how they are stored in the
|
|
target machine.
|
|
.Em Integers
|
|
are numbers that would fit into an
|
|
.Li int
|
|
in the C language.
|
|
.Em BiGNUms
|
|
are integers, but they are stored in more than 32 bits.
|
|
.Em Flonums
|
|
are floating point numbers, described below.
|
|
.Pp
|
|
.No Integers
|
|
.Pp
|
|
A binary integer is
|
|
.Li 0b
|
|
or
|
|
.Li 0B
|
|
followed by zero or more of the binary digits
|
|
.Li 01 .
|
|
.Pp
|
|
An octal integer is
|
|
.Li 0
|
|
followed by zero or more of the octal digits (
|
|
.Li 01234567 ) .
|
|
.Pp
|
|
A decimal integer starts with a non-zero digit followed by zero or more digits
|
|
(
|
|
.Li 0123456789 ) .
|
|
.Pp
|
|
A hexadecimal integer is
|
|
.Li 0x
|
|
or
|
|
.Li 0X
|
|
followed by one or more hexadecimal digits chosen from
|
|
.Li 0123456789abcdefABCDEF .
|
|
.Pp
|
|
Integers have the usual values. To denote a negative integer, use the prefix
|
|
operator
|
|
.Li -
|
|
discussed under expressions (see Section
|
|
.Dq Prefix Ops ) .
|
|
.Pp
|
|
.No BiGNUms
|
|
.Pp
|
|
A
|
|
.Em biGNUm
|
|
has the same syntax and semantics as an integer except that the number (or
|
|
its negative) takes more than 32 bits to represent in binary. The distinction
|
|
is made because in some places integers are permitted while biGNUms are not.
|
|
.Pp
|
|
.No Flonums
|
|
.Pp
|
|
A
|
|
.Em flonum
|
|
represents a floating point number. The translation is indirect: a decimal
|
|
floating point number from the text is converted by
|
|
.Xr as
|
|
to a generic binary floating point number of more than sufficient precision.
|
|
This generic floating point number is converted to a particular computer's
|
|
floating point format (or formats) by a portion of
|
|
.Xr as
|
|
specialized to that computer.
|
|
.Pp
|
|
A flonum is written by writing (in order)
|
|
.Bl -bullet
|
|
.It
|
|
The digit
|
|
.Li 0 .
|
|
.Pp
|
|
.It
|
|
A letter, to tell
|
|
.Xr as
|
|
the rest of the number is a flonum.
|
|
.Pp
|
|
.It
|
|
An optional sign: either
|
|
.Li +
|
|
or
|
|
.Li - .
|
|
.Pp
|
|
.It
|
|
An optional
|
|
.Em integer part :
|
|
zero or more decimal digits.
|
|
.Pp
|
|
.It
|
|
An optional
|
|
.Em fractional part :
|
|
.Li .
|
|
followed by zero or more decimal digits.
|
|
.Pp
|
|
.It
|
|
An optional exponent, consisting of:
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
An
|
|
.Li E
|
|
or
|
|
.Li e .
|
|
.It
|
|
Optional sign: either
|
|
.Li +
|
|
or
|
|
.Li - .
|
|
.It
|
|
One or more decimal digits.
|
|
.El
|
|
.Pp
|
|
.El
|
|
At least one of the integer part or the fractional part must be present. The
|
|
floating point number has the usual base-10 value.
|
|
.Pp
|
|
.Xr as
|
|
does all processing using integers. Flonums are computed independently of
|
|
any floating point hardware in the computer running
|
|
.Xr as .
|
|
.Pp
|
|
.Sh Sections and Relocation
|
|
.Ss Background
|
|
Roughly, a section is a range of addresses, with no gaps; all data \(lqin\(rq those
|
|
addresses is treated the same for some particular purpose. For example there
|
|
may be a \(lqread only\(rq section.
|
|
.Pp
|
|
The linker
|
|
.Li ld
|
|
reads many object files (partial programs) and combines their contents to
|
|
form a runnable program. When
|
|
.Xr as
|
|
emits an object file, the partial program is assumed to start at address 0.
|
|
.Li ld
|
|
assigns the final addresses for the partial program, so that different partial
|
|
programs do not overlap. This is actually an oversimplification, but it suffices
|
|
to explain how
|
|
.Xr as
|
|
uses sections.
|
|
.Pp
|
|
.Li ld
|
|
moves blocks of bytes of your program to their run-time addresses. These blocks
|
|
slide to their run-time addresses as rigid units; their length does not change
|
|
and neither does the order of bytes within them. Such a rigid unit is called
|
|
a
|
|
.Em section .
|
|
Assigning run-time addresses to sections is called
|
|
.Em relocation .
|
|
It includes the task of adjusting mentions of object-file addresses so they
|
|
refer to the proper run-time addresses.
|
|
.Pp
|
|
An object file written by
|
|
.Xr as
|
|
has at least three sections, any of which may be empty. These are named
|
|
.Em text ,
|
|
.Em data
|
|
and
|
|
.Em bss
|
|
sections.
|
|
.Pp
|
|
.Xr as
|
|
can also generate whatever other named sections you specify using the
|
|
.Li .section
|
|
directive (see Section
|
|
.Dq Section ) .
|
|
If you do not use any directives that place output in the
|
|
.Li .text
|
|
or
|
|
.Li .data
|
|
sections, these sections still exist, but are empty.
|
|
.Pp
|
|
Within the object file, the text section starts at address
|
|
.Li 0 ,
|
|
the data section follows, and the bss section follows the data section.
|
|
.Pp
|
|
To let
|
|
.Li ld
|
|
know which data changes when the sections are relocated, and how to change
|
|
that data,
|
|
.Xr as
|
|
also writes to the object file details of the relocation needed. To perform
|
|
relocation
|
|
.Li ld
|
|
must know, each time an address in the object file is mentioned:
|
|
.Bl -bullet
|
|
.It
|
|
Where in the object file is the beginning of this reference to an address?
|
|
.It
|
|
How long (in bytes) is this reference?
|
|
.It
|
|
Which section does the address refer to? What is the numeric value of
|
|
.Bd -filled -offset indent
|
|
(
|
|
.Va address )
|
|
\-(
|
|
.Va start-address of section ) ?
|
|
.Ed
|
|
.It
|
|
Is the reference to an address \(lqProgram-Counter relative\(rq?
|
|
.El
|
|
.Pp
|
|
In fact, every address
|
|
.Xr as
|
|
ever uses is expressed as
|
|
.Bd -filled -offset indent
|
|
(
|
|
.Va section )
|
|
+ (
|
|
.Va offset into section )
|
|
.Ed
|
|
Further, most expressions
|
|
.Xr as
|
|
computes have this section-relative nature.
|
|
.Pp
|
|
In this manual we use the notation {
|
|
.Va secname
|
|
.Va N
|
|
}to mean \(lqoffset
|
|
.Va N
|
|
into section
|
|
.Va secname
|
|
\&.\(rq
|
|
.Pp
|
|
Apart from text, data and bss sections you need to know about the
|
|
.Em absolute
|
|
section. When
|
|
.Li ld
|
|
mixes partial programs, addresses in the absolute section remain unchanged.
|
|
For example, address
|
|
.Li {absolute 0}
|
|
is \(lqrelocated\(rq to run-time address 0 by
|
|
.Li ld .
|
|
Although the linker never arranges two partial programs' data sections with
|
|
overlapping addresses after linking,
|
|
.Em by definition
|
|
their absolute sections must overlap. Address
|
|
.Li {absolute 239}
|
|
in one part of a program is always the same address when the program is running
|
|
as address
|
|
.Li {absolute 239}
|
|
in any other part of the program.
|
|
.Pp
|
|
The idea of sections is extended to the
|
|
.Em undefined
|
|
section. Any address whose section is unknown at assembly time is by definition
|
|
rendered {undefined
|
|
.Va U
|
|
}---where
|
|
.Va U
|
|
is filled in later. Since numbers are always defined, the only way to generate
|
|
an undefined address is to mention an undefined symbol. A reference to a named
|
|
common block would be such a symbol: its value is unknown at assembly time
|
|
so it has section
|
|
.Em undefined .
|
|
.Pp
|
|
By analogy the word
|
|
.Em section
|
|
is used to describe groups of sections in the linked program.
|
|
.Li ld
|
|
puts all partial programs' text sections in contiguous addresses in the linked
|
|
program. It is customary to refer to the
|
|
.Em text section
|
|
of a program, meaning all the addresses of all partial programs' text sections.
|
|
Likewise for data and bss sections.
|
|
.Pp
|
|
Some sections are manipulated by
|
|
.Li ld ;
|
|
others are invented for use of
|
|
.Xr as
|
|
and have no meaning except during assembly.
|
|
.Pp
|
|
.Ss Linker Sections
|
|
.Li ld
|
|
deals with just four kinds of sections, summarized below.
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It named sections
|
|
These sections hold your program.
|
|
.Xr as
|
|
and
|
|
.Li ld
|
|
treat them as separate but equal sections. Anything you can say of one section
|
|
is true of another. When the program is running, however, it is customary
|
|
for the text section to be unalterable. The text section is often shared among
|
|
processes: it contains instructions, constants and the like. The data section
|
|
of a running program is usually alterable: for example, C variables would
|
|
be stored in the data section.
|
|
.Pp
|
|
.It bss section
|
|
This section contains zeroed bytes when your program begins running. It is
|
|
used to hold uninitialized variables or common storage. The length of each
|
|
partial program's bss section is important, but because it starts out containing
|
|
zeroed bytes there is no need to store explicit zero bytes in the object file.
|
|
The bss section was invented to eliminate those explicit zeros from object
|
|
files.
|
|
.Pp
|
|
.It absolute section
|
|
Address 0 of this section is always \(lqrelocated\(rq to runtime address 0. This is
|
|
useful if you want to refer to an address that
|
|
.Li ld
|
|
must not change when relocating. In this sense we speak of absolute addresses
|
|
being \(lqunrelocatable\(rq: they do not change during relocation.
|
|
.Pp
|
|
.It undefined section
|
|
This \(lqsection\(rq is a catch-all for address references to objects not in the preceding
|
|
sections.
|
|
.El
|
|
.Pp
|
|
An idealized example of three relocatable sections follows. The example uses
|
|
the traditional section names
|
|
.Li .text
|
|
and
|
|
.Li .data .
|
|
Memory addresses are on the horizontal axis.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
+-----+----+--+
|
|
partial program # 1: |ttttt|dddd|00|
|
|
+-----+----+--+
|
|
|
|
text data bss
|
|
seg. seg. seg.
|
|
|
|
+---+---+---+
|
|
partial program # 2: |TTT|DDD|000|
|
|
+---+---+---+
|
|
|
|
+--+---+-----+--+----+---+-----+~~
|
|
linked program: | |TTT|ttttt| |dddd|DDD|00000|
|
|
+--+---+-----+--+----+---+-----+~~
|
|
|
|
addresses: 0 ...
|
|
.Ed
|
|
.Pp
|
|
.Ss Assembler Internal Sections
|
|
These sections are meant only for the internal use of
|
|
.Xr as .
|
|
They have no meaning at run-time. You do not really need to know about these
|
|
sections for most purposes; but they can be mentioned in
|
|
.Xr as
|
|
warning messages, so it might be helpful to have an idea of their meanings
|
|
to
|
|
.Xr as .
|
|
These sections are used to permit the value of every expression in your assembly
|
|
language program to be a section-relative address.
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It ASSEMBLER-INTERNAL-LOGIC-ERROR!
|
|
An internal assembler logic error has been found. This means there is a bug
|
|
in the assembler.
|
|
.Pp
|
|
.It 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.
|
|
.El
|
|
.Pp
|
|
.Ss Sub-Sections
|
|
You may have separate groups of data in named sections that you want to end
|
|
up near to each other in the object file, even though they are not contiguous
|
|
in the assembler source.
|
|
.Xr as
|
|
allows you to use
|
|
.Em subsections
|
|
for this purpose. Within each section, there can be numbered subsections with
|
|
values from 0 to 8192. Objects assembled into the same subsection go into
|
|
the object file together with other objects in the same subsection. For example,
|
|
a compiler might want to store constants in the text section, but might not
|
|
want to have them interspersed with the program being assembled. In this case,
|
|
the compiler could issue a
|
|
.Li .text 0
|
|
before each section of code being output, and a
|
|
.Li .text 1
|
|
before each group of constants being output.
|
|
.Pp
|
|
Subsections are optional. If you do not use subsections, everything goes in
|
|
subsection number zero.
|
|
.Pp
|
|
Subsections appear in your object file in numeric order, lowest numbered to
|
|
highest. (All this to be compatible with other people's assemblers.) The object
|
|
file contains no representation of subsections;
|
|
.Li ld
|
|
and other programs that manipulate object files see no trace of them. They
|
|
just see all your text subsections as a text section, and all your data subsections
|
|
as a data section.
|
|
.Pp
|
|
To specify which subsection you want subsequent statements assembled into,
|
|
use a numeric argument to specify it, in a
|
|
.Li .text Va expression
|
|
or a
|
|
.Li .data Va expression
|
|
statement. You can also use the
|
|
.Li .subsection
|
|
directive (see Section
|
|
.Dq SubSection )
|
|
to specify a subsection:
|
|
.Li .subsection Va expression .
|
|
.Va Expression
|
|
should be an absolute expression (see Section
|
|
.Dq Expressions ) .
|
|
If you just say
|
|
.Li .text
|
|
then
|
|
.Li .text 0
|
|
is assumed. Likewise
|
|
.Li .data
|
|
means
|
|
.Li .data 0 .
|
|
Assembly begins in
|
|
.Li text 0 .
|
|
For instance:
|
|
.Bd -literal -offset indent
|
|
\&.text 0 # The default subsection is text 0 anyway.
|
|
\&.ascii "This lives in the first text subsection. *"
|
|
\&.text 1
|
|
\&.ascii "But this lives in the second text subsection."
|
|
\&.data 0
|
|
\&.ascii "This lives in the data section,"
|
|
\&.ascii "in the first data subsection."
|
|
\&.text 0
|
|
\&.ascii "This lives in the first text section,"
|
|
\&.ascii "immediately following the asterisk (*)."
|
|
.Ed
|
|
.Pp
|
|
Each section has a
|
|
.Em location counter
|
|
incremented by one for every byte assembled into that section. Because subsections
|
|
are merely a convenience restricted to
|
|
.Xr as
|
|
there is no concept of a subsection location counter. There is no way to directly
|
|
manipulate a location counter---but the
|
|
.Li .align
|
|
directive changes it, and any label definition captures its current value.
|
|
The location counter of the section where statements are being assembled is
|
|
said to be the
|
|
.Em active
|
|
location counter.
|
|
.Pp
|
|
.Ss bss Section
|
|
The bss section is used for local common variable storage. You may allocate
|
|
address space in the bss section, but you may not dictate data to load into
|
|
it before your program executes. When your program starts running, all the
|
|
contents of the bss section are zeroed bytes.
|
|
.Pp
|
|
The
|
|
.Li .lcomm
|
|
pseudo-op defines a symbol in the bss section; see Lcomm,,
|
|
.Li .lcomm
|
|
\&.
|
|
.Pp
|
|
The
|
|
.Li .comm
|
|
pseudo-op may be used to declare a common symbol, which is another form of
|
|
uninitialized symbol; see Comm,,
|
|
.Li .comm
|
|
\&.
|
|
.Pp
|
|
.Sh Symbols
|
|
Symbols are a central concept: the programmer uses symbols to name things,
|
|
the linker uses symbols to link, and the debugger uses symbols to debug.
|
|
.Pp
|
|
.Qo
|
|
.Em Warning:
|
|
.Xr as
|
|
does not place symbols in the object file in the same order they were declared.
|
|
This may break some debuggers.
|
|
.Qc
|
|
.Pp
|
|
.Ss Labels
|
|
A
|
|
.Em label
|
|
is written as a symbol immediately followed by a colon
|
|
.Li : .
|
|
The symbol then represents the current value of the active location counter,
|
|
and is, for example, a suitable instruction operand. You are warned if you
|
|
use the same symbol to represent two different locations: the first definition
|
|
overrides any other definitions.
|
|
.Pp
|
|
.Ss Giving Symbols Other Values
|
|
A symbol can be given an arbitrary value by writing a symbol, followed by
|
|
an equals sign
|
|
.Li = ,
|
|
followed by an expression (see Section
|
|
.Dq Expressions ) .
|
|
This is equivalent to using the
|
|
.Li .set
|
|
directive.See Section
|
|
.Dq Set .
|
|
In the same way, using a double equals sign
|
|
.Li =
|
|
.Li =
|
|
here represents an equivalent of the
|
|
.Li .eqv
|
|
directive.See Section
|
|
.Dq Eqv .
|
|
.Pp
|
|
.Ss Symbol Names
|
|
Symbol names begin with a letter or with one of
|
|
.Li ._ .
|
|
On most machines, you can also use
|
|
.Li $
|
|
in symbol names; exceptions are noted in Machine Dependencies. That character
|
|
may be followed by any string of digits, letters, dollar signs (unless otherwise
|
|
noted for a particular target machine), and underscores.
|
|
.Pp
|
|
Case of letters is significant:
|
|
.Li foo
|
|
is a different symbol name than
|
|
.Li Foo .
|
|
.Pp
|
|
Each symbol has exactly one name. Each name in an assembly language program
|
|
refers to exactly one symbol. You may use that symbol name any number of times
|
|
in a program.
|
|
.Pp
|
|
.Em Local Symbol Names
|
|
.Pp
|
|
A local symbol is any symbol beginning with certain local label prefixes.
|
|
By default, the local label prefix is
|
|
.Li .L
|
|
for ELF systems or
|
|
.Li L
|
|
for traditional a.out systems, but each target may have its own set of local
|
|
label prefixes.
|
|
.Pp
|
|
Local symbols are defined and used within the assembler, but they are normally
|
|
not saved in object files. Thus, they are not visible when debugging. You
|
|
may use the
|
|
.Li -L
|
|
option (see Section
|
|
.Dq L )
|
|
to retain the local symbols in the object files.
|
|
.Pp
|
|
.Em Local Labels
|
|
.Pp
|
|
Local labels help compilers and programmers use names temporarily. They create
|
|
symbols which are guaranteed to be unique over the entire scope of the input
|
|
source code and which can be referred to by a simple notation. To define a
|
|
local label, write a label of the form
|
|
.Li Sy N:
|
|
(where
|
|
.Sy N
|
|
represents any positive integer). To refer to the most recent previous definition
|
|
of that label write
|
|
.Li Sy Nb ,
|
|
using the same number as when you defined the label. To refer to the next
|
|
definition of a local label, write
|
|
.Li Sy Nf
|
|
---the
|
|
.Li b
|
|
stands for \(lqbackwards\(rq and the
|
|
.Li f
|
|
stands for \(lqforwards\(rq.
|
|
.Pp
|
|
There is no restriction on how you can use these labels, and you can reuse
|
|
them too. So that it is possible to repeatedly define the same local label
|
|
(using the same number
|
|
.Li Sy N ) ,
|
|
although you can only refer to the most recently defined local label of that
|
|
number (for a backwards reference) or the next definition of a specific local
|
|
label for a forward reference. It is also worth noting that the first 10 local
|
|
labels (
|
|
.Li Sy 0:
|
|
\&....Li Sy 9: )
|
|
are implemented in a slightly more efficient manner than the others.
|
|
.Pp
|
|
Here is an example:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
1: branch 1f
|
|
2: branch 1b
|
|
1: branch 2f
|
|
2: branch 1b
|
|
.Ed
|
|
.Pp
|
|
Which is the equivalent of:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
label_1: branch label_3
|
|
label_2: branch label_1
|
|
label_3: branch label_4
|
|
label_4: branch label_3
|
|
.Ed
|
|
.Pp
|
|
Local label names are only a notational device. They are immediately transformed
|
|
into more conventional symbol names before the assembler uses them. The symbol
|
|
names are stored in the symbol table, appear in error messages, and are optionally
|
|
emitted to the object file. The names are constructed using these parts:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It Em local label prefix
|
|
All local symbols begin with the system-specific local label prefix. Normally
|
|
both
|
|
.Xr as
|
|
and
|
|
.Li ld
|
|
forget symbols that start with the local label prefix. These labels are used
|
|
for symbols you are never intended to see. If you use the
|
|
.Li -L
|
|
option then
|
|
.Xr as
|
|
retains these symbols in the object file. If you also instruct
|
|
.Li ld
|
|
to retain these symbols, you may use them in debugging.
|
|
.Pp
|
|
.It Va number
|
|
This is the number that was used in the local label definition. So if the
|
|
label is written
|
|
.Li 55:
|
|
then the number is
|
|
.Li 55 .
|
|
.Pp
|
|
.It Li C-B
|
|
This unusual character is included so you do not accidentally invent a symbol
|
|
of the same name. The character has ASCII value of
|
|
.Li \e002
|
|
(control-B).
|
|
.Pp
|
|
.It Em ordinal number
|
|
This is a serial number to keep the labels distinct. The first definition
|
|
of
|
|
.Li 0:
|
|
gets the number
|
|
.Li 1 .
|
|
The 15th definition of
|
|
.Li 0:
|
|
gets the number
|
|
.Li 15 ,
|
|
and so on. Likewise the first definition of
|
|
.Li 1:
|
|
gets the number
|
|
.Li 1
|
|
and its 15th definition gets
|
|
.Li 15
|
|
as well.
|
|
.El
|
|
.Pp
|
|
So for example, the first
|
|
.Li 1:
|
|
may be named
|
|
.Li .L1 Li C-B1 ,
|
|
and the 44th
|
|
.Li 3:
|
|
may be named
|
|
.Li .L3 Li C-B44 .
|
|
.Pp
|
|
.Em Dollar Local Labels
|
|
.Pp
|
|
.Li as
|
|
also supports an even more local form of local labels called dollar labels.
|
|
These labels go out of scope (i.e., they become undefined) as soon as a non-local
|
|
label is defined. Thus they remain valid for only a small region of the input
|
|
source code. Normal local labels, by contrast, remain in scope for the entire
|
|
file, or until they are redefined by another occurrence of the same local
|
|
label.
|
|
.Pp
|
|
Dollar labels are defined in exactly the same way as ordinary local labels,
|
|
except that instead of being terminated by a colon, they are terminated by
|
|
a dollar sign, e.g.,
|
|
.Li Sy 55$ .
|
|
.Pp
|
|
They can also be distinguished from ordinary local labels by their transformed
|
|
names which use ASCII character
|
|
.Li \e001
|
|
(control-A) as the magic character to distinguish them from ordinary labels.
|
|
For example, the fifth definition of
|
|
.Li 6$
|
|
may be named
|
|
.Li .L6 Li C-A5 .
|
|
.Pp
|
|
.Ss The Special Dot Symbol
|
|
The special symbol
|
|
.Li .
|
|
refers to the current address that
|
|
.Xr as
|
|
is assembling into. Thus, the expression
|
|
.Li melvin: .long .
|
|
defines
|
|
.Li melvin
|
|
to contain its own address. Assigning a value to
|
|
.Li .
|
|
is treated the same as a
|
|
.Li .org
|
|
directive. Thus, the expression
|
|
.Li .=.+4
|
|
is the same as saying
|
|
.Li .space 4 .
|
|
.Pp
|
|
.Ss Symbol Attributes
|
|
Every symbol has, as well as its name, the attributes \(lqValue\(rq and \(lqType\(rq. Depending
|
|
on output format, symbols can also have auxiliary attributes. The detailed
|
|
definitions are in
|
|
.Pa a.out.h .
|
|
.Pp
|
|
If you use a symbol without defining it,
|
|
.Xr as
|
|
assumes zero for all these attributes, and probably won't warn you. This makes
|
|
the symbol an externally defined symbol, which is generally what you would
|
|
want.
|
|
.Pp
|
|
.Em Value
|
|
.Pp
|
|
The value of a symbol is (usually) 32 bits. For a symbol which labels a location
|
|
in the text, data, bss or absolute sections the value is the number of addresses
|
|
from the start of that section to the label. Naturally for text, data and
|
|
bss sections the value of a symbol changes as
|
|
.Li ld
|
|
changes section base addresses during linking. Absolute symbols' values do
|
|
not change during linking: that is why they are called absolute.
|
|
.Pp
|
|
The value of an undefined symbol is treated in a special way. If it is 0 then
|
|
the symbol is not defined in this assembler source file, and
|
|
.Li ld
|
|
tries to determine its value from other files linked into the same program.
|
|
You make this kind of symbol simply by mentioning a symbol name without defining
|
|
it. A non-zero value represents a
|
|
.Li .comm
|
|
common declaration. The value is how much common storage to reserve, in bytes
|
|
(addresses). The symbol refers to the first address of the allocated storage.
|
|
.Pp
|
|
.Em Type
|
|
.Pp
|
|
The type attribute of a symbol contains relocation (section) information,
|
|
any flag settings indicating that a symbol is external, and (optionally),
|
|
other information for linkers and debuggers. The exact format depends on the
|
|
object-code output format in use.
|
|
.Pp
|
|
.Sh Expressions
|
|
An
|
|
.Em expression
|
|
specifies an address or numeric value. Whitespace may precede and/or follow
|
|
an expression.
|
|
.Pp
|
|
The result of an expression must be an absolute number, or else an offset
|
|
into a particular section. If an expression is not absolute, and there is
|
|
not enough information when
|
|
.Xr as
|
|
sees the expression to know its section, a second pass over the source program
|
|
might be necessary to interpret the expression---but the second pass is currently
|
|
not implemented.
|
|
.Xr as
|
|
aborts with an error message in this situation.
|
|
.Pp
|
|
.Ss Empty Expressions
|
|
An empty expression has no value: it is just whitespace or null. Wherever
|
|
an absolute expression is required, you may omit the expression, and
|
|
.Xr as
|
|
assumes a value of (absolute) 0. This is compatible with other assemblers.
|
|
.Pp
|
|
.Ss Integer Expressions
|
|
An
|
|
.Em integer expression
|
|
is one or more
|
|
.Em arguments
|
|
delimited by
|
|
.Em operators .
|
|
.Pp
|
|
.Em Arguments
|
|
.Pp
|
|
.Em Arguments
|
|
are symbols, numbers or subexpressions. In other contexts arguments are sometimes
|
|
called \(lqarithmetic operands\(rq. In this manual, to avoid confusing them with the
|
|
\(lqinstruction operands\(rq of the machine language, we use the term \(lqargument\(rq to
|
|
refer to parts of expressions only, reserving the word \(lqoperand\(rq to refer only
|
|
to machine instruction operands.
|
|
.Pp
|
|
Symbols are evaluated to yield {
|
|
.Va section
|
|
.Va NNN
|
|
}where
|
|
.Va section
|
|
is one of text, data, bss, absolute, or undefined.
|
|
.Va NNN
|
|
is a signed, 2's complement 32 bit integer.
|
|
.Pp
|
|
Numbers are usually integers.
|
|
.Pp
|
|
A number can be a flonum or biGNUm. In this case, you are warned that only
|
|
the low order 32 bits are used, and
|
|
.Xr as
|
|
pretends these 32 bits are an integer. You may write integer-manipulating
|
|
instructions that act on exotic constants, compatible with other assemblers.
|
|
.Pp
|
|
Subexpressions are a left parenthesis
|
|
.Li (
|
|
followed by an integer expression, followed by a right parenthesis
|
|
.Li ) ;
|
|
or a prefix operator followed by an argument.
|
|
.Pp
|
|
.Em Operators
|
|
.Pp
|
|
.Em Operators
|
|
are arithmetic functions, like
|
|
.Li +
|
|
or
|
|
.Li % .
|
|
Prefix operators are followed by an argument. Infix operators appear between
|
|
their arguments. Operators may be preceded and/or followed by whitespace.
|
|
.Pp
|
|
.Em Prefix Operator
|
|
.Pp
|
|
.Xr as
|
|
has the following
|
|
.Em prefix operators .
|
|
They each take one argument, which must be absolute.
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It -
|
|
.Em Negation .
|
|
Two's complement negation.
|
|
.It ~
|
|
.Em Complementation .
|
|
Bitwise not.
|
|
.El
|
|
.Pp
|
|
.Em Infix Operators
|
|
.Pp
|
|
.Em Infix operators
|
|
take two arguments, one on either side. Operators have precedence, but operations
|
|
with equal precedence are performed left to right. Apart from
|
|
.Li +
|
|
or
|
|
.Op - ,
|
|
both arguments must be absolute, and the result is absolute.
|
|
.Pp
|
|
.Bl -enum
|
|
.It
|
|
Highest Precedence
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It *
|
|
.Em Multiplication .
|
|
.Pp
|
|
.It /
|
|
.Em Division .
|
|
Truncation is the same as the C operator
|
|
.Li /
|
|
.Pp
|
|
.It %
|
|
.Em Remainder .
|
|
.Pp
|
|
.It <<
|
|
.Em Shift Left .
|
|
Same as the C operator
|
|
.Li << .
|
|
.Pp
|
|
.It >>
|
|
.Em Shift Right .
|
|
Same as the C operator
|
|
.Li >> .
|
|
.El
|
|
.Pp
|
|
.It
|
|
Intermediate precedence
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It |
|
|
.Pp
|
|
.Em Bitwise Inclusive Or .
|
|
.Pp
|
|
.It &
|
|
.Em Bitwise And .
|
|
.Pp
|
|
.It ^
|
|
.Em Bitwise Exclusive Or .
|
|
.Pp
|
|
.It !
|
|
.Em Bitwise Or Not .
|
|
.El
|
|
.Pp
|
|
.It
|
|
Low Precedence
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It +
|
|
.Em Addition .
|
|
If either argument is absolute, the result has the section of the other argument.
|
|
You may not add together arguments from different sections.
|
|
.Pp
|
|
.It -
|
|
.Em 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.
|
|
You may not subtract arguments from different sections.
|
|
.Pp
|
|
.It ==
|
|
.Em Is Equal To
|
|
.It <>
|
|
.It !=
|
|
.Em Is Not Equal To
|
|
.It <
|
|
.Em Is Less Than
|
|
.It >
|
|
.Em Is Greater Than
|
|
.It >=
|
|
.Em Is Greater Than Or Equal To
|
|
.It <=
|
|
.Em Is Less Than Or Equal To
|
|
.Pp
|
|
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.
|
|
.El
|
|
.Pp
|
|
.It
|
|
Lowest Precedence
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It &&
|
|
.Em Logical And .
|
|
.Pp
|
|
.It ||
|
|
.Em Logical Or .
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.El
|
|
.El
|
|
In short, it's only meaningful to add or subtract the
|
|
.Em offsets
|
|
in an address; you can only have a defined section in one of the two arguments.
|
|
.Pp
|
|
.Sh Assembler Directives
|
|
All assembler directives have names that begin with a period (
|
|
.Li . ) .
|
|
The rest of the name is letters, usually in lower case.
|
|
.Pp
|
|
This chapter discusses directives that are available regardless of the target
|
|
machine configuration for the GNU assembler.
|
|
.Pp
|
|
.Ss Li .abort
|
|
This directive stops the assembly immediately. It is for compatibility with
|
|
other assemblers. The original idea was that the assembly language source
|
|
would be piped into the assembler. If the sender of the source quit, it could
|
|
use this directive tells
|
|
.Xr as
|
|
to quit also. One day
|
|
.Li .abort
|
|
will not be supported.
|
|
.Pp
|
|
.Ss Li .align Va abs-expr, Va abs-expr, Va abs-expr
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The way the required alignment is specified varies from system to system.
|
|
For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, s390, sparc,
|
|
tic4x, tic80 and xtensa, the first expression is the alignment request in
|
|
bytes. For example
|
|
.Li .align 8
|
|
advances the location counter until it is a multiple of 8. If the location
|
|
counter is already a multiple of 8, no change is needed. For the tic54x, the
|
|
first expression is the alignment request in words.
|
|
.Pp
|
|
For other systems, including the i386 using a.out format, and the arm and
|
|
strongarm, it is the number of low-order zero bits the location counter must
|
|
have after advancement. For example
|
|
.Li .align 3
|
|
advances the location counter until it a multiple of 8. If the location counter
|
|
is already a multiple of 8, no change is needed.
|
|
.Pp
|
|
This inconsistency is due to the different behaviors of the various native
|
|
assemblers for these systems which GAS must emulate. GAS also provides
|
|
.Li .balign
|
|
and
|
|
.Li .p2align
|
|
directives, described later, which have a consistent behavior across all architectures
|
|
(but are specific to GAS).
|
|
.Pp
|
|
.Ss Li .ascii " Va string"...
|
|
.Li .ascii
|
|
expects zero or more string literals (see Section
|
|
.Dq Strings )
|
|
separated by commas. It assembles each string (with no automatic trailing
|
|
zero byte) into consecutive addresses.
|
|
.Pp
|
|
.Ss Li .asciz " Va string"...
|
|
.Li .asciz
|
|
is just like
|
|
.Li .ascii ,
|
|
but each string is followed by a zero byte. The \(lqz\(rq in
|
|
.Li .asciz
|
|
stands for \(lqzero\(rq.
|
|
.Pp
|
|
.Ss Li .balign[wl] Va abs-expr, Va abs-expr, Va abs-expr
|
|
Pad the location counter (in the current subsection) to a particular storage
|
|
boundary. The first expression (which must be absolute) is the alignment request
|
|
in bytes. For example
|
|
.Li .balign 8
|
|
advances the location counter until it is a multiple of 8. If the location
|
|
counter is already a multiple of 8, no change is needed.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The
|
|
.Li .balignw
|
|
and
|
|
.Li .balignl
|
|
directives are variants of the
|
|
.Li .balign
|
|
directive. The
|
|
.Li .balignw
|
|
directive treats the fill pattern as a two byte word value. The
|
|
.Li .balignl
|
|
directives treats the fill pattern as a four byte longword value. For example,
|
|
.Li .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.
|
|
.Pp
|
|
.Ss Li .byte Va expressions
|
|
.Li .byte
|
|
expects zero or more expressions, separated by commas. Each expression is
|
|
assembled into the next byte.
|
|
.Pp
|
|
.Ss Li .comm Va symbol , Va length
|
|
.Li .comm
|
|
declares a common symbol named
|
|
.Va 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
|
|
.Li ld
|
|
does not see a definition for the symbol--just one or more common symbols--then
|
|
it will allocate
|
|
.Va length
|
|
bytes of uninitialized memory.
|
|
.Va length
|
|
must be an absolute expression. If
|
|
.Li 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.
|
|
.Pp
|
|
When using ELF, the
|
|
.Li .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
|
|
.Li ld
|
|
allocates uninitialized memory for the common symbol, it will use the alignment
|
|
when placing the symbol. If no alignment is specified,
|
|
.Xr 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.
|
|
.Pp
|
|
.Ss Li .cfi_startproc [simple]
|
|
.Li .cfi_startproc
|
|
is used at the beginning of each function that should have an entry in
|
|
.Li .eh_frame .
|
|
It initializes some internal data structures. Don't forget to close the function
|
|
by
|
|
.Li .cfi_endproc .
|
|
.Pp
|
|
Unless
|
|
.Li .cfi_startproc
|
|
is used along with parameter
|
|
.Li simple
|
|
it also emits some architecture dependent initial CFI instructions.
|
|
.Ss Li .cfi_endproc
|
|
.Li .cfi_endproc
|
|
is used at the end of a function where it closes its unwind entry previously
|
|
opened by
|
|
.Li .cfi_startproc ,
|
|
and emits it to
|
|
.Li .eh_frame .
|
|
.Pp
|
|
.Ss Li .cfi_personality Va encoding [, Va exp]
|
|
.Li .cfi_personality
|
|
defines personality routine and its encoding.
|
|
.Va encoding
|
|
must be a constant determining how the personality should be encoded. If it
|
|
is 255 (
|
|
.Li DW_EH_PE_omit ) ,
|
|
second argument is not present, otherwise second argument should be a constant
|
|
or a symbol name. When using indirect encodings, the symbol provided should
|
|
be the location where personality can be loaded from, not the personality
|
|
routine itself. The default after
|
|
.Li .cfi_startproc
|
|
is
|
|
.Li .cfi_personality 0xff ,
|
|
no personality routine.
|
|
.Pp
|
|
.Ss Li .cfi_lsda Va encoding [, Va exp]
|
|
.Li .cfi_lsda
|
|
defines LSDA and its encoding.
|
|
.Va encoding
|
|
must be a constant determining how the LSDA should be encoded. If it is 255
|
|
(
|
|
.Li DW_EH_PE_omit ) ,
|
|
second argument is not present, otherwise second argument should be a constant
|
|
or a symbol name. The default after
|
|
.Li .cfi_startproc
|
|
is
|
|
.Li .cfi_lsda 0xff ,
|
|
no LSDA.
|
|
.Pp
|
|
.Ss Li .cfi_def_cfa Va register, Va offset
|
|
.Li .cfi_def_cfa
|
|
defines a rule for computing CFA as:
|
|
.Em take address from Va register and add Va offset to it .
|
|
.Pp
|
|
.Ss Li .cfi_def_cfa_register Va register
|
|
.Li .cfi_def_cfa_register
|
|
modifies a rule for computing CFA. From now on
|
|
.Va register
|
|
will be used instead of the old one. Offset remains the same.
|
|
.Pp
|
|
.Ss Li .cfi_def_cfa_offset Va offset
|
|
.Li .cfi_def_cfa_offset
|
|
modifies a rule for computing CFA. Register remains the same, but
|
|
.Va offset
|
|
is new. Note that it is the absolute offset that will be added to a defined
|
|
register to compute CFA address.
|
|
.Pp
|
|
.Ss Li .cfi_adjust_cfa_offset Va offset
|
|
Same as
|
|
.Li .cfi_def_cfa_offset
|
|
but
|
|
.Va offset
|
|
is a relative value that is added/substracted from the previous offset.
|
|
.Pp
|
|
.Ss Li .cfi_offset Va register, Va offset
|
|
Previous value of
|
|
.Va register
|
|
is saved at offset
|
|
.Va offset
|
|
from CFA.
|
|
.Pp
|
|
.Ss Li .cfi_rel_offset Va register, Va offset
|
|
Previous value of
|
|
.Va register
|
|
is saved at offset
|
|
.Va offset
|
|
from the current CFA register. This is transformed to
|
|
.Li .cfi_offset
|
|
using the known displacement of the CFA register from the CFA. This is often
|
|
easier to use, because the number will match the code it's annotating.
|
|
.Pp
|
|
.Ss Li .cfi_register Va register1, Va register2
|
|
Previous value of
|
|
.Va register1
|
|
is saved in register
|
|
.Va register2 .
|
|
.Pp
|
|
.Ss Li .cfi_restore Va register
|
|
.Li .cfi_restore
|
|
says that the rule for
|
|
.Va register
|
|
is now the same as it was at the beginning of the function, after all initial
|
|
instruction added by
|
|
.Li .cfi_startproc
|
|
were executed.
|
|
.Pp
|
|
.Ss Li .cfi_undefined Va register
|
|
From now on the previous value of
|
|
.Va register
|
|
can't be restored anymore.
|
|
.Pp
|
|
.Ss Li .cfi_same_value Va register
|
|
Current value of
|
|
.Va register
|
|
is the same like in the previous frame, i.e. no restoration needed.
|
|
.Pp
|
|
.Ss Li .cfi_remember_state,
|
|
First save all current rules for all registers by
|
|
.Li .cfi_remember_state ,
|
|
then totally screw them up by subsequent
|
|
.Li .cfi_*
|
|
directives and when everything is hopelessly bad, use
|
|
.Li .cfi_restore_state
|
|
to restore the previous saved state.
|
|
.Pp
|
|
.Ss Li .cfi_return_column Va register
|
|
Change return column
|
|
.Va register ,
|
|
i.e. the return address is either directly in
|
|
.Va register
|
|
or can be accessed by rules for
|
|
.Va register .
|
|
.Pp
|
|
.Ss Li .cfi_signal_frame
|
|
Mark current function as signal trampoline.
|
|
.Pp
|
|
.Ss Li .cfi_window_save
|
|
SPARC register window has been saved.
|
|
.Pp
|
|
.Ss Li .cfi_escape Va expression[, ...]
|
|
Allows the user to add arbitrary bytes to the unwind info. One might use this
|
|
to add OS-specific CFI opcodes, or generic CFI opcodes that GAS does not yet
|
|
support.
|
|
.Pp
|
|
.Ss Li .file Va fileno Va filename
|
|
When emitting dwarf2 line number information
|
|
.Li .file
|
|
assigns filenames to the
|
|
.Li .debug_line
|
|
file name table. The
|
|
.Va fileno
|
|
operand should be a unique positive integer to use as the index of the entry
|
|
in the table. The
|
|
.Va filename
|
|
operand is a C string literal.
|
|
.Pp
|
|
The detail of filename indices is exposed to the user because the filename
|
|
table is shared with the
|
|
.Li .debug_info
|
|
section of the dwarf2 debugging information, and thus the user must know the
|
|
exact indices that table entries will have.
|
|
.Pp
|
|
.Ss Li .loc Va fileno Va lineno [ Va column] [ Va options]
|
|
The
|
|
.Li .loc
|
|
directive will add row to the
|
|
.Li .debug_line
|
|
line number matrix corresponding to the immediately following assembly instruction.
|
|
The
|
|
.Va fileno ,
|
|
.Va lineno ,
|
|
and optional
|
|
.Va column
|
|
arguments will be applied to the
|
|
.Li .debug_line
|
|
state machine before the row is added.
|
|
.Pp
|
|
The
|
|
.Va options
|
|
are a sequence of the following tokens in any order:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It basic_block
|
|
This option will set the
|
|
.Li basic_block
|
|
register in the
|
|
.Li .debug_line
|
|
state machine to
|
|
.Li true .
|
|
.Pp
|
|
.It prologue_end
|
|
This option will set the
|
|
.Li prologue_end
|
|
register in the
|
|
.Li .debug_line
|
|
state machine to
|
|
.Li true .
|
|
.Pp
|
|
.It epilogue_begin
|
|
This option will set the
|
|
.Li epilogue_begin
|
|
register in the
|
|
.Li .debug_line
|
|
state machine to
|
|
.Li true .
|
|
.Pp
|
|
.It is_stmt Va value
|
|
This option will set the
|
|
.Li is_stmt
|
|
register in the
|
|
.Li .debug_line
|
|
state machine to
|
|
.Li value ,
|
|
which must be either 0 or 1.
|
|
.Pp
|
|
.It isa Va value
|
|
This directive will set the
|
|
.Li isa
|
|
register in the
|
|
.Li .debug_line
|
|
state machine to
|
|
.Va value ,
|
|
which must be an unsigned integer.
|
|
.Pp
|
|
.El
|
|
.Ss Li .loc_mark_blocks Va enable
|
|
The
|
|
.Li .loc_mark_blocks
|
|
directive makes the assembler emit an entry to the
|
|
.Li .debug_line
|
|
line number matrix with the
|
|
.Li basic_block
|
|
register in the state machine set whenever a code label is seen. The
|
|
.Va enable
|
|
argument should be either 1 or 0, to enable or disable this function respectively.
|
|
.Pp
|
|
.Ss Li .data Va subsection
|
|
.Li .data
|
|
tells
|
|
.Xr as
|
|
to assemble the following statements onto the end of the data subsection numbered
|
|
.Va subsection
|
|
(which is an absolute expression). If
|
|
.Va subsection
|
|
is omitted, it defaults to zero.
|
|
.Pp
|
|
.Ss Li .double Va flonums
|
|
.Li .double
|
|
expects zero or more flonums, separated by commas. It assembles floating point
|
|
numbers.
|
|
.Pp
|
|
.Ss Li .eject
|
|
Force a page break at this point, when generating assembly listings.
|
|
.Pp
|
|
.Ss Li .else
|
|
.Li .else
|
|
is part of the
|
|
.Xr as
|
|
support for conditional assembly; see If,,
|
|
.Li .if
|
|
\&. It marks the beginning of a section of code to be assembled if the condition
|
|
for the preceding
|
|
.Li .if
|
|
was false.
|
|
.Pp
|
|
.Ss Li .elseif
|
|
.Li .elseif
|
|
is part of the
|
|
.Xr as
|
|
support for conditional assembly; see If,,
|
|
.Li .if
|
|
\&. It is shorthand for beginning a new
|
|
.Li .if
|
|
block that would otherwise fill the entire
|
|
.Li .else
|
|
section.
|
|
.Pp
|
|
.Ss Li .end
|
|
.Li .end
|
|
marks the end of the assembly file.
|
|
.Xr as
|
|
does not process anything in the file past the
|
|
.Li .end
|
|
directive.
|
|
.Pp
|
|
.Ss Li .endfunc
|
|
.Li .endfunc
|
|
marks the end of a function specified with
|
|
.Li .func .
|
|
.Pp
|
|
.Ss Li .endif
|
|
.Li .endif
|
|
is part of the
|
|
.Xr as
|
|
support for conditional assembly; it marks the end of a block of code that
|
|
is only assembled conditionally.See Section
|
|
.Dq If .
|
|
.Pp
|
|
.Ss Li .equ Va symbol, Va expression
|
|
This directive sets the value of
|
|
.Va symbol
|
|
to
|
|
.Va expression .
|
|
It is synonymous with
|
|
.Li .set ;
|
|
see Set,,
|
|
.Li .set
|
|
\&.
|
|
.Pp
|
|
.Ss Li .equiv Va symbol, Va expression
|
|
The
|
|
.Li .equiv
|
|
directive is like
|
|
.Li .equ
|
|
and
|
|
.Li .set ,
|
|
except that the assembler will signal an error if
|
|
.Va symbol
|
|
is already defined. Note a symbol which has been referenced but not actually
|
|
defined is considered to be undefined.
|
|
.Pp
|
|
Except for the contents of the error message, this is roughly equivalent to
|
|
.Bd -literal -offset indent
|
|
\&.ifdef SYM
|
|
\&.err
|
|
\&.endif
|
|
\&.equ SYM,VAL
|
|
.Ed
|
|
plus it protects the symbol from later redefinition.
|
|
.Pp
|
|
.Ss Li .eqv Va symbol, Va expression
|
|
The
|
|
.Li .eqv
|
|
directive is like
|
|
.Li .equiv ,
|
|
but no attempt is made to evaluate the expression or any part of it immediately.
|
|
Instead each time the resulting symbol is used in an expression, a snapshot
|
|
of its current value is taken.
|
|
.Pp
|
|
.Ss Li .err
|
|
If
|
|
.Xr as
|
|
assembles a
|
|
.Li .err
|
|
directive, it will print an error message and, unless the
|
|
.Op -Z
|
|
option was used, it will not generate an object file. This can be used to
|
|
signal an error in conditionally compiled code.
|
|
.Pp
|
|
.Ss Li .error " Va string"
|
|
Similarly to
|
|
.Li .err ,
|
|
this directive emits an error, but you can specify a string that will be emitted
|
|
as the error message. If you don't specify the message, it defaults to
|
|
.Li ".error directive invoked in source file" .
|
|
See Section.Dq Errors .
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.error "This code has not been assembled and tested."
|
|
.Ed
|
|
.Pp
|
|
.Ss Li .exitm
|
|
Exit early from the current macro definition.See Section
|
|
.Dq Macro .
|
|
.Pp
|
|
.Ss Li .extern
|
|
.Li .extern
|
|
is accepted in the source program---for compatibility with other assemblers---but
|
|
it is ignored.
|
|
.Xr as
|
|
treats all undefined symbols as external.
|
|
.Pp
|
|
.Ss Li .fail Va expression
|
|
Generates an error or a warning. If the value of the
|
|
.Va expression
|
|
is 500 or more,
|
|
.Xr as
|
|
will print a warning message. If the value is less than 500,
|
|
.Xr as
|
|
will print an error message. The message will include the value of
|
|
.Va expression .
|
|
This can occasionally be useful inside complex nested macros or conditional
|
|
assembly.
|
|
.Pp
|
|
.Ss Li .file Va string
|
|
.Li .file
|
|
tells
|
|
.Xr as
|
|
that we are about to start a new logical file.
|
|
.Va string
|
|
is the new file name. In general, the filename is recognized whether or not
|
|
it is surrounded by quotes
|
|
.Li " ;
|
|
but if you wish to specify an empty file name, you must give the quotes--
|
|
.Li "" .
|
|
This statement may go away in future: it is only recognized to be compatible
|
|
with old
|
|
.Xr as
|
|
programs.
|
|
.Pp
|
|
.Ss Li .fill Va repeat , Va size , Va value
|
|
.Va repeat ,
|
|
.Va size
|
|
and
|
|
.Va value
|
|
are absolute expressions. This emits
|
|
.Va repeat
|
|
copies of
|
|
.Va size
|
|
bytes.
|
|
.Va Repeat
|
|
may be zero or more.
|
|
.Va Size
|
|
may be zero or more, but if it is more than 8, then it is deemed to have the
|
|
value 8, compatible with other people's assemblers. The contents of each
|
|
.Va repeat
|
|
bytes is taken from an 8-byte number. The highest order 4 bytes are zero.
|
|
The lowest order 4 bytes are
|
|
.Va value
|
|
rendered in the byte-order of an integer on the computer
|
|
.Xr as
|
|
is assembling for. Each
|
|
.Va size
|
|
bytes in a repetition is taken from the lowest order
|
|
.Va size
|
|
bytes of this number. Again, this bizarre behavior is compatible with other
|
|
people's assemblers.
|
|
.Pp
|
|
.Va size
|
|
and
|
|
.Va value
|
|
are optional. If the second comma and
|
|
.Va value
|
|
are absent,
|
|
.Va value
|
|
is assumed zero. If the first comma and following tokens are absent,
|
|
.Va size
|
|
is assumed to be 1.
|
|
.Pp
|
|
.Ss Li .float Va flonums
|
|
This directive assembles zero or more flonums, separated by commas. It has
|
|
the same effect as
|
|
.Li .single .
|
|
.Pp
|
|
.Ss Li .func Va name[, Va label]
|
|
.Li .func
|
|
emits debugging information to denote function
|
|
.Va name ,
|
|
and is ignored unless the file is assembled with debugging enabled. Only
|
|
.Li --gstabs[+]
|
|
is currently supported.
|
|
.Va label
|
|
is the entry point of the function and if omitted
|
|
.Va name
|
|
prepended with the
|
|
.Li leading char
|
|
is used.
|
|
.Li leading char
|
|
is usually
|
|
.Li _
|
|
or nothing, depending on the target. All functions are currently defined to
|
|
have
|
|
.Li void
|
|
return type. The function must be terminated with
|
|
.Li .endfunc .
|
|
.Pp
|
|
.Ss Li .global Va symbol, Li .globl Va symbol
|
|
.Li .global
|
|
makes the symbol visible to
|
|
.Li ld .
|
|
If you define
|
|
.Va symbol
|
|
in your partial program, its value is made available to other partial programs
|
|
that are linked with it. Otherwise,
|
|
.Va symbol
|
|
takes its attributes from a symbol of the same name from another file linked
|
|
into the same program.
|
|
.Pp
|
|
Both spellings (
|
|
.Li .globl
|
|
and
|
|
.Li .global )
|
|
are accepted, for compatibility with other assemblers.
|
|
.Pp
|
|
.Ss Li .hidden Va names
|
|
This is one of the ELF visibility directives. The other two are
|
|
.Li .internal
|
|
(see Section
|
|
.Dq Internal )
|
|
and
|
|
.Li .protected
|
|
(see Section
|
|
.Dq Protected ) .
|
|
.Pp
|
|
This directive overrides the named symbols default visibility (which is set
|
|
by their binding: local, global or weak). The directive sets the visibility
|
|
to
|
|
.Li hidden
|
|
which means that the symbols are not visible to other components. Such symbols
|
|
are always considered to be
|
|
.Li protected
|
|
as well.
|
|
.Pp
|
|
.Ss Li .hword Va expressions
|
|
This expects zero or more
|
|
.Va expressions ,
|
|
and emits a 16 bit number for each.
|
|
.Pp
|
|
This directive is a synonym for
|
|
.Li .short .
|
|
.Pp
|
|
.Ss Li .ident
|
|
This directive is used by some assemblers to place tags in object files. The
|
|
behavior of this directive varies depending on the target. When using the
|
|
a.out object file format,
|
|
.Xr as
|
|
simply accepts the directive for source-file compatibility with existing assemblers,
|
|
but does not emit anything for it. When using COFF, comments are emitted to
|
|
the
|
|
.Li .comment
|
|
or
|
|
.Li .rdata
|
|
section, depending on the target. When using ELF, comments are emitted to
|
|
the
|
|
.Li .comment
|
|
section.
|
|
.Pp
|
|
.Ss Li .if Va absolute expression
|
|
.Li .if
|
|
marks the beginning of a section of code which is only considered part of
|
|
the source program being assembled if the argument (which must be an
|
|
.Va absolute expression )
|
|
is non-zero. The end of the conditional section of code must be marked by
|
|
.Li .endif
|
|
(see Section
|
|
.Dq Endif ) ;
|
|
optionally, you may include code for the alternative condition, flagged by
|
|
.Li .else
|
|
(see Section
|
|
.Dq Else ) .
|
|
If you have several conditions to check,
|
|
.Li .elseif
|
|
may be used to avoid nesting blocks if/else within each subsequent
|
|
.Li .else
|
|
block.
|
|
.Pp
|
|
The following variants of
|
|
.Li .if
|
|
are also supported:
|
|
.Bl -tag -width Ds
|
|
.It .ifdef Va symbol
|
|
Assembles the following section of code if the specified
|
|
.Va symbol
|
|
has been defined. Note a symbol which has been referenced but not yet defined
|
|
is considered to be undefined.
|
|
.Pp
|
|
.It .ifb Va text
|
|
Assembles the following section of code if the operand is blank (empty).
|
|
.Pp
|
|
.It .ifc Va string1, Va string2
|
|
Assembles the following section of code if the two strings are the same. The
|
|
strings may be optionally quoted with single quotes. If they are not quoted,
|
|
the first string stops at the first comma, and the second string stops at
|
|
the end of the line. Strings which contain whitespace should be quoted. The
|
|
string comparison is case sensitive.
|
|
.Pp
|
|
.It .ifeq Va absolute expression
|
|
Assembles the following section of code if the argument is zero.
|
|
.Pp
|
|
.It .ifeqs Va string1, Va string2
|
|
Another form of
|
|
.Li .ifc .
|
|
The strings must be quoted using double quotes.
|
|
.Pp
|
|
.It .ifge Va absolute expression
|
|
Assembles the following section of code if the argument is greater than or
|
|
equal to zero.
|
|
.Pp
|
|
.It .ifgt Va absolute expression
|
|
Assembles the following section of code if the argument is greater than zero.
|
|
.Pp
|
|
.It .ifle Va absolute expression
|
|
Assembles the following section of code if the argument is less than or equal
|
|
to zero.
|
|
.Pp
|
|
.It .iflt Va absolute expression
|
|
Assembles the following section of code if the argument is less than zero.
|
|
.Pp
|
|
.It .ifnb Va text
|
|
Like
|
|
.Li .ifb ,
|
|
but the sense of the test is reversed: this assembles the following section
|
|
of code if the operand is non-blank (non-empty).
|
|
.Pp
|
|
.It .ifnc Va string1, Va string2.
|
|
Like
|
|
.Li .ifc ,
|
|
but the sense of the test is reversed: this assembles the following section
|
|
of code if the two strings are not the same.
|
|
.Pp
|
|
.It .ifndef Va symbol
|
|
.It .ifnotdef Va symbol
|
|
Assembles the following section of code if the specified
|
|
.Va symbol
|
|
has not been defined. Both spelling variants are equivalent. Note a symbol
|
|
which has been referenced but not yet defined is considered to be undefined.
|
|
.Pp
|
|
.It .ifne Va absolute expression
|
|
Assembles the following section of code if the argument is not equal to zero
|
|
(in other words, this is equivalent to
|
|
.Li .if ) .
|
|
.Pp
|
|
.It .ifnes Va string1, Va string2
|
|
Like
|
|
.Li .ifeqs ,
|
|
but the sense of the test is reversed: this assembles the following section
|
|
of code if the two strings are not the same.
|
|
.El
|
|
.Pp
|
|
.Ss Li .incbin " Va file"[, Va skip[, Va count]]
|
|
The
|
|
.Li incbin
|
|
directive includes
|
|
.Va file
|
|
verbatim at the current location. You can control the search paths used with
|
|
the
|
|
.Li -I
|
|
command-line option (see Section
|
|
.Dq Invoking ) .
|
|
Quotation marks are required around
|
|
.Va file .
|
|
.Pp
|
|
The
|
|
.Va skip
|
|
argument skips a number of bytes from the start of the
|
|
.Va file .
|
|
The
|
|
.Va count
|
|
argument indicates the maximum number of bytes to read. Note that the data
|
|
is not aligned in any way, so it is the user's responsibility to make sure
|
|
that proper alignment is provided both before and after the
|
|
.Li incbin
|
|
directive.
|
|
.Pp
|
|
.Ss Li .include " Va file"
|
|
This directive provides a way to include supporting files at specified points
|
|
in your source program. The code from
|
|
.Va file
|
|
is assembled as if it followed the point of the
|
|
.Li .include ;
|
|
when the end of the included file is reached, assembly of the original file
|
|
continues. You can control the search paths used with the
|
|
.Li -I
|
|
command-line option (see Section
|
|
.Dq Invoking ) .
|
|
Quotation marks are required around
|
|
.Va file .
|
|
.Pp
|
|
.Ss Li .int Va expressions
|
|
Expect zero or more
|
|
.Va expressions ,
|
|
of any section, separated by commas. For each expression, emit a number that,
|
|
at run time, is the value of that expression. The byte order and bit size
|
|
of the number depends on what kind of target the assembly is for.
|
|
.Pp
|
|
.Ss Li .internal Va names
|
|
This is one of the ELF visibility directives. The other two are
|
|
.Li .hidden
|
|
(see Section
|
|
.Dq Hidden )
|
|
and
|
|
.Li .protected
|
|
(see Section
|
|
.Dq Protected ) .
|
|
.Pp
|
|
This directive overrides the named symbols default visibility (which is set
|
|
by their binding: local, global or weak). The directive sets the visibility
|
|
to
|
|
.Li internal
|
|
which means that the symbols are considered to be
|
|
.Li hidden
|
|
(i.e., not visible to other components), and that some extra, processor specific
|
|
processing must also be performed upon the symbols as well.
|
|
.Pp
|
|
.Ss Li .irp Va symbol, Va values...
|
|
Evaluate a sequence of statements assigning different values to
|
|
.Va symbol .
|
|
The sequence of statements starts at the
|
|
.Li .irp
|
|
directive, and is terminated by an
|
|
.Li .endr
|
|
directive. For each
|
|
.Va value ,
|
|
.Va symbol
|
|
is set to
|
|
.Va value ,
|
|
and the sequence of statements is assembled. If no
|
|
.Va value
|
|
is listed, the sequence of statements is assembled once, with
|
|
.Va symbol
|
|
set to the null string. To refer to
|
|
.Va symbol
|
|
within the sequence of statements, use
|
|
.Va \esymbol .
|
|
.Pp
|
|
For example, assembling
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.irp param,1,2,3
|
|
move d\eparam,sp@-
|
|
.endr
|
|
.Ed
|
|
.Pp
|
|
is equivalent to assembling
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
move d1,sp@-
|
|
move d2,sp@-
|
|
move d3,sp@-
|
|
.Ed
|
|
.Pp
|
|
For some caveats with the spelling of
|
|
.Va symbol ,
|
|
see also Macro.
|
|
.Pp
|
|
.Ss Li .irpc Va symbol, Va values...
|
|
Evaluate a sequence of statements assigning different values to
|
|
.Va symbol .
|
|
The sequence of statements starts at the
|
|
.Li .irpc
|
|
directive, and is terminated by an
|
|
.Li .endr
|
|
directive. For each character in
|
|
.Va value ,
|
|
.Va symbol
|
|
is set to the character, and the sequence of statements is assembled. If no
|
|
.Va value
|
|
is listed, the sequence of statements is assembled once, with
|
|
.Va symbol
|
|
set to the null string. To refer to
|
|
.Va symbol
|
|
within the sequence of statements, use
|
|
.Va \esymbol .
|
|
.Pp
|
|
For example, assembling
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.irpc param,123
|
|
move d\eparam,sp@-
|
|
.endr
|
|
.Ed
|
|
.Pp
|
|
is equivalent to assembling
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
move d1,sp@-
|
|
move d2,sp@-
|
|
move d3,sp@-
|
|
.Ed
|
|
.Pp
|
|
For some caveats with the spelling of
|
|
.Va symbol ,
|
|
see also the discussion atSee Section
|
|
.Dq Macro .
|
|
.Pp
|
|
.Ss Li .lcomm Va symbol , Va length
|
|
Reserve
|
|
.Va length
|
|
(an absolute expression) bytes for a local common denoted by
|
|
.Va symbol .
|
|
The section and value of
|
|
.Va symbol
|
|
are those of the new local common. The addresses are allocated in the bss
|
|
section, so that at run-time the bytes start off zeroed.
|
|
.Va Symbol
|
|
is not declared global (see Section
|
|
.Dq Global ) ,
|
|
so is normally not visible to
|
|
.Li ld .
|
|
.Pp
|
|
.Ss Li .lflags
|
|
.Xr as
|
|
accepts this directive, for compatibility with other assemblers, but ignores
|
|
it.
|
|
.Pp
|
|
.Ss Li .line Va line-number
|
|
Even though this is a directive associated with the
|
|
.Li a.out
|
|
or
|
|
.Li b.out
|
|
object-code formats,
|
|
.Xr as
|
|
still recognizes it when producing COFF output, and treats
|
|
.Li .line
|
|
as though it were the COFF
|
|
.Li .ln
|
|
.Em if
|
|
it is found outside a
|
|
.Li .def
|
|
/
|
|
.Li .endef
|
|
pair.
|
|
.Pp
|
|
Inside a
|
|
.Li .def ,
|
|
.Li .line
|
|
is, instead, one of the directives used by compilers to generate auxiliary
|
|
symbol information for debugging.
|
|
.Pp
|
|
.Ss Li .linkonce [ Va type]
|
|
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
|
|
.Li .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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The
|
|
.Va type
|
|
argument is optional. If specified, it must be one of the following strings.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
\&.linkonce same_size
|
|
.Ed
|
|
Not all types may be supported on all object file formats.
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It discard
|
|
Silently discard duplicate sections. This is the default.
|
|
.Pp
|
|
.It one_only
|
|
Warn if there are duplicate sections, but still keep only one copy.
|
|
.Pp
|
|
.It same_size
|
|
Warn if any of the duplicates have different sizes.
|
|
.Pp
|
|
.It same_contents
|
|
Warn if any of the duplicates do not have exactly the same contents.
|
|
.El
|
|
.Pp
|
|
.Ss Li .ln Va line-number
|
|
.Li .ln
|
|
is a synonym for
|
|
.Li .line .
|
|
.Pp
|
|
.Ss Li .mri Va val
|
|
If
|
|
.Va val
|
|
is non-zero, this tells
|
|
.Xr as
|
|
to enter MRI mode. If
|
|
.Va val
|
|
is zero, this tells
|
|
.Xr as
|
|
to exit MRI mode. This change affects code assembled until the next
|
|
.Li .mri
|
|
directive, or until the end of the file.See Section
|
|
.Dq M .
|
|
.Pp
|
|
.Ss Li .list
|
|
Control (in conjunction with the
|
|
.Li .nolist
|
|
directive) whether or not assembly listings are generated. These two directives
|
|
maintain an internal counter (which is zero initially).
|
|
.Li .list
|
|
increments the counter, and
|
|
.Li .nolist
|
|
decrements it. Assembly listings are generated whenever the counter is greater
|
|
than zero.
|
|
.Pp
|
|
By default, listings are disabled. When you enable them (with the
|
|
.Li -a
|
|
command line option;see Section
|
|
.Dq Invoking ) ,
|
|
the initial value of the listing counter is one.
|
|
.Pp
|
|
.Ss Li .long Va expressions
|
|
.Li .long
|
|
is the same as
|
|
.Li .int .
|
|
See Section.Dq Int .
|
|
.Pp
|
|
.Ss Li .macro
|
|
The commands
|
|
.Li .macro
|
|
and
|
|
.Li .endm
|
|
allow you to define macros that generate assembly output. For example, this
|
|
definition specifies a macro
|
|
.Li sum
|
|
that puts a sequence of numbers into memory:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.macro sum from=0, to=5
|
|
.long \efrom
|
|
.if \eto-\efrom
|
|
sum "(\efrom+1)",\eto
|
|
.endif
|
|
.endm
|
|
.Ed
|
|
.Pp
|
|
With that definition,
|
|
.Li SUM 0,5
|
|
is equivalent to this assembly input:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.long 0
|
|
.long 1
|
|
.long 2
|
|
.long 3
|
|
.long 4
|
|
.long 5
|
|
.Ed
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It .macro Va macname
|
|
.It .macro Va macname Va macargs ...
|
|
Begin the definition of a macro called
|
|
.Va macname .
|
|
If your macro definition requires arguments, specify their names after the
|
|
macro name, separated by commas or spaces. You can qualify the macro argument
|
|
to indicate whether all invocations must specify a non-blank value (through
|
|
.Li : Li req ) ,
|
|
or whether it takes all of the remaining arguments (through
|
|
.Li : Li vararg ) .
|
|
You can supply a default value for any macro argument by following the name
|
|
with
|
|
.Li = Va deflt .
|
|
You cannot define two macros with the same
|
|
.Va macname
|
|
unless it has been subject to the
|
|
.Li .purgem
|
|
directive (see Section
|
|
.Dq Purgem )
|
|
between the two definitions. For example, these are all valid
|
|
.Li .macro
|
|
statements:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It .macro comm
|
|
Begin the definition of a macro called
|
|
.Li comm ,
|
|
which takes no arguments.
|
|
.Pp
|
|
.It .macro plus1 p, p1
|
|
.It .macro plus1 p p1
|
|
Either statement begins the definition of a macro called
|
|
.Li plus1 ,
|
|
which takes two arguments; within the macro definition, write
|
|
.Li \ep
|
|
or
|
|
.Li \ep1
|
|
to evaluate the arguments.
|
|
.Pp
|
|
.It .macro reserve_str p1=0 p2
|
|
Begin the definition of a macro called
|
|
.Li 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
|
|
.Li reserve_str Va a, Va b
|
|
(with
|
|
.Li \ep1
|
|
evaluating to
|
|
.Va a
|
|
and
|
|
.Li \ep2
|
|
evaluating to
|
|
.Va b ) ,
|
|
or as
|
|
.Li reserve_str , Va b
|
|
(with
|
|
.Li \ep1
|
|
evaluating as the default, in this case
|
|
.Li 0 ,
|
|
and
|
|
.Li \ep2
|
|
evaluating to
|
|
.Va b ) .
|
|
.Pp
|
|
.It .macro m p1:req, p2=0, p3:vararg
|
|
Begin the definition of a macro called
|
|
.Li m ,
|
|
with at least three arguments. The first argument must always have a value
|
|
specified, but not the second, which instead has a default value. The third
|
|
formal will get assigned all remaining arguments specified at invocation time.
|
|
.Pp
|
|
When you call a macro, you can specify the argument values either by position,
|
|
or by keyword. For example,
|
|
.Li sum 9,17
|
|
is equivalent to
|
|
.Li sum to=17, from=9 .
|
|
.Pp
|
|
.El
|
|
Note that since each of the
|
|
.Va macargs
|
|
can be an identifier exactly as any other one permitted by the target architecture,
|
|
there may be occasional problems if the target hand-crafts special meanings
|
|
to certain characters when they occur in a special position. For example,
|
|
if the colon (
|
|
.Li : )
|
|
is generally permitted to be part of a symbol name, but the architecture specific
|
|
code special-cases it when occurring as the final character of a symbol (to
|
|
denote a label), then the macro parameter replacement code will have no way
|
|
of knowing that and consider the whole construct (including the colon) an
|
|
identifier, and check only this identifier for being the subject to parameter
|
|
substitution. So for example this macro definition:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.macro label l
|
|
\el:
|
|
.endm
|
|
.Ed
|
|
.Pp
|
|
might not work as expected. Invoking
|
|
.Li label foo
|
|
might not create a label called
|
|
.Li foo
|
|
but instead just insert the text
|
|
.Li \el:
|
|
into the assembler source, probably generating an error about an unrecognised
|
|
identifier.
|
|
.Pp
|
|
Similarly problems might occur with the period character (
|
|
.Li . )
|
|
which is often allowed inside opcode names (and hence identifier names). So
|
|
for example constructing a macro to build an opcode from a base name and a
|
|
length specifier like this:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.macro opcode base length
|
|
\ebase.\elength
|
|
.endm
|
|
.Ed
|
|
.Pp
|
|
and invoking it as
|
|
.Li opcode store l
|
|
will not create a
|
|
.Li store.l
|
|
instruction but instead generate some kind of error as the assembler tries
|
|
to interpret the text
|
|
.Li \ebase.\elength .
|
|
.Pp
|
|
There are several possible ways around this problem:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It Insert white space
|
|
If it is possible to use white space characters then this is the simplest
|
|
solution. eg:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.macro label l
|
|
\el :
|
|
.endm
|
|
.Ed
|
|
.Pp
|
|
.It Use Li \e()
|
|
The string
|
|
.Li \e()
|
|
can be used to separate the end of a macro argument from the following text.
|
|
eg:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.macro opcode base length
|
|
\ebase\e().\elength
|
|
.endm
|
|
.Ed
|
|
.Pp
|
|
.It Use the alternate macro syntax mode
|
|
In the alternative macro syntax mode the ampersand character (
|
|
.Li & )
|
|
can be used as a separator. eg:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.altmacro
|
|
.macro label l
|
|
l&:
|
|
.endm
|
|
.Ed
|
|
.El
|
|
.Pp
|
|
Note: this problem of correctly identifying string parameters to pseudo ops
|
|
also applies to the identifiers used in
|
|
.Li .irp
|
|
(see Section
|
|
.Dq Irp )
|
|
and
|
|
.Li .irpc
|
|
(see Section
|
|
.Dq Irpc )
|
|
as well.
|
|
.Pp
|
|
.It .endm
|
|
Mark the end of a macro definition.
|
|
.Pp
|
|
.It .exitm
|
|
Exit early from the current macro definition.
|
|
.Pp
|
|
.It \e@
|
|
.Xr as
|
|
maintains a counter of how many macros it has executed in this pseudo-variable;
|
|
you can copy that number to your output with
|
|
.Li \e@ ,
|
|
but
|
|
.Em only within a macro definition .
|
|
.Pp
|
|
.It LOCAL Va name [ , ... ]
|
|
.Em Warning: Li LOCAL is only available if you select \(lqalternate macro syntax\(rq with Li --alternate or Li .altmacro.
|
|
See Section.Dq Altmacro .
|
|
.El
|
|
.Pp
|
|
.Ss Li .altmacro
|
|
Enable alternate macro mode, enabling:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It LOCAL Va name [ , ... ]
|
|
One additional directive,
|
|
.Li LOCAL ,
|
|
is available. It is used to generate a string replacement for each of the
|
|
.Va name
|
|
arguments, and replace any instances of
|
|
.Va name
|
|
in each macro expansion. The replacement string is unique in the assembly,
|
|
and different for each separate macro expansion.
|
|
.Li LOCAL
|
|
allows you to write macros that define symbols, without fear of conflict between
|
|
separate macro expansions.
|
|
.Pp
|
|
.It String delimiters
|
|
You can write strings delimited in these other ways besides
|
|
.Li " Va string" :
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It ' Va string'
|
|
You can delimit strings with single-quote characters.
|
|
.Pp
|
|
.It < Va string>
|
|
You can delimit strings with matching angle brackets.
|
|
.El
|
|
.Pp
|
|
.It single-character string escape
|
|
To include any single character literally in a string (even if the character
|
|
would otherwise have some special meaning), you can prefix the character with
|
|
.Li !
|
|
(an exclamation mark). For example, you can write
|
|
.Li <4.3 !> 5.4!!>
|
|
to get the literal text
|
|
.Li 4.3 > 5.4! .
|
|
.Pp
|
|
.It Expression results as strings
|
|
You can write
|
|
.Li % Va expr
|
|
to evaluate the expression
|
|
.Va expr
|
|
and use the result as a string.
|
|
.El
|
|
.Pp
|
|
.Ss Li .noaltmacro
|
|
Disable alternate macro mode.See Section
|
|
.Dq Altmacro .
|
|
.Pp
|
|
.Ss Li .nolist
|
|
Control (in conjunction with the
|
|
.Li .list
|
|
directive) whether or not assembly listings are generated. These two directives
|
|
maintain an internal counter (which is zero initially).
|
|
.Li .list
|
|
increments the counter, and
|
|
.Li .nolist
|
|
decrements it. Assembly listings are generated whenever the counter is greater
|
|
than zero.
|
|
.Pp
|
|
.Ss Li .octa Va biGNUms
|
|
This directive expects zero or more biGNUms, separated by commas. For each
|
|
biGNUm, it emits a 16-byte integer.
|
|
.Pp
|
|
The term \(lqocta\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence
|
|
.Em octa
|
|
-word for 16 bytes.
|
|
.Pp
|
|
.Ss Li .org Va new-lc , Va fill
|
|
Advance the location counter of the current section to
|
|
.Va new-lc .
|
|
.Va new-lc
|
|
is either an absolute expression or an expression with the same section as
|
|
the current subsection. That is, you can't use
|
|
.Li .org
|
|
to cross sections: if
|
|
.Va new-lc
|
|
has the wrong section, the
|
|
.Li .org
|
|
directive is ignored. To be compatible with former assemblers, if the section
|
|
of
|
|
.Va new-lc
|
|
is absolute,
|
|
.Xr as
|
|
issues a warning, then pretends the section of
|
|
.Va new-lc
|
|
is the same as the current subsection.
|
|
.Pp
|
|
.Li .org
|
|
may only increase the location counter, or leave it unchanged; you cannot
|
|
use
|
|
.Li .org
|
|
to move the location counter backwards.
|
|
.Pp
|
|
Because
|
|
.Xr as
|
|
tries to assemble programs in one pass,
|
|
.Va new-lc
|
|
may not be undefined. If you really detest this restriction we eagerly await
|
|
a chance to share your improved assembler.
|
|
.Pp
|
|
Beware that the origin is relative to the start of the section, not to the
|
|
start of the subsection. This is compatible with other people's assemblers.
|
|
.Pp
|
|
When the location counter (of the current subsection) is advanced, the intervening
|
|
bytes are filled with
|
|
.Va fill
|
|
which should be an absolute expression. If the comma and
|
|
.Va fill
|
|
are omitted,
|
|
.Va fill
|
|
defaults to zero.
|
|
.Pp
|
|
.Ss Li .p2align[wl] Va abs-expr, Va abs-expr, Va abs-expr
|
|
Pad the location counter (in the current subsection) to a particular storage
|
|
boundary. The first expression (which must be absolute) is the number of low-order
|
|
zero bits the location counter must have after advancement. For example
|
|
.Li .p2align 3
|
|
advances the location counter until it a multiple of 8. If the location counter
|
|
is already a multiple of 8, no change is needed.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The
|
|
.Li .p2alignw
|
|
and
|
|
.Li .p2alignl
|
|
directives are variants of the
|
|
.Li .p2align
|
|
directive. The
|
|
.Li .p2alignw
|
|
directive treats the fill pattern as a two byte word value. The
|
|
.Li .p2alignl
|
|
directives treats the fill pattern as a four byte longword value. For example,
|
|
.Li .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.
|
|
.Pp
|
|
.Ss Li .previous
|
|
This is one of the ELF section stack manipulation directives. The others are
|
|
.Li .section
|
|
(see Section
|
|
.Dq Section ) ,
|
|
.Li .subsection
|
|
(see Section
|
|
.Dq SubSection ) ,
|
|
.Li .pushsection
|
|
(see Section
|
|
.Dq PushSection ) ,
|
|
and
|
|
.Li .popsection
|
|
(see Section
|
|
.Dq PopSection ) .
|
|
.Pp
|
|
This directive swaps the current section (and subsection) with most recently
|
|
referenced section (and subsection) prior to this one. Multiple
|
|
.Li .previous
|
|
directives in a row will flip between two sections (and their subsections).
|
|
.Pp
|
|
In terms of the section stack, this directive swaps the current section with
|
|
the top section on the section stack.
|
|
.Pp
|
|
.Ss Li .popsection
|
|
This is one of the ELF section stack manipulation directives. The others are
|
|
.Li .section
|
|
(see Section
|
|
.Dq Section ) ,
|
|
.Li .subsection
|
|
(see Section
|
|
.Dq SubSection ) ,
|
|
.Li .pushsection
|
|
(see Section
|
|
.Dq PushSection ) ,
|
|
and
|
|
.Li .previous
|
|
(see Section
|
|
.Dq Previous ) .
|
|
.Pp
|
|
This directive replaces the current section (and subsection) with the top
|
|
section (and subsection) on the section stack. This section is popped off
|
|
the stack.
|
|
.Pp
|
|
.Ss Li .print Va string
|
|
.Xr as
|
|
will print
|
|
.Va string
|
|
on the standard output during assembly. You must put
|
|
.Va string
|
|
in double quotes.
|
|
.Pp
|
|
.Ss Li .protected Va names
|
|
This is one of the ELF visibility directives. The other two are
|
|
.Li .hidden
|
|
(see Section
|
|
.Dq Hidden )
|
|
and
|
|
.Li .internal
|
|
(see Section
|
|
.Dq Internal ) .
|
|
.Pp
|
|
This directive overrides the named symbols default visibility (which is set
|
|
by their binding: local, global or weak). The directive sets the visibility
|
|
to
|
|
.Li protected
|
|
which means that any references to the symbols from within the components
|
|
that defines them must be resolved to the definition in that component, even
|
|
if a definition in another component would normally preempt this.
|
|
.Pp
|
|
.Ss Li .psize Va lines , Va columns
|
|
Use this directive to declare the number of lines---and, optionally, the number
|
|
of columns---to use for each page, when generating listings.
|
|
.Pp
|
|
If you do not use
|
|
.Li .psize ,
|
|
listings use a default line-count of 60. You may omit the comma and
|
|
.Va columns
|
|
specification; the default width is 200 columns.
|
|
.Pp
|
|
.Xr as
|
|
generates formfeeds whenever the specified number of lines is exceeded (or
|
|
whenever you explicitly request one, using
|
|
.Li .eject ) .
|
|
.Pp
|
|
If you specify
|
|
.Va lines
|
|
as
|
|
.Li 0 ,
|
|
no formfeeds are generated save those explicitly specified with
|
|
.Li .eject .
|
|
.Pp
|
|
.Ss Li .purgem Va name
|
|
Undefine the macro
|
|
.Va name ,
|
|
so that later uses of the string will not be expanded.See Section
|
|
.Dq Macro .
|
|
.Pp
|
|
.Ss Li .pushsection Va name , Va subsection
|
|
This is one of the ELF section stack manipulation directives. The others are
|
|
.Li .section
|
|
(see Section
|
|
.Dq Section ) ,
|
|
.Li .subsection
|
|
(see Section
|
|
.Dq SubSection ) ,
|
|
.Li .popsection
|
|
(see Section
|
|
.Dq PopSection ) ,
|
|
and
|
|
.Li .previous
|
|
(see Section
|
|
.Dq Previous ) .
|
|
.Pp
|
|
This directive pushes the current section (and subsection) onto the top of
|
|
the section stack, and then replaces the current section and subsection with
|
|
.Li name
|
|
and
|
|
.Li subsection .
|
|
.Pp
|
|
.Ss Li .quad Va biGNUms
|
|
.Li .quad
|
|
expects zero or more biGNUms, separated by commas. For each bignum, it emits
|
|
an 8-byte integer. If the biGNUm won't fit in 8 bytes, it prints a warning
|
|
message; and just takes the lowest order 8 bytes of the biGNUm.
|
|
.Pp
|
|
The term \(lqquad\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence
|
|
.Em quad
|
|
-word for 8 bytes.
|
|
.Pp
|
|
.Ss Li .reloc Va offset, Va reloc_name[, Va expression]
|
|
Generate a relocation at
|
|
.Va offset
|
|
of type
|
|
.Va reloc_name
|
|
with value
|
|
.Va expression .
|
|
If
|
|
.Va offset
|
|
is a number, the relocation is generated in the current section. If
|
|
.Va offset
|
|
is an expression that resolves to a symbol plus offset, the relocation is
|
|
generated in the given symbol's section.
|
|
.Va expression ,
|
|
if present, must resolve to a symbol plus addend or to an absolute value,
|
|
but note that not all targets support an addend. e.g. ELF REL targets such
|
|
as i386 store an addend in the section contents rather than in the relocation.
|
|
This low level interface does not support addends stored in the section.
|
|
.Pp
|
|
.Ss Li .rept Va count
|
|
Repeat the sequence of lines between the
|
|
.Li .rept
|
|
directive and the next
|
|
.Li .endr
|
|
directive
|
|
.Va count
|
|
times.
|
|
.Pp
|
|
For example, assembling
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.rept 3
|
|
.long 0
|
|
.endr
|
|
.Ed
|
|
.Pp
|
|
is equivalent to assembling
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.long 0
|
|
.long 0
|
|
.long 0
|
|
.Ed
|
|
.Pp
|
|
.Ss Li .sbttl " Va subheading"
|
|
Use
|
|
.Va subheading
|
|
as the title (third line, immediately after the title line) when generating
|
|
assembly listings.
|
|
.Pp
|
|
This directive affects subsequent pages, as well as the current page if it
|
|
appears within ten lines of the top of a page.
|
|
.Pp
|
|
.Ss Li .section Va name
|
|
Use the
|
|
.Li .section
|
|
directive to assemble the following code into a section named
|
|
.Va name .
|
|
.Pp
|
|
This directive is only supported for targets that actually support arbitrarily
|
|
named sections; on
|
|
.Li a.out
|
|
targets, for example, it is not accepted, even with a standard
|
|
.Li a.out
|
|
section name.
|
|
.Pp
|
|
This is one of the ELF section stack manipulation directives. The others are
|
|
.Li .subsection
|
|
(see Section
|
|
.Dq SubSection ) ,
|
|
.Li .pushsection
|
|
(see Section
|
|
.Dq PushSection ) ,
|
|
.Li .popsection
|
|
(see Section
|
|
.Dq PopSection ) ,
|
|
and
|
|
.Li .previous
|
|
(see Section
|
|
.Dq Previous ) .
|
|
.Pp
|
|
For ELF targets, the
|
|
.Li .section
|
|
directive is used like this:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
\&.section name [, "flags"[, @type[,flag_specific_arguments]]]
|
|
.Ed
|
|
.Pp
|
|
The optional
|
|
.Va flags
|
|
argument is a quoted string which may contain any combination of the following
|
|
characters:
|
|
.Bl -tag -width Ds
|
|
.It a
|
|
section is allocatable
|
|
.It w
|
|
section is writable
|
|
.It x
|
|
section is executable
|
|
.It M
|
|
section is mergeable
|
|
.It S
|
|
section contains zero terminated strings
|
|
.It G
|
|
section is a member of a section group
|
|
.It T
|
|
section is used for thread-local-storage
|
|
.El
|
|
.Pp
|
|
The optional
|
|
.Va type
|
|
argument may contain one of the following constants:
|
|
.Bl -tag -width Ds
|
|
.It @progbits
|
|
section contains data
|
|
.It @nobits
|
|
section does not contain data (i.e., section only occupies space)
|
|
.It @note
|
|
section contains data which is used by things other than the program
|
|
.It @init_array
|
|
section contains an array of pointers to init functions
|
|
.It @fini_array
|
|
section contains an array of pointers to finish functions
|
|
.It @preinit_array
|
|
section contains an array of pointers to pre-init functions
|
|
.El
|
|
.Pp
|
|
Many targets only support the first three section types.
|
|
.Pp
|
|
Note on targets where the
|
|
.Li @
|
|
character is the start of a comment (eg ARM) then another character is used
|
|
instead. For example the ARM port uses the
|
|
.Li %
|
|
character.
|
|
.Pp
|
|
If
|
|
.Va flags
|
|
contains the
|
|
.Li M
|
|
symbol then the
|
|
.Va type
|
|
argument must be specified as well as an extra argument---
|
|
.Va entsize
|
|
---like this:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
\&.section name , "flags"M, @type, entsize
|
|
.Ed
|
|
.Pp
|
|
Sections with the
|
|
.Li M
|
|
flag but not
|
|
.Li S
|
|
flag must contain fixed size constants, each
|
|
.Va entsize
|
|
octets long. Sections with both
|
|
.Li M
|
|
and
|
|
.Li S
|
|
must contain zero terminated strings where each character is
|
|
.Va entsize
|
|
bytes long. The linker may remove duplicates within sections with the same
|
|
name, same entity size and same flags.
|
|
.Va entsize
|
|
must be an absolute expression.
|
|
.Pp
|
|
If
|
|
.Va flags
|
|
contains the
|
|
.Li G
|
|
symbol then the
|
|
.Va type
|
|
argument must be present along with an additional field like this:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
\&.section name , "flags"G, @type, GroupName[, linkage]
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va GroupName
|
|
field specifies the name of the section group to which this particular section
|
|
belongs. The optional linkage field can contain:
|
|
.Bl -tag -width Ds
|
|
.It comdat
|
|
indicates that only one copy of this section should be retained
|
|
.It .GNU.linkonce
|
|
an alias for comdat
|
|
.El
|
|
.Pp
|
|
Note: if both the
|
|
.Va M
|
|
and
|
|
.Va G
|
|
flags are present then the fields for the Merge flag should come first, like
|
|
this:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
\&.section name , "flags"MG, @type, entsize, GroupName[, linkage]
|
|
.Ed
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
For ELF targets, the assembler supports another type of
|
|
.Li .section
|
|
directive for compatibility with the Solaris assembler:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
\&.section "name"[, flags...]
|
|
.Ed
|
|
.Pp
|
|
Note that the section name is quoted. There may be a sequence of comma separated
|
|
flags:
|
|
.Bl -tag -width Ds
|
|
.It #alloc
|
|
section is allocatable
|
|
.It #write
|
|
section is writable
|
|
.It #execinstr
|
|
section is executable
|
|
.It #tls
|
|
section is used for thread local storage
|
|
.El
|
|
.Pp
|
|
This directive replaces the current section and subsection. See the contents
|
|
of the gas testsuite directory
|
|
.Li gas/testsuite/gas/elf
|
|
for some examples of how this directive and the other section stack directives
|
|
work.
|
|
.Pp
|
|
.Ss Li .set Va symbol, Va expression
|
|
Set the value of
|
|
.Va symbol
|
|
to
|
|
.Va expression .
|
|
This changes
|
|
.Va symbol
|
|
\&'s value and type to conform to
|
|
.Va expression .
|
|
If
|
|
.Va symbol
|
|
was flagged as external, it remains flagged (see Section
|
|
.Dq Symbol Attributes ) .
|
|
.Pp
|
|
You may
|
|
.Li .set
|
|
a symbol many times in the same assembly.
|
|
.Pp
|
|
If you
|
|
.Li .set
|
|
a global symbol, the value stored in the object file is the last value stored
|
|
into it.
|
|
.Pp
|
|
.Ss Li .short Va expressions
|
|
This expects zero or more
|
|
.Va expressions ,
|
|
and emits a 16 bit number for each.
|
|
.Pp
|
|
.Ss Li .single Va flonums
|
|
This directive assembles zero or more flonums, separated by commas. It has
|
|
the same effect as
|
|
.Li .float .
|
|
.Pp
|
|
.Ss Li .size
|
|
This directive is used to set the size associated with a symbol.
|
|
.Pp
|
|
For ELF targets, the
|
|
.Li .size
|
|
directive is used like this:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
\&.size name , expression
|
|
.Ed
|
|
.Pp
|
|
This directive sets the size associated with a symbol
|
|
.Va name .
|
|
The size in bytes is computed from
|
|
.Va expression
|
|
which can make use of label arithmetic. This directive is typically used to
|
|
set the size of function symbols.
|
|
.Pp
|
|
.Ss Li .sleb128 Va expressions
|
|
.Va sleb128
|
|
stands for \(lqsigned little endian base 128.\(rq This is a compact, variable length
|
|
representation of numbers used by the DWARF symbolic debugging format.See Section
|
|
.Dq Uleb128 .
|
|
.Pp
|
|
.Ss Li .skip Va size , Va fill
|
|
This directive emits
|
|
.Va size
|
|
bytes, each of value
|
|
.Va fill .
|
|
Both
|
|
.Va size
|
|
and
|
|
.Va fill
|
|
are absolute expressions. If the comma and
|
|
.Va fill
|
|
are omitted,
|
|
.Va fill
|
|
is assumed to be zero. This is the same as
|
|
.Li .space .
|
|
.Pp
|
|
.Ss Li .space Va size , Va fill
|
|
This directive emits
|
|
.Va size
|
|
bytes, each of value
|
|
.Va fill .
|
|
Both
|
|
.Va size
|
|
and
|
|
.Va fill
|
|
are absolute expressions. If the comma and
|
|
.Va fill
|
|
are omitted,
|
|
.Va fill
|
|
is assumed to be zero. This is the same as
|
|
.Li .skip .
|
|
.Pp
|
|
.Ss Li .stabd, .stabn, .stabs
|
|
There are three directives that begin
|
|
.Li .stab .
|
|
All emit symbols (see Section
|
|
.Dq Symbols ) ,
|
|
for use by symbolic debuggers. The symbols are not entered in the
|
|
.Xr as
|
|
hash table: they cannot be referenced elsewhere in the source file. Up to
|
|
five fields are required:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It string
|
|
This is the symbol's name. It may contain any character except
|
|
.Li \e000 ,
|
|
so is more general than ordinary symbol names. Some debuggers used to code
|
|
arbitrarily complex structures into symbol names using this field.
|
|
.Pp
|
|
.It type
|
|
An absolute expression. The symbol's type is set to the low 8 bits of this
|
|
expression. Any bit pattern is permitted, but
|
|
.Li ld
|
|
and debuggers choke on silly bit patterns.
|
|
.Pp
|
|
.It other
|
|
An absolute expression. The symbol's \(lqother\(rq attribute is set to the low 8 bits
|
|
of this expression.
|
|
.Pp
|
|
.It desc
|
|
An absolute expression. The symbol's descriptor is set to the low 16 bits
|
|
of this expression.
|
|
.Pp
|
|
.It value
|
|
An absolute expression which becomes the symbol's value.
|
|
.El
|
|
.Pp
|
|
If a warning is detected while reading a
|
|
.Li .stabd ,
|
|
.Li .stabn ,
|
|
or
|
|
.Li .stabs
|
|
statement, the symbol has probably already been created; you get a half-formed
|
|
symbol in your object file. This is compatible with earlier assemblers!
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It .stabd Va type , Va other , Va desc
|
|
.Pp
|
|
The \(lqname\(rq of the symbol generated is not even an empty string. It is a null
|
|
pointer, for compatibility. Older assemblers used a null pointer so they didn't
|
|
waste space in object files with empty strings.
|
|
.Pp
|
|
The symbol's value is set to the location counter, relocatably. When your
|
|
program is linked, the value of this symbol is the address of the location
|
|
counter when the
|
|
.Li .stabd
|
|
was assembled.
|
|
.Pp
|
|
.It .stabn Va type , Va other , Va desc , Va value
|
|
The name of the symbol is set to the empty string
|
|
.Li "" .
|
|
.Pp
|
|
.It .stabs Va string , Va type , Va other , Va desc , Va value
|
|
All five fields are specified.
|
|
.El
|
|
.Pp
|
|
.Ss Li .string " Va str"
|
|
Copy the characters in
|
|
.Va str
|
|
to the object file. You may specify more than one string to copy, separated
|
|
by commas. Unless otherwise specified for a particular machine, the assembler
|
|
marks the end of each string with a 0 byte. You can use any of the escape
|
|
sequences described in Strings,,Strings.
|
|
.Pp
|
|
.Ss Li .struct Va expression
|
|
Switch to the absolute section, and set the section offset to
|
|
.Va expression ,
|
|
which must be an absolute expression. You might use this as follows:
|
|
.Bd -literal -offset indent
|
|
.struct 0
|
|
field1:
|
|
.struct field1 + 4
|
|
field2:
|
|
.struct field2 + 4
|
|
field3:
|
|
.Ed
|
|
This would define the symbol
|
|
.Li field1
|
|
to have the value 0, the symbol
|
|
.Li field2
|
|
to have the value 4, and the symbol
|
|
.Li field3
|
|
to have the value 8. Assembly would be left in the absolute section, and you
|
|
would need to use a
|
|
.Li .section
|
|
directive of some sort to change to some other section before further assembly.
|
|
.Pp
|
|
.Ss Li .subsection Va name
|
|
This is one of the ELF section stack manipulation directives. The others are
|
|
.Li .section
|
|
(see Section
|
|
.Dq Section ) ,
|
|
.Li .pushsection
|
|
(see Section
|
|
.Dq PushSection ) ,
|
|
.Li .popsection
|
|
(see Section
|
|
.Dq PopSection ) ,
|
|
and
|
|
.Li .previous
|
|
(see Section
|
|
.Dq Previous ) .
|
|
.Pp
|
|
This directive replaces the current subsection with
|
|
.Li name .
|
|
The current section is not changed. The replaced subsection is put onto the
|
|
section stack in place of the then current top of stack subsection.
|
|
.Pp
|
|
.Ss Li .symver
|
|
Use the
|
|
.Li .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.
|
|
.Pp
|
|
For ELF targets, the
|
|
.Li .symver
|
|
directive can be used like this:
|
|
.Bd -literal -offset indent
|
|
\&.symver name, name2@nodename
|
|
.Ed
|
|
If the symbol
|
|
.Va name
|
|
is defined within the file being assembled, the
|
|
.Li .symver
|
|
directive effectively creates a symbol alias with the name
|
|
.Va name2@nodename ,
|
|
and in fact the main reason that we just don't try and create a regular alias
|
|
is that the
|
|
.Va @
|
|
character isn't permitted in symbol names. The
|
|
.Va name2
|
|
part of the name is the actual name of the symbol by which it will be externally
|
|
referenced. The name
|
|
.Va 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
|
|
.Va 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
|
|
.Va nodename
|
|
should correspond to the nodename of the symbol you are trying to override.
|
|
.Pp
|
|
If the symbol
|
|
.Va name
|
|
is not defined within the file being assembled, all references to
|
|
.Va name
|
|
will be changed to
|
|
.Va name2@nodename .
|
|
If no reference to
|
|
.Va name
|
|
is made,
|
|
.Va name2@nodename
|
|
will be removed from the symbol table.
|
|
.Pp
|
|
Another usage of the
|
|
.Li .symver
|
|
directive is:
|
|
.Bd -literal -offset indent
|
|
\&.symver name, name2@@nodename
|
|
.Ed
|
|
In this case, the symbol
|
|
.Va name
|
|
must exist and be defined within the file being assembled. It is similar to
|
|
.Va name2@nodename .
|
|
The difference is
|
|
.Va name2@@nodename
|
|
will also be used to resolve references to
|
|
.Va name2
|
|
by the linker.
|
|
.Pp
|
|
The third usage of the
|
|
.Li .symver
|
|
directive is:
|
|
.Bd -literal -offset indent
|
|
\&.symver name, name2@@@nodename
|
|
.Ed
|
|
When
|
|
.Va name
|
|
is not defined within the file being assembled, it is treated as
|
|
.Va name2@nodename .
|
|
When
|
|
.Va name
|
|
is defined within the file being assembled, the symbol name,
|
|
.Va name ,
|
|
will be changed to
|
|
.Va name2@@nodename .
|
|
.Pp
|
|
.Ss Li .text Va subsection
|
|
Tells
|
|
.Xr as
|
|
to assemble the following statements onto the end of the text subsection numbered
|
|
.Va subsection ,
|
|
which is an absolute expression. If
|
|
.Va subsection
|
|
is omitted, subsection number zero is used.
|
|
.Pp
|
|
.Ss Li .title " Va heading"
|
|
Use
|
|
.Va heading
|
|
as the title (second line, immediately after the source file name and pagenumber)
|
|
when generating assembly listings.
|
|
.Pp
|
|
This directive affects subsequent pages, as well as the current page if it
|
|
appears within ten lines of the top of a page.
|
|
.Pp
|
|
.Ss Li .type
|
|
This directive is used to set the type of a symbol.
|
|
.Pp
|
|
For ELF targets, the
|
|
.Li .type
|
|
directive is used like this:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
\&.type name , type description
|
|
.Ed
|
|
.Pp
|
|
This sets the type of symbol
|
|
.Va name
|
|
to be either a function symbol or an object symbol. There are five different
|
|
syntaxes supported for the
|
|
.Va type description
|
|
field, in order to provide compatibility with various other assemblers.
|
|
.Pp
|
|
Because some of the characters used in these syntaxes (such as
|
|
.Li @
|
|
and
|
|
.Li # )
|
|
are comment characters for some architectures, some of the syntaxes below
|
|
do not work on all architectures. The first variant will be accepted by the
|
|
GNU assembler on all architectures so that variant should be used for maximum
|
|
portability, if you do not need to assemble your code with other assemblers.
|
|
.Pp
|
|
The syntaxes supported are:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.type <name> STT_FUNCTION
|
|
.type <name> STT_OBJECT
|
|
|
|
.type <name>,#function
|
|
.type <name>,#object
|
|
|
|
.type <name>,@function
|
|
.type <name>,@object
|
|
|
|
.type <name>,%function
|
|
.type <name>,%object
|
|
|
|
.type <name>,"function"
|
|
.type <name>,"object"
|
|
.Ed
|
|
.Pp
|
|
.Ss Li .uleb128 Va expressions
|
|
.Va uleb128
|
|
stands for \(lqunsigned little endian base 128.\(rq This is a compact, variable length
|
|
representation of numbers used by the DWARF symbolic debugging format.See Section
|
|
.Dq Sleb128 .
|
|
.Pp
|
|
.Ss Li .version " Va string"
|
|
This directive creates a
|
|
.Li .note
|
|
section and places into it an ELF formatted note of type NT_VERSION. The note's
|
|
name is set to
|
|
.Li string .
|
|
.Pp
|
|
.Ss Li .vtable_entry Va table, Va offset
|
|
This directive finds or creates a symbol
|
|
.Li table
|
|
and creates a
|
|
.Li VTABLE_ENTRY
|
|
relocation for it with an addend of
|
|
.Li offset .
|
|
.Pp
|
|
.Ss Li .vtable_inherit Va child, Va parent
|
|
This directive finds the symbol
|
|
.Li child
|
|
and finds or creates the symbol
|
|
.Li parent
|
|
and then creates a
|
|
.Li VTABLE_INHERIT
|
|
relocation for the parent whose addend is the value of the child symbol. As
|
|
a special case the parent name of
|
|
.Li 0
|
|
is treated as referring to the
|
|
.Li *ABS*
|
|
section.
|
|
.Pp
|
|
.Ss Li .warning " Va string"
|
|
Similar to the directive
|
|
.Li .error
|
|
(see Section
|
|
.Dq Error ) ,
|
|
but just emits a warning.
|
|
.Pp
|
|
.Ss Li .weak Va names
|
|
This directive sets the weak attribute on the comma separated list of symbol
|
|
.Li names .
|
|
If the symbols do not already exist, they will be created.
|
|
.Pp
|
|
On COFF targets other than PE, weak symbols are a GNU extension. This directive
|
|
sets the weak attribute on the comma separated list of symbol
|
|
.Li names .
|
|
If the symbols do not already exist, they will be created.
|
|
.Pp
|
|
On the PE target, weak symbols are supported natively as weak aliases. When
|
|
a weak symbol is created that is not an alias, GAS creates an alternate symbol
|
|
to hold the default value.
|
|
.Pp
|
|
.Ss Li .weakref Va alias, Va target
|
|
This directive creates an alias to the target symbol that enables the symbol
|
|
to be referenced with weak-symbol semantics, but without actually making it
|
|
weak. If direct references or definitions of the symbol are present, then
|
|
the symbol will not be weak, but if all references to it are through weak
|
|
references, the symbol will be marked as weak in the symbol table.
|
|
.Pp
|
|
The effect is equivalent to moving all references to the alias to a separate
|
|
assembly source file, renaming the alias to the symbol in it, declaring the
|
|
symbol as weak there, and running a reloadable link to merge the object files
|
|
resulting from the assembly of the new source file and the old source file
|
|
that had the references to the alias removed.
|
|
.Pp
|
|
The alias itself never makes to the symbol table, and is entirely handled
|
|
within the assembler.
|
|
.Pp
|
|
.Ss Li .word Va expressions
|
|
This directive expects zero or more
|
|
.Va expressions ,
|
|
of any section, separated by commas. For each expression,
|
|
.Xr as
|
|
emits a 32-bit number.
|
|
.Pp
|
|
.Ss Deprecated Directives
|
|
One day these directives won't work. They are included for compatibility with
|
|
older assemblers.
|
|
.Bl -tag -width Ds
|
|
.It .abort
|
|
.It .line
|
|
.El
|
|
.Pp
|
|
.Sh ARM Dependent Features
|
|
.Ss Options
|
|
.Bl -tag -width Ds
|
|
.It -mcpu= Va processor[+ Va extension...]
|
|
This option specifies the target processor. The assembler will issue an error
|
|
message if an attempt is made to assemble an instruction which will not execute
|
|
on the target processor. The following processor names are recognized:
|
|
.Li arm1 ,
|
|
.Li arm2 ,
|
|
.Li arm250 ,
|
|
.Li arm3 ,
|
|
.Li arm6 ,
|
|
.Li arm60 ,
|
|
.Li arm600 ,
|
|
.Li arm610 ,
|
|
.Li arm620 ,
|
|
.Li arm7 ,
|
|
.Li arm7m ,
|
|
.Li arm7d ,
|
|
.Li arm7dm ,
|
|
.Li arm7di ,
|
|
.Li arm7dmi ,
|
|
.Li arm70 ,
|
|
.Li arm700 ,
|
|
.Li arm700i ,
|
|
.Li arm710 ,
|
|
.Li arm710t ,
|
|
.Li arm720 ,
|
|
.Li arm720t ,
|
|
.Li arm740t ,
|
|
.Li arm710c ,
|
|
.Li arm7100 ,
|
|
.Li arm7500 ,
|
|
.Li arm7500fe ,
|
|
.Li arm7t ,
|
|
.Li arm7tdmi ,
|
|
.Li arm7tdmi-s ,
|
|
.Li arm8 ,
|
|
.Li arm810 ,
|
|
.Li strongarm ,
|
|
.Li strongarm1 ,
|
|
.Li strongarm110 ,
|
|
.Li strongarm1100 ,
|
|
.Li strongarm1110 ,
|
|
.Li arm9 ,
|
|
.Li arm920 ,
|
|
.Li arm920t ,
|
|
.Li arm922t ,
|
|
.Li arm940t ,
|
|
.Li arm9tdmi ,
|
|
.Li arm9e ,
|
|
.Li arm926e ,
|
|
.Li arm926ej-s ,
|
|
.Li arm946e-r0 ,
|
|
.Li arm946e ,
|
|
.Li arm946e-s ,
|
|
.Li arm966e-r0 ,
|
|
.Li arm966e ,
|
|
.Li arm966e-s ,
|
|
.Li arm968e-s ,
|
|
.Li arm10t ,
|
|
.Li arm10tdmi ,
|
|
.Li arm10e ,
|
|
.Li arm1020 ,
|
|
.Li arm1020t ,
|
|
.Li arm1020e ,
|
|
.Li arm1022e ,
|
|
.Li arm1026ej-s ,
|
|
.Li arm1136j-s ,
|
|
.Li arm1136jf-s ,
|
|
.Li arm1156t2-s ,
|
|
.Li arm1156t2f-s ,
|
|
.Li arm1176jz-s ,
|
|
.Li arm1176jzf-s ,
|
|
.Li mpcore ,
|
|
.Li mpcorenovfp ,
|
|
.Li cortex-a8 ,
|
|
.Li cortex-r4 ,
|
|
.Li cortex-m3 ,
|
|
.Li ep9312
|
|
(ARM920 with Cirrus Maverick coprocessor),
|
|
.Li i80200
|
|
(Intel XScale processor)
|
|
.Li iwmmxt
|
|
(Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) and
|
|
.Li xscale .
|
|
The special name
|
|
.Li all
|
|
may be used to allow the assembler to accept instructions valid for any ARM
|
|
processor.
|
|
.Pp
|
|
In addition to the basic instruction set, the assembler can be told to accept
|
|
various extension mnemonics that extend the processor using the co-processor
|
|
instruction space. For example,
|
|
.Li -mcpu=arm920+maverick
|
|
is equivalent to specifying
|
|
.Li -mcpu=ep9312 .
|
|
The following extensions are currently supported:
|
|
.Li +maverick
|
|
.Li +iwmmxt
|
|
and
|
|
.Li +xscale .
|
|
.Pp
|
|
.It -march= Va architecture[+ Va extension...]
|
|
This option specifies the target architecture. The assembler will issue an
|
|
error message if an attempt is made to assemble an instruction which will
|
|
not execute on the target architecture. The following architecture names are
|
|
recognized:
|
|
.Li armv1 ,
|
|
.Li armv2 ,
|
|
.Li armv2a ,
|
|
.Li armv2s ,
|
|
.Li armv3 ,
|
|
.Li armv3m ,
|
|
.Li armv4 ,
|
|
.Li armv4xm ,
|
|
.Li armv4t ,
|
|
.Li armv4txm ,
|
|
.Li armv5 ,
|
|
.Li armv5t ,
|
|
.Li armv5txm ,
|
|
.Li armv5te ,
|
|
.Li armv5texp ,
|
|
.Li armv6 ,
|
|
.Li armv6j ,
|
|
.Li armv6k ,
|
|
.Li armv6z ,
|
|
.Li armv6zk ,
|
|
.Li armv7 ,
|
|
.Li armv7-a ,
|
|
.Li armv7-r ,
|
|
.Li armv7-m ,
|
|
.Li iwmmxt
|
|
and
|
|
.Li xscale .
|
|
If both
|
|
.Li -mcpu
|
|
and
|
|
.Li -march
|
|
are specified, the assembler will use the setting for
|
|
.Li -mcpu .
|
|
.Pp
|
|
The architecture option can be extended with the same instruction set extension
|
|
options as the
|
|
.Li -mcpu
|
|
option.
|
|
.Pp
|
|
.It -mfpu= Va floating-point-format
|
|
.Pp
|
|
This option specifies the floating point format to assemble for. The assembler
|
|
will issue an error message if an attempt is made to assemble an instruction
|
|
which will not execute on the target floating point unit. The following format
|
|
options are recognized:
|
|
.Li softfpa ,
|
|
.Li fpe ,
|
|
.Li fpe2 ,
|
|
.Li fpe3 ,
|
|
.Li fpa ,
|
|
.Li fpa10 ,
|
|
.Li fpa11 ,
|
|
.Li arm7500fe ,
|
|
.Li softvfp ,
|
|
.Li softvfp+vfp ,
|
|
.Li vfp ,
|
|
.Li vfp10 ,
|
|
.Li vfp10-r0 ,
|
|
.Li vfp9 ,
|
|
.Li vfpxd ,
|
|
.Li arm1020t ,
|
|
.Li arm1020e ,
|
|
.Li arm1136jf-s
|
|
and
|
|
.Li maverick .
|
|
.Pp
|
|
In addition to determining which instructions are assembled, this option also
|
|
affects the way in which the
|
|
.Li .double
|
|
assembler directive behaves when assembling little-endian code.
|
|
.Pp
|
|
The default is dependent on the processor selected. For Architecture 5 or
|
|
later, the default is to assembler for VFP instructions; for earlier architectures
|
|
the default is to assemble for FPA instructions.
|
|
.Pp
|
|
.It -mthumb
|
|
This option specifies that the assembler should start assembling Thumb instructions;
|
|
that is, it should behave as though the file starts with a
|
|
.Li .code 16
|
|
directive.
|
|
.Pp
|
|
.It -mthumb-interwork
|
|
This option specifies that the output generated by the assembler should be
|
|
marked as supporting interworking.
|
|
.Pp
|
|
.It -mapcs Li [26|32]
|
|
This option specifies that the output generated by the assembler should be
|
|
marked as supporting the indicated version of the Arm Procedure. Calling Standard.
|
|
.Pp
|
|
.It -matpcs
|
|
This option specifies that the output generated by the assembler should be
|
|
marked as supporting the Arm/Thumb Procedure Calling Standard. If enabled
|
|
this option will cause the assembler to create an empty debugging section
|
|
in the object file called .arm.atpcs. Debuggers can use this to determine
|
|
the ABI being used by.
|
|
.Pp
|
|
.It -mapcs-float
|
|
This indicates the floating point variant of the APCS should be used. In this
|
|
variant floating point arguments are passed in FP registers rather than integer
|
|
registers.
|
|
.Pp
|
|
.It -mapcs-reentrant
|
|
This indicates that the reentrant variant of the APCS should be used. This
|
|
variant supports position independent code.
|
|
.Pp
|
|
.It -mfloat-abi= Va abi
|
|
This option specifies that the output generated by the assembler should be
|
|
marked as using specified floating point ABI. The following values are recognized:
|
|
.Li soft ,
|
|
.Li softfp
|
|
and
|
|
.Li hard .
|
|
.Pp
|
|
.It -meabi= Va ver
|
|
This option specifies which EABI version the produced object files should
|
|
conform to. The following values are recognized:
|
|
.Li GNU ,
|
|
.Li 4
|
|
and
|
|
.Li 5 .
|
|
.Pp
|
|
.It -EB
|
|
This option specifies that the output generated by the assembler should be
|
|
marked as being encoded for a big-endian processor.
|
|
.Pp
|
|
.It -EL
|
|
This option specifies that the output generated by the assembler should be
|
|
marked as being encoded for a little-endian processor.
|
|
.Pp
|
|
.It -k
|
|
This option specifies that the output of the assembler should be marked as
|
|
position-independent code (PIC).
|
|
.Pp
|
|
.El
|
|
.Ss Syntax
|
|
.Em Special Characters
|
|
.Pp
|
|
The presence of a
|
|
.Li @
|
|
on a line indicates the start of a comment that extends to the end of the
|
|
current line. If a
|
|
.Li #
|
|
appears as the first character of a line, the whole line is treated as a comment.
|
|
.Pp
|
|
The
|
|
.Li ;
|
|
character can be used instead of a newline to separate statements.
|
|
.Pp
|
|
Either
|
|
.Li #
|
|
or
|
|
.Li $
|
|
can be used to indicate immediate operands.
|
|
.Pp
|
|
*TODO* Explain about /data modifier on symbols.
|
|
.Pp
|
|
.Em Register Names
|
|
.Pp
|
|
*TODO* Explain about ARM register naming, and the predefined names.
|
|
.Pp
|
|
.Em ARM relocation generation
|
|
.Pp
|
|
Specific data relocations can be generated by putting the relocation name
|
|
in parentheses after the symbol name. For example:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.word foo(TARGET1)
|
|
.Ed
|
|
.Pp
|
|
This will generate an
|
|
.Li R_ARM_TARGET1
|
|
relocation against the symbol
|
|
.Va foo .
|
|
The following relocations are supported:
|
|
.Li GOT ,
|
|
.Li GOTOFF ,
|
|
.Li TARGET1 ,
|
|
.Li TARGET2 ,
|
|
.Li SBREL ,
|
|
.Li TLSGD ,
|
|
.Li TLSLDM ,
|
|
.Li TLSLDO ,
|
|
.Li GOTTPOFF
|
|
and
|
|
.Li TPOFF .
|
|
.Pp
|
|
For compatibility with older toolchains the assembler also accepts
|
|
.Li (PLT)
|
|
after branch targets. This will generate the deprecated
|
|
.Li R_ARM_PLT32
|
|
relocation.
|
|
.Pp
|
|
Relocations for
|
|
.Li MOVW
|
|
and
|
|
.Li MOVT
|
|
instructions can be generated by prefixing the value with
|
|
.Li #:lower16:
|
|
and
|
|
.Li #:upper16
|
|
respectively. For example to load the 32-bit address of foo into r0:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
MOVW r0, #:lower16:foo
|
|
MOVT r0, #:upper16:foo
|
|
.Ed
|
|
.Pp
|
|
.Ss Floating Point
|
|
The ARM family uses ieee floating-point numbers.
|
|
.Pp
|
|
.Ss ARM Machine Directives
|
|
.Bl -tag -width Ds
|
|
.It .align Va expression [, Va expression]
|
|
This is the generic
|
|
.Va .align
|
|
directive. For the ARM however if the first argument is zero (ie no alignment
|
|
is needed) the assembler will behave as if the argument had been 2 (ie pad
|
|
to the next four byte boundary). This is for compatibility with ARM's own
|
|
assembler.
|
|
.Pp
|
|
.It Va name .req Va register name
|
|
This creates an alias for
|
|
.Va register name
|
|
called
|
|
.Va name .
|
|
For example:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
foo .req r0
|
|
.Ed
|
|
.Pp
|
|
.It .unreq Va alias-name
|
|
This undefines a register alias which was previously defined using the
|
|
.Li req ,
|
|
.Li dn
|
|
or
|
|
.Li qn
|
|
directives. For example:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
foo .req r0
|
|
.unreq foo
|
|
.Ed
|
|
.Pp
|
|
An error occurs if the name is undefined. Note - this pseudo op can be used
|
|
to delete builtin in register name aliases (eg 'r0'). This should only be
|
|
done if it is really necessary.
|
|
.Pp
|
|
.It Va name .dn Va register name [ Va .type] [ Va [index]]
|
|
.It Va name .qn Va register name [ Va .type] [ Va [index]]
|
|
.Pp
|
|
The
|
|
.Li dn
|
|
and
|
|
.Li qn
|
|
directives are used to create typed and/or indexed register aliases for use
|
|
in Advanced SIMD Extension (Neon) instructions. The former should be used
|
|
to create aliases of double-precision registers, and the latter to create
|
|
aliases of quad-precision registers.
|
|
.Pp
|
|
If these directives are used to create typed aliases, those aliases can be
|
|
used in Neon instructions instead of writing types after the mnemonic or after
|
|
each operand. For example:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
x .dn d2.f32
|
|
y .dn d3.f32
|
|
z .dn d4.f32[1]
|
|
vmul x,y,z
|
|
.Ed
|
|
.Pp
|
|
This is equivalent to writing the following:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
vmul.f32 d2,d3,d4[1]
|
|
.Ed
|
|
.Pp
|
|
Aliases created using
|
|
.Li dn
|
|
or
|
|
.Li qn
|
|
can be destroyed using
|
|
.Li unreq .
|
|
.Pp
|
|
.It .code Li [16|32]
|
|
This directive selects the instruction set being generated. The value 16 selects
|
|
Thumb, with the value 32 selecting ARM.
|
|
.Pp
|
|
.It .thumb
|
|
This performs the same action as
|
|
.Va .code 16 .
|
|
.Pp
|
|
.It .arm
|
|
This performs the same action as
|
|
.Va .code 32 .
|
|
.Pp
|
|
.It .force_thumb
|
|
This directive forces the selection of Thumb instructions, even if the target
|
|
processor does not support those instructions
|
|
.Pp
|
|
.It .thumb_func
|
|
This directive specifies that the following symbol is the name of a Thumb
|
|
encoded function. This information is necessary in order to allow the assembler
|
|
and linker to generate correct code for interworking between Arm and Thumb
|
|
instructions and should be used even if interworking is not going to be performed.
|
|
The presence of this directive also implies
|
|
.Li .thumb
|
|
.Pp
|
|
This directive is not neccessary when generating EABI objects. On these targets
|
|
the encoding is implicit when generating Thumb code.
|
|
.Pp
|
|
.It .thumb_set
|
|
This performs the equivalent of a
|
|
.Li .set
|
|
directive in that it creates a symbol which is an alias for another symbol
|
|
(possibly not yet defined). This directive also has the added property in
|
|
that it marks the aliased symbol as being a thumb function entry point, in
|
|
the same way that the
|
|
.Li .thumb_func
|
|
directive does.
|
|
.Pp
|
|
.It .ltorg
|
|
This directive causes the current contents of the literal pool to be dumped
|
|
into the current section (which is assumed to be the .text section) at the
|
|
current location (aligned to a word boundary).
|
|
.Li GAS
|
|
maintains a separate literal pool for each section and each sub-section. The
|
|
.Li .ltorg
|
|
directive will only affect the literal pool of the current section and sub-section.
|
|
At the end of assembly all remaining, un-empty literal pools will automatically
|
|
be dumped.
|
|
.Pp
|
|
Note - older versions of
|
|
.Li GAS
|
|
would dump the current literal pool any time a section change occurred. This
|
|
is no longer done, since it prevents accurate control of the placement of
|
|
literal pools.
|
|
.Pp
|
|
.It .pool
|
|
This is a synonym for .ltorg.
|
|
.Pp
|
|
.It .unwind_fnstart
|
|
Marks the start of a function with an unwind table entry.
|
|
.Pp
|
|
.It .unwind_fnend
|
|
Marks the end of a function with an unwind table entry. The unwind index table
|
|
entry is created when this directive is processed.
|
|
.Pp
|
|
If no personality routine has been specified then standard personality routine
|
|
0 or 1 will be used, depending on the number of unwind opcodes required.
|
|
.Pp
|
|
.It .cantunwind
|
|
Prevents unwinding through the current function. No personality routine or
|
|
exception table data is required or permitted.
|
|
.Pp
|
|
.It .personality Va name
|
|
Sets the personality routine for the current function to
|
|
.Va name .
|
|
.Pp
|
|
.It .personalityindex Va index
|
|
Sets the personality routine for the current function to the EABI standard
|
|
routine number
|
|
.Va index
|
|
.Pp
|
|
.It .handlerdata
|
|
Marks the end of the current function, and the start of the exception table
|
|
entry for that function. Anything between this directive and the
|
|
.Li .fnend
|
|
directive will be added to the exception table entry.
|
|
.Pp
|
|
Must be preceded by a
|
|
.Li .personality
|
|
or
|
|
.Li .personalityindex
|
|
directive.
|
|
.Pp
|
|
.It .save Va reglist
|
|
Generate unwinder annotations to restore the registers in
|
|
.Va reglist .
|
|
The format of
|
|
.Va reglist
|
|
is the same as the corresponding store-multiple instruction.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.save {r4, r5, r6, lr}
|
|
stmfd sp!, {r4, r5, r6, lr}
|
|
.save f4, 2
|
|
sfmfd f4, 2, [sp]!
|
|
.save {d8, d9, d10}
|
|
fstmdx sp!, {d8, d9, d10}
|
|
.save {wr10, wr11}
|
|
wstrd wr11, [sp, #-8]!
|
|
wstrd wr10, [sp, #-8]!
|
|
or
|
|
.save wr11
|
|
wstrd wr11, [sp, #-8]!
|
|
.save wr10
|
|
wstrd wr10, [sp, #-8]!
|
|
.Ed
|
|
.Pp
|
|
.It .vsave Va vfp-reglist
|
|
Generate unwinder annotations to restore the VFP registers in
|
|
.Va vfp-reglist
|
|
using FLDMD. Also works for VFPv3 registers that are to be restored using
|
|
VLDM. The format of
|
|
.Va vfp-reglist
|
|
is the same as the corresponding store-multiple instruction.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.vsave {d8, d9, d10}
|
|
fstmdd sp!, {d8, d9, d10}
|
|
.vsave {d15, d16, d17}
|
|
vstm sp!, {d15, d16, d17}
|
|
.Ed
|
|
.Pp
|
|
Since FLDMX and FSTMX are now deprecated, this directive should be used in
|
|
favour of
|
|
.Li .save
|
|
for saving VFP registers for ARMv6 and above.
|
|
.Pp
|
|
.It .pad # Va count
|
|
Generate unwinder annotations for a stack adjustment of
|
|
.Va count
|
|
bytes. A positive value indicates the function prologue allocated stack space
|
|
by decrementing the stack pointer.
|
|
.Pp
|
|
.It .movsp Va reg [, # Va offset]
|
|
Tell the unwinder that
|
|
.Va reg
|
|
contains an offset from the current stack pointer. If
|
|
.Va offset
|
|
is not specified then it is assumed to be zero.
|
|
.Pp
|
|
.It .setfp Va fpreg, Va spreg [, # Va offset]
|
|
Make all unwinder annotations relaive to a frame pointer. Without this the
|
|
unwinder will use offsets from the stack pointer.
|
|
.Pp
|
|
The syntax of this directive is the same as the
|
|
.Li sub
|
|
or
|
|
.Li mov
|
|
instruction used to set the frame pointer.
|
|
.Va spreg
|
|
must be either
|
|
.Li sp
|
|
or mentioned in a previous
|
|
.Li .movsp
|
|
directive.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
\&.movsp ip
|
|
mov ip, sp
|
|
\&...
|
|
\&.setfp fp, ip, #4
|
|
sub fp, ip, #4
|
|
.Ed
|
|
.Pp
|
|
.It .raw Va offset, Va byte1, ...
|
|
Insert one of more arbitary unwind opcode bytes, which are known to adjust
|
|
the stack pointer by
|
|
.Va offset
|
|
bytes.
|
|
.Pp
|
|
For example
|
|
.Li .unwind_raw 4, 0xb1, 0x01
|
|
is equivalent to
|
|
.Li .save {r0}
|
|
.Pp
|
|
.It .cpu Va name
|
|
Select the target processor. Valid values for
|
|
.Va name
|
|
are the same as for the
|
|
.Op -mcpu
|
|
commandline option.
|
|
.Pp
|
|
.It .arch Va name
|
|
Select the target architecture. Valid values for
|
|
.Va name
|
|
are the same as for the
|
|
.Op -march
|
|
commandline option.
|
|
.Pp
|
|
.It .object_arch Va name
|
|
Override the architecture recorded in the EABI object attribute section. Valid
|
|
values for
|
|
.Va name
|
|
are the same as for the
|
|
.Li .arch
|
|
directive. Typically this is useful when code uses runtime detection of CPU
|
|
features.
|
|
.Pp
|
|
.It .fpu Va name
|
|
Select the floating point unit to assemble for. Valid values for
|
|
.Va name
|
|
are the same as for the
|
|
.Op -mfpu
|
|
commandline option.
|
|
.Pp
|
|
.It .eabi_attribute Va tag, Va value
|
|
Set the EABI object attribute number
|
|
.Va tag
|
|
to
|
|
.Va value .
|
|
The value is either a
|
|
.Li number ,
|
|
.Li "string" ,
|
|
or
|
|
.Li number, "string"
|
|
depending on the tag.
|
|
.Pp
|
|
.El
|
|
.Ss Opcodes
|
|
.Li as
|
|
implements all the standard ARM opcodes. It also implements several pseudo
|
|
opcodes, including several synthetic load instructions.
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It NOP
|
|
.Bd -literal -offset indent
|
|
nop
|
|
.Ed
|
|
.Pp
|
|
This pseudo op will always evaluate to a legal ARM instruction that does nothing.
|
|
Currently it will evaluate to MOV r0, r0.
|
|
.Pp
|
|
.It LDR
|
|
.Bd -literal -offset indent
|
|
ldr <register> , = <expression>
|
|
.Ed
|
|
.Pp
|
|
If expression evaluates to a numeric constant then a MOV or MVN instruction
|
|
will be used in place of the LDR instruction, if the constant can be generated
|
|
by either of these instructions. Otherwise the constant will be placed into
|
|
the nearest literal pool (if it not already there) and a PC relative LDR instruction
|
|
will be generated.
|
|
.Pp
|
|
.It ADR
|
|
.Bd -literal -offset indent
|
|
adr <register> <label>
|
|
.Ed
|
|
.Pp
|
|
This instruction will load the address of
|
|
.Va label
|
|
into the indicated register. The instruction will evaluate to a PC relative
|
|
ADD or SUB instruction depending upon where the label is located. If the label
|
|
is out of range, or if it is not defined in the same file (and section) as
|
|
the ADR instruction, then an error will be generated. This instruction will
|
|
not make use of the literal pool.
|
|
.Pp
|
|
.It ADRL
|
|
.Bd -literal -offset indent
|
|
adrl <register> <label>
|
|
.Ed
|
|
.Pp
|
|
This instruction will load the address of
|
|
.Va label
|
|
into the indicated register. The instruction will evaluate to one or two PC
|
|
relative ADD or SUB instructions depending upon where the label is located.
|
|
If a second instruction is not needed a NOP instruction will be generated
|
|
in its place, so that this instruction is always 8 bytes long.
|
|
.Pp
|
|
If the label is out of range, or if it is not defined in the same file (and
|
|
section) as the ADRL instruction, then an error will be generated. This instruction
|
|
will not make use of the literal pool.
|
|
.Pp
|
|
.El
|
|
For information on the ARM or Thumb instruction sets, see
|
|
.Em ARM Software Development Toolkit Reference Manual ,
|
|
Advanced RISC Machines Ltd.
|
|
.Pp
|
|
.Ss Mapping Symbols
|
|
The ARM ELF specification requires that special symbols be inserted into object
|
|
files to mark certain features:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It $a
|
|
At the start of a region of code containing ARM instructions.
|
|
.Pp
|
|
.It $t
|
|
At the start of a region of code containing THUMB instructions.
|
|
.Pp
|
|
.It $d
|
|
At the start of a region of data.
|
|
.Pp
|
|
.El
|
|
The assembler will automatically insert these symbols for you - there is no
|
|
need to code them yourself. Support for tagging symbols ($b, $f, $p and $m)
|
|
which is also mentioned in the current ARM ELF specification is not implemented.
|
|
This is because they have been dropped from the new EABI and so tools cannot
|
|
rely upon their presence.
|
|
.Pp
|
|
.Sh 80386 Dependent Features
|
|
The i386 version
|
|
.Li as
|
|
supports both the original Intel 386 architecture in both 16 and 32-bit mode
|
|
as well as AMD x86-64 architecture extending the Intel architecture to 64-bits.
|
|
.Pp
|
|
.Ss Options
|
|
The i386 version of
|
|
.Li as
|
|
has a few machine dependent options:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It --32 | --64
|
|
Select the word size, either 32 bits or 64 bits. Selecting 32-bit implies
|
|
Intel i386 architecture, while 64-bit implies AMD x86-64 architecture.
|
|
.Pp
|
|
These options are only available with the ELF object file format, and require
|
|
that the necessary BFD support has been included (on a 32-bit platform you
|
|
have to add --enable-64-bit-bfd to configure enable 64-bit usage and use x86-64
|
|
as target platform).
|
|
.Pp
|
|
.It -n
|
|
By default, x86 GAS replaces multiple nop instructions used for alignment
|
|
within code sections with multi-byte nop instructions such as leal 0(%esi,1),%esi.
|
|
This switch disables the optimization.
|
|
.Pp
|
|
.It --divide
|
|
On SVR4-derived platforms, the character
|
|
.Li /
|
|
is treated as a comment character, which means that it cannot be used in expressions.
|
|
The
|
|
.Li --divide
|
|
option turns
|
|
.Li /
|
|
into a normal character. This does not disable
|
|
.Li /
|
|
at the beginning of a line starting a comment, or affect using
|
|
.Li #
|
|
for starting a comment.
|
|
.Pp
|
|
.It -march= Va CPU
|
|
This option specifies an instruction set architecture for generating instructions.
|
|
The following architectures are recognized:
|
|
.Li i8086 ,
|
|
.Li i186 ,
|
|
.Li i286 ,
|
|
.Li i386 ,
|
|
.Li i486 ,
|
|
.Li i586 ,
|
|
.Li i686 ,
|
|
.Li pentium ,
|
|
.Li pentiumpro ,
|
|
.Li pentiumii ,
|
|
.Li pentiumiii ,
|
|
.Li pentium4 ,
|
|
.Li prescott ,
|
|
.Li nocona ,
|
|
.Li core ,
|
|
.Li core2 ,
|
|
.Li k6 ,
|
|
.Li k6_2 ,
|
|
.Li athlon ,
|
|
.Li sledgehammer ,
|
|
.Li opteron ,
|
|
.Li k8 ,
|
|
.Li generic32
|
|
and
|
|
.Li generic64 .
|
|
.Pp
|
|
This option only affects instructions generated by the assembler. The
|
|
.Li .arch
|
|
directive will take precedent.
|
|
.Pp
|
|
.It -mtune= Va CPU
|
|
This option specifies a processor to optimize for. When used in conjunction
|
|
with the
|
|
.Op -march
|
|
option, only instructions of the processor specified by the
|
|
.Op -march
|
|
option will be generated.
|
|
.Pp
|
|
Valid
|
|
.Va CPU
|
|
values are identical to
|
|
.Op -march= Va CPU .
|
|
.Pp
|
|
.El
|
|
.Ss AT&T Syntax versus Intel Syntax
|
|
.Li as
|
|
now supports assembly using Intel assembler syntax.
|
|
.Li .intel_syntax
|
|
selects Intel mode, and
|
|
.Li .att_syntax
|
|
switches back to the usual AT&T mode for compatibility with the output of
|
|
.Li gcc .
|
|
Either of these directives may have an optional argument,
|
|
.Li prefix ,
|
|
or
|
|
.Li noprefix
|
|
specifying whether registers require a
|
|
.Li %
|
|
prefix. AT&T System V/386 assembler syntax is quite different from Intel syntax.
|
|
We mention these differences because almost all 80386 documents use Intel
|
|
syntax. Notable differences between the two syntaxes are:
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
AT&T immediate operands are preceded by
|
|
.Li $ ;
|
|
Intel immediate operands are undelimited (Intel
|
|
.Li push 4
|
|
is AT&T
|
|
.Li pushl $4 ) .
|
|
AT&T register operands are preceded by
|
|
.Li % ;
|
|
Intel register operands are undelimited. AT&T absolute (as opposed to PC relative)
|
|
jump/call operands are prefixed by
|
|
.Li * ;
|
|
they are undelimited in Intel syntax.
|
|
.Pp
|
|
.It
|
|
AT&T and Intel syntax use the opposite order for source and destination operands.
|
|
Intel
|
|
.Li add eax, 4
|
|
is
|
|
.Li addl $4, %eax .
|
|
The
|
|
.Li source, dest
|
|
convention is maintained for compatibility with previous Unix assemblers.
|
|
Note that instructions with more than one source operand, such as the
|
|
.Li enter
|
|
instruction, do
|
|
.Em not
|
|
have reversed order. i386-Bugs.
|
|
.Pp
|
|
.It
|
|
In AT&T syntax the size of memory operands is determined from the last character
|
|
of the instruction mnemonic. Mnemonic suffixes of
|
|
.Li b ,
|
|
.Li w ,
|
|
.Li l
|
|
and
|
|
.Li q
|
|
specify byte (8-bit), word (16-bit), long (32-bit) and quadruple word (64-bit)
|
|
memory references. Intel syntax accomplishes this by prefixing memory operands
|
|
(
|
|
.Em not
|
|
the instruction mnemonics) with
|
|
.Li byte ptr ,
|
|
.Li word ptr ,
|
|
.Li dword ptr
|
|
and
|
|
.Li qword ptr .
|
|
Thus, Intel
|
|
.Li mov al, byte ptr Va foo
|
|
is
|
|
.Li movb Va foo, %al
|
|
in AT&T syntax.
|
|
.Pp
|
|
.It
|
|
Immediate form long jumps and calls are
|
|
.Li lcall/ljmp $ Va section, $ Va offset
|
|
in AT&T syntax; the Intel syntax is
|
|
.Li call/jmp far Va section: Va offset .
|
|
Also, the far return instruction is
|
|
.Li lret $ Va stack-adjust
|
|
in AT&T syntax; Intel syntax is
|
|
.Li ret far Va stack-adjust .
|
|
.Pp
|
|
.It
|
|
The AT&T assembler does not provide support for multiple section programs.
|
|
Unix style systems expect all programs to be single sections.
|
|
.El
|
|
.Pp
|
|
.Ss Instruction Naming
|
|
Instruction mnemonics are suffixed with one character modifiers which specify
|
|
the size of operands. The letters
|
|
.Li b ,
|
|
.Li w ,
|
|
.Li l
|
|
and
|
|
.Li q
|
|
specify byte, word, long and quadruple word operands. If no suffix is specified
|
|
by an instruction then
|
|
.Li as
|
|
tries to fill in the missing suffix based on the destination register operand
|
|
(the last one by convention). Thus,
|
|
.Li mov %ax, %bx
|
|
is equivalent to
|
|
.Li movw %ax, %bx ;
|
|
also,
|
|
.Li mov $1, %bx
|
|
is equivalent to
|
|
.Li movw $1, bx .
|
|
Note that this is incompatible with the AT&T Unix assembler which assumes
|
|
that a missing mnemonic suffix implies long operand size. (This incompatibility
|
|
does not affect compiler output since compilers always explicitly specify
|
|
the mnemonic suffix.)
|
|
.Pp
|
|
Almost all instructions have the same names in AT&T and Intel format. There
|
|
are a few exceptions. The sign extend and zero extend instructions need two
|
|
sizes to specify them. They need a size to sign/zero extend
|
|
.Em from
|
|
and a size to zero extend
|
|
.Em to .
|
|
This is accomplished by using two instruction mnemonic suffixes in AT&T syntax.
|
|
Base names for sign extend and zero extend are
|
|
.Li movs...
|
|
and
|
|
.Li movz...
|
|
in AT&T syntax (
|
|
.Li movsx
|
|
and
|
|
.Li movzx
|
|
in Intel syntax). The instruction mnemonic suffixes are tacked on to this
|
|
base name, the
|
|
.Em from
|
|
suffix before the
|
|
.Em to
|
|
suffix. Thus,
|
|
.Li movsbl %al, %edx
|
|
is AT&T syntax for \(lqmove sign extend
|
|
.Em from
|
|
%al
|
|
.Em to
|
|
%edx.\(rq Possible suffixes, thus, are
|
|
.Li bl
|
|
(from byte to long),
|
|
.Li bw
|
|
(from byte to word),
|
|
.Li wl
|
|
(from word to long),
|
|
.Li bq
|
|
(from byte to quadruple word),
|
|
.Li wq
|
|
(from word to quadruple word), and
|
|
.Li lq
|
|
(from long to quadruple word).
|
|
.Pp
|
|
The Intel-syntax conversion instructions
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
.Li cbw
|
|
--- sign-extend byte in
|
|
.Li %al
|
|
to word in
|
|
.Li %ax ,
|
|
.Pp
|
|
.It
|
|
.Li cwde
|
|
--- sign-extend word in
|
|
.Li %ax
|
|
to long in
|
|
.Li %eax ,
|
|
.Pp
|
|
.It
|
|
.Li cwd
|
|
--- sign-extend word in
|
|
.Li %ax
|
|
to long in
|
|
.Li %dx:%ax ,
|
|
.Pp
|
|
.It
|
|
.Li cdq
|
|
--- sign-extend dword in
|
|
.Li %eax
|
|
to quad in
|
|
.Li %edx:%eax ,
|
|
.Pp
|
|
.It
|
|
.Li cdqe
|
|
--- sign-extend dword in
|
|
.Li %eax
|
|
to quad in
|
|
.Li %rax
|
|
(x86-64 only),
|
|
.Pp
|
|
.It
|
|
.Li cqo
|
|
--- sign-extend quad in
|
|
.Li %rax
|
|
to octuple in
|
|
.Li %rdx:%rax
|
|
(x86-64 only),
|
|
.El
|
|
.Pp
|
|
are called
|
|
.Li cbtw ,
|
|
.Li cwtl ,
|
|
.Li cwtd ,
|
|
.Li cltd ,
|
|
.Li cltq ,
|
|
and
|
|
.Li cqto
|
|
in AT&T naming.
|
|
.Li as
|
|
accepts either naming for these instructions.
|
|
.Pp
|
|
Far call/jump instructions are
|
|
.Li lcall
|
|
and
|
|
.Li ljmp
|
|
in AT&T syntax, but are
|
|
.Li call far
|
|
and
|
|
.Li jump far
|
|
in Intel convention.
|
|
.Pp
|
|
.Ss Register Naming
|
|
Register operands are always prefixed with
|
|
.Li % .
|
|
The 80386 registers consist of
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
the 8 32-bit registers
|
|
.Li %eax
|
|
(the accumulator),
|
|
.Li %ebx ,
|
|
.Li %ecx ,
|
|
.Li %edx ,
|
|
.Li %edi ,
|
|
.Li %esi ,
|
|
.Li %ebp
|
|
(the frame pointer), and
|
|
.Li %esp
|
|
(the stack pointer).
|
|
.Pp
|
|
.It
|
|
the 8 16-bit low-ends of these:
|
|
.Li %ax ,
|
|
.Li %bx ,
|
|
.Li %cx ,
|
|
.Li %dx ,
|
|
.Li %di ,
|
|
.Li %si ,
|
|
.Li %bp ,
|
|
and
|
|
.Li %sp .
|
|
.Pp
|
|
.It
|
|
the 8 8-bit registers:
|
|
.Li %ah ,
|
|
.Li %al ,
|
|
.Li %bh ,
|
|
.Li %bl ,
|
|
.Li %ch ,
|
|
.Li %cl ,
|
|
.Li %dh ,
|
|
and
|
|
.Li %dl
|
|
(These are the high-bytes and low-bytes of
|
|
.Li %ax ,
|
|
.Li %bx ,
|
|
.Li %cx ,
|
|
and
|
|
.Li %dx )
|
|
.Pp
|
|
.It
|
|
the 6 section registers
|
|
.Li %cs
|
|
(code section),
|
|
.Li %ds
|
|
(data section),
|
|
.Li %ss
|
|
(stack section),
|
|
.Li %es ,
|
|
.Li %fs ,
|
|
and
|
|
.Li %gs .
|
|
.Pp
|
|
.It
|
|
the 3 processor control registers
|
|
.Li %cr0 ,
|
|
.Li %cr2 ,
|
|
and
|
|
.Li %cr3 .
|
|
.Pp
|
|
.It
|
|
the 6 debug registers
|
|
.Li %db0 ,
|
|
.Li %db1 ,
|
|
.Li %db2 ,
|
|
.Li %db3 ,
|
|
.Li %db6 ,
|
|
and
|
|
.Li %db7 .
|
|
.Pp
|
|
.It
|
|
the 2 test registers
|
|
.Li %tr6
|
|
and
|
|
.Li %tr7 .
|
|
.Pp
|
|
.It
|
|
the 8 floating point register stack
|
|
.Li %st
|
|
or equivalently
|
|
.Li %st(0) ,
|
|
.Li %st(1) ,
|
|
.Li %st(2) ,
|
|
.Li %st(3) ,
|
|
.Li %st(4) ,
|
|
.Li %st(5) ,
|
|
.Li %st(6) ,
|
|
and
|
|
.Li %st(7) .
|
|
These registers are overloaded by 8 MMX registers
|
|
.Li %mm0 ,
|
|
.Li %mm1 ,
|
|
.Li %mm2 ,
|
|
.Li %mm3 ,
|
|
.Li %mm4 ,
|
|
.Li %mm5 ,
|
|
.Li %mm6
|
|
and
|
|
.Li %mm7 .
|
|
.Pp
|
|
.It
|
|
the 8 SSE registers registers
|
|
.Li %xmm0 ,
|
|
.Li %xmm1 ,
|
|
.Li %xmm2 ,
|
|
.Li %xmm3 ,
|
|
.Li %xmm4 ,
|
|
.Li %xmm5 ,
|
|
.Li %xmm6
|
|
and
|
|
.Li %xmm7 .
|
|
.El
|
|
.Pp
|
|
The AMD x86-64 architecture extends the register set by:
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
enhancing the 8 32-bit registers to 64-bit:
|
|
.Li %rax
|
|
(the accumulator),
|
|
.Li %rbx ,
|
|
.Li %rcx ,
|
|
.Li %rdx ,
|
|
.Li %rdi ,
|
|
.Li %rsi ,
|
|
.Li %rbp
|
|
(the frame pointer),
|
|
.Li %rsp
|
|
(the stack pointer)
|
|
.Pp
|
|
.It
|
|
the 8 extended registers
|
|
.Li %r8
|
|
--
|
|
.Li %r15 .
|
|
.Pp
|
|
.It
|
|
the 8 32-bit low ends of the extended registers:
|
|
.Li %r8d
|
|
--
|
|
.Li %r15d
|
|
.Pp
|
|
.It
|
|
the 8 16-bit low ends of the extended registers:
|
|
.Li %r8w
|
|
--
|
|
.Li %r15w
|
|
.Pp
|
|
.It
|
|
the 8 8-bit low ends of the extended registers:
|
|
.Li %r8b
|
|
--
|
|
.Li %r15b
|
|
.Pp
|
|
.It
|
|
the 4 8-bit registers:
|
|
.Li %sil ,
|
|
.Li %dil ,
|
|
.Li %bpl ,
|
|
.Li %spl .
|
|
.Pp
|
|
.It
|
|
the 8 debug registers:
|
|
.Li %db8
|
|
--
|
|
.Li %db15 .
|
|
.Pp
|
|
.It
|
|
the 8 SSE registers:
|
|
.Li %xmm8
|
|
--
|
|
.Li %xmm15 .
|
|
.El
|
|
.Pp
|
|
.Ss Instruction Prefixes
|
|
Instruction prefixes are used to modify the following instruction. They are
|
|
used to repeat string instructions, to provide section overrides, to perform
|
|
bus lock operations, and to change operand and address sizes. (Most instructions
|
|
that normally operate on 32-bit operands will use 16-bit operands if the instruction
|
|
has an \(lqoperand size\(rq prefix.) Instruction prefixes are best written on the
|
|
same line as the instruction they act upon. For example, the
|
|
.Li scas
|
|
(scan string) instruction is repeated with:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
repne scas %es:(%edi),%al
|
|
.Ed
|
|
.Pp
|
|
You may also place prefixes on the lines immediately preceding the instruction,
|
|
but this circumvents checks that
|
|
.Li as
|
|
does with prefixes, and will not work with all prefixes.
|
|
.Pp
|
|
Here is a list of instruction prefixes:
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
Section override prefixes
|
|
.Li cs ,
|
|
.Li ds ,
|
|
.Li ss ,
|
|
.Li es ,
|
|
.Li fs ,
|
|
.Li gs .
|
|
These are automatically added by specifying using the
|
|
.Va section
|
|
:
|
|
.Va memory-operand
|
|
form for memory references.
|
|
.Pp
|
|
.It
|
|
Operand/Address size prefixes
|
|
.Li data16
|
|
and
|
|
.Li addr16
|
|
change 32-bit operands/addresses into 16-bit operands/addresses, while
|
|
.Li data32
|
|
and
|
|
.Li addr32
|
|
change 16-bit ones (in a
|
|
.Li .code16
|
|
section) into 32-bit operands/addresses. These prefixes
|
|
.Em must
|
|
appear on the same line of code as the instruction they modify. For example,
|
|
in a 16-bit
|
|
.Li .code16
|
|
section, you might write:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
addr32 jmpl *(%ebx)
|
|
.Ed
|
|
.Pp
|
|
.It
|
|
The bus lock prefix
|
|
.Li lock
|
|
inhibits interrupts during execution of the instruction it precedes. (This
|
|
is only valid with certain instructions; see a 80386 manual for details).
|
|
.Pp
|
|
.It
|
|
The wait for coprocessor prefix
|
|
.Li wait
|
|
waits for the coprocessor to complete the current instruction. This should
|
|
never be needed for the 80386/80387 combination.
|
|
.Pp
|
|
.It
|
|
The
|
|
.Li rep ,
|
|
.Li repe ,
|
|
and
|
|
.Li repne
|
|
prefixes are added to string instructions to make them repeat
|
|
.Li %ecx
|
|
times (
|
|
.Li %cx
|
|
times if the current address size is 16-bits).
|
|
.It
|
|
The
|
|
.Li rex
|
|
family of prefixes is used by x86-64 to encode extensions to i386 instruction
|
|
set. The
|
|
.Li rex
|
|
prefix has four bits --- an operand size overwrite (
|
|
.Li 64 )
|
|
used to change operand size from 32-bit to 64-bit and X, Y and Z extensions
|
|
bits used to extend the register set.
|
|
.Pp
|
|
You may write the
|
|
.Li rex
|
|
prefixes directly. The
|
|
.Li rex64xyz
|
|
instruction emits
|
|
.Li rex
|
|
prefix with all the bits set. By omitting the
|
|
.Li 64 ,
|
|
.Li x ,
|
|
.Li y
|
|
or
|
|
.Li z
|
|
you may write other prefixes as well. Normally, there is no need to write
|
|
the prefixes explicitly, since gas will automatically generate them based
|
|
on the instruction operands.
|
|
.El
|
|
.Pp
|
|
.Ss Memory References
|
|
An Intel syntax indirect memory reference of the form
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
section:[base + index*scale + disp]
|
|
.Ed
|
|
.Pp
|
|
is translated into the AT&T syntax
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
section:disp(base, index, scale)
|
|
.Ed
|
|
.Pp
|
|
where
|
|
.Va base
|
|
and
|
|
.Va index
|
|
are the optional 32-bit base and index registers,
|
|
.Va disp
|
|
is the optional displacement, and
|
|
.Va scale ,
|
|
taking the values 1, 2, 4, and 8, multiplies
|
|
.Va index
|
|
to calculate the address of the operand. If no
|
|
.Va scale
|
|
is specified,
|
|
.Va scale
|
|
is taken to be 1.
|
|
.Va section
|
|
specifies the optional section register for the memory operand, and may override
|
|
the default section register (see a 80386 manual for section register defaults).
|
|
Note that section overrides in AT&T syntax
|
|
.Em must
|
|
be preceded by a
|
|
.Li % .
|
|
If you specify a section override which coincides with the default section
|
|
register,
|
|
.Li as
|
|
does
|
|
.Em not
|
|
output any section register override prefixes to assemble the given instruction.
|
|
Thus, section overrides can be specified to emphasize which section register
|
|
is used for a given memory operand.
|
|
.Pp
|
|
Here are some examples of Intel and AT&T style memory references:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It AT&T: Li -4(%ebp), Intel: Li [ebp - 4]
|
|
.Va base
|
|
is
|
|
.Li %ebp ;
|
|
.Va disp
|
|
is
|
|
.Li -4 .
|
|
.Va section
|
|
is missing, and the default section is used (
|
|
.Li %ss
|
|
for addressing with
|
|
.Li %ebp
|
|
as the base register).
|
|
.Va index ,
|
|
.Va scale
|
|
are both missing.
|
|
.Pp
|
|
.It AT&T: Li foo(,%eax,4), Intel: Li [foo + eax*4]
|
|
.Va index
|
|
is
|
|
.Li %eax
|
|
(scaled by a
|
|
.Va scale
|
|
4);
|
|
.Va disp
|
|
is
|
|
.Li foo .
|
|
All other fields are missing. The section register here defaults to
|
|
.Li %ds .
|
|
.Pp
|
|
.It AT&T: Li foo(,1); Intel Li [foo]
|
|
This uses the value pointed to by
|
|
.Li foo
|
|
as a memory operand. Note that
|
|
.Va base
|
|
and
|
|
.Va index
|
|
are both missing, but there is only
|
|
.Em one
|
|
.Li , .
|
|
This is a syntactic exception.
|
|
.Pp
|
|
.It AT&T: Li %gs:foo; Intel Li gs:foo
|
|
This selects the contents of the variable
|
|
.Li foo
|
|
with section register
|
|
.Va section
|
|
being
|
|
.Li %gs .
|
|
.El
|
|
.Pp
|
|
Absolute (as opposed to PC relative) call and jump operands must be prefixed
|
|
with
|
|
.Li * .
|
|
If no
|
|
.Li *
|
|
is specified,
|
|
.Li as
|
|
always chooses PC relative addressing for jump/call labels.
|
|
.Pp
|
|
Any instruction that has a memory operand, but no register operand,
|
|
.Em must
|
|
specify its size (byte, word, long, or quadruple) with an instruction mnemonic
|
|
suffix (
|
|
.Li b ,
|
|
.Li w ,
|
|
.Li l
|
|
or
|
|
.Li q ,
|
|
respectively).
|
|
.Pp
|
|
The x86-64 architecture adds an RIP (instruction pointer relative) addressing.
|
|
This addressing mode is specified by using
|
|
.Li rip
|
|
as a base register. Only constant offsets are valid. For example:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It AT&T: Li 1234(%rip), Intel: Li [rip + 1234]
|
|
Points to the address 1234 bytes past the end of the current instruction.
|
|
.Pp
|
|
.It AT&T: Li symbol(%rip), Intel: Li [rip + symbol]
|
|
Points to the
|
|
.Li symbol
|
|
in RIP relative way, this is shorter than the default absolute addressing.
|
|
.El
|
|
.Pp
|
|
Other addressing modes remain unchanged in x86-64 architecture, except registers
|
|
used are 64-bit instead of 32-bit.
|
|
.Pp
|
|
.Ss Handling of Jump Instructions
|
|
Jump instructions are always optimized to use the smallest possible displacements.
|
|
This is accomplished by using byte (8-bit) displacement jumps whenever the
|
|
target is sufficiently close. If a byte displacement is insufficient a long
|
|
displacement is used. We do not support word (16-bit) displacement jumps in
|
|
32-bit mode (i.e. prefixing the jump instruction with the
|
|
.Li data16
|
|
instruction prefix), since the 80386 insists upon masking
|
|
.Li %eip
|
|
to 16 bits after the word displacement is added. (See alsosee Section
|
|
.Dq i386-Arch )
|
|
.Pp
|
|
Note that the
|
|
.Li jcxz ,
|
|
.Li jecxz ,
|
|
.Li loop ,
|
|
.Li loopz ,
|
|
.Li loope ,
|
|
.Li loopnz
|
|
and
|
|
.Li loopne
|
|
instructions only come in byte displacements, so that if you use these instructions
|
|
(
|
|
.Li gcc
|
|
does not use them) you may get an error message (and incorrect code). The
|
|
AT&T 80386 assembler tries to get around this problem by expanding
|
|
.Li jcxz foo
|
|
to
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
jcxz cx_zero
|
|
jmp cx_nonzero
|
|
cx_zero: jmp foo
|
|
cx_nonzero:
|
|
.Ed
|
|
.Pp
|
|
.Ss Floating Point
|
|
All 80387 floating point types except packed BCD are supported. (BCD support
|
|
may be added without much difficulty). These data types are 16-, 32-, and
|
|
64- bit integers, and single (32-bit), double (64-bit), and extended (80-bit)
|
|
precision floating point. Each supported type has an instruction mnemonic
|
|
suffix and a constructor associated with it. Instruction mnemonic suffixes
|
|
specify the operand's data type. Constructors build these data types into
|
|
memory.
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
Floating point constructors are
|
|
.Li .float
|
|
or
|
|
.Li .single ,
|
|
.Li .double ,
|
|
and
|
|
.Li .tfloat
|
|
for 32-, 64-, and 80-bit formats. These correspond to instruction mnemonic
|
|
suffixes
|
|
.Li s ,
|
|
.Li l ,
|
|
and
|
|
.Li t .
|
|
.Li t
|
|
stands for 80-bit (ten byte) real. The 80387 only supports this format via
|
|
the
|
|
.Li fldt
|
|
(load 80-bit real to stack top) and
|
|
.Li fstpt
|
|
(store 80-bit real and pop stack) instructions.
|
|
.Pp
|
|
.It
|
|
Integer constructors are
|
|
.Li .word ,
|
|
.Li .long
|
|
or
|
|
.Li .int ,
|
|
and
|
|
.Li .quad
|
|
for the 16-, 32-, and 64-bit integer formats. The corresponding instruction
|
|
mnemonic suffixes are
|
|
.Li s
|
|
(single),
|
|
.Li l
|
|
(long), and
|
|
.Li q
|
|
(quad). As with the 80-bit real format, the 64-bit
|
|
.Li q
|
|
format is only present in the
|
|
.Li fildq
|
|
(load quad integer to stack top) and
|
|
.Li fistpq
|
|
(store quad integer and pop stack) instructions.
|
|
.El
|
|
.Pp
|
|
Register to register operations should not use instruction mnemonic suffixes.
|
|
.Li fstl %st, %st(1)
|
|
will give a warning, and be assembled as if you wrote
|
|
.Li fst %st, %st(1) ,
|
|
since all register to register operations use 80-bit floating point operands.
|
|
(Contrast this with
|
|
.Li fstl %st, mem ,
|
|
which converts
|
|
.Li %st
|
|
from 80-bit to 64-bit floating point format, then stores the result in the
|
|
4 byte location
|
|
.Li mem )
|
|
.Pp
|
|
.Ss Intel's MMX and AMD's 3DNow! SIMD Operations
|
|
.Li as
|
|
supports Intel's MMX instruction set (SIMD instructions for integer data),
|
|
available on Intel's Pentium MMX processors and Pentium II processors, AMD's
|
|
K6 and K6-2 processors, Cyrix' M2 processor, and probably others. It also
|
|
supports AMD's 3DNow! instruction set (SIMD instructions for 32-bit floating
|
|
point data) available on AMD's K6-2 processor and possibly others in the future.
|
|
.Pp
|
|
Currently,
|
|
.Li as
|
|
does not support Intel's floating point SIMD, Katmai (KNI).
|
|
.Pp
|
|
The eight 64-bit MMX operands, also used by 3DNow!, are called
|
|
.Li %mm0 ,
|
|
.Li %mm1 ,
|
|
\&...
|
|
.Li %mm7 .
|
|
They contain eight 8-bit integers, four 16-bit integers, two 32-bit integers,
|
|
one 64-bit integer, or two 32-bit floating point values. The MMX registers
|
|
cannot be used at the same time as the floating point stack.
|
|
.Pp
|
|
See Intel and AMD documentation, keeping in mind that the operand order in
|
|
instructions is reversed from the Intel syntax.
|
|
.Pp
|
|
.Ss Writing 16-bit Code
|
|
While
|
|
.Li as
|
|
normally writes only \(lqpure\(rq 32-bit i386 code or 64-bit x86-64 code depending
|
|
on the default configuration, it also supports writing code to run in real
|
|
mode or in 16-bit protected mode code segments. To do this, put a
|
|
.Li .code16
|
|
or
|
|
.Li .code16gcc
|
|
directive before the assembly language instructions to be run in 16-bit mode.
|
|
You can switch
|
|
.Li as
|
|
back to writing normal 32-bit code with the
|
|
.Li .code32
|
|
directive.
|
|
.Pp
|
|
.Li .code16gcc
|
|
provides experimental support for generating 16-bit code from gcc, and differs
|
|
from
|
|
.Li .code16
|
|
in that
|
|
.Li call ,
|
|
.Li ret ,
|
|
.Li enter ,
|
|
.Li leave ,
|
|
.Li push ,
|
|
.Li pop ,
|
|
.Li pusha ,
|
|
.Li popa ,
|
|
.Li pushf ,
|
|
and
|
|
.Li popf
|
|
instructions default to 32-bit size. This is so that the stack pointer is
|
|
manipulated in the same way over function calls, allowing access to function
|
|
parameters at the same stack offsets as in 32-bit mode.
|
|
.Li .code16gcc
|
|
also automatically adds address size prefixes where necessary to use the 32-bit
|
|
addressing modes that gcc generates.
|
|
.Pp
|
|
The code which
|
|
.Li as
|
|
generates in 16-bit mode will not necessarily run on a 16-bit pre-80386 processor.
|
|
To write code that runs on such a processor, you must refrain from using
|
|
.Em any
|
|
32-bit constructs which require
|
|
.Li as
|
|
to output address or operand size prefixes.
|
|
.Pp
|
|
Note that writing 16-bit code instructions by explicitly specifying a prefix
|
|
or an instruction mnemonic suffix within a 32-bit code section generates different
|
|
machine instructions than those generated for a 16-bit code segment. In a
|
|
32-bit code section, the following code generates the machine opcode bytes
|
|
.Li 66 6a 04 ,
|
|
which pushes the value
|
|
.Li 4
|
|
onto the stack, decrementing
|
|
.Li %esp
|
|
by 2.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
pushw $4
|
|
.Ed
|
|
.Pp
|
|
The same code in a 16-bit code section would generate the machine opcode bytes
|
|
.Li 6a 04
|
|
(i.e., without the operand size prefix), which is correct since the processor
|
|
default operand size is assumed to be 16 bits in a 16-bit code section.
|
|
.Pp
|
|
.Ss AT&T Syntax bugs
|
|
The UnixWare assembler, and probably other AT&T derived ix86 Unix assemblers,
|
|
generate floating point instructions with reversed source and destination
|
|
registers in certain cases. Unfortunately, gcc and possibly many other programs
|
|
use this reversed syntax, so we're stuck with it.
|
|
.Pp
|
|
For example
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
fsub %st,%st(3)
|
|
.Ed
|
|
results in
|
|
.Li %st(3)
|
|
being updated to
|
|
.Li %st - %st(3)
|
|
rather than the expected
|
|
.Li %st(3) - %st .
|
|
This happens with all the non-commutative arithmetic floating point operations
|
|
with two register operands where the source register is
|
|
.Li %st
|
|
and the destination register is
|
|
.Li %st(i) .
|
|
.Pp
|
|
.Ss Specifying CPU Architecture
|
|
.Li as
|
|
may be told to assemble for a particular CPU (sub-)architecture with the
|
|
.Li .arch Va cpu_type
|
|
directive. This directive enables a warning when gas detects an instruction
|
|
that is not supported on the CPU specified. The choices for
|
|
.Va cpu_type
|
|
are:
|
|
.Pp
|
|
.TS
|
|
l l l l.
|
|
|
|
i8086 i186 i286 i386
|
|
i486 i586 i686 pentium
|
|
pentiumpro pentiumii pentiumiii pentium4
|
|
prescott nocona core core2
|
|
amdfam10
|
|
k6 athlon sledgehammer k8
|
|
\&.mmx .sse .sse2 .sse3
|
|
\&.ssse3 .sse4.1 .sse4.2 .sse4
|
|
\&.sse4a .3dnow .3dnowa .padlock
|
|
\&.pacifica .svme .abm
|
|
.TE
|
|
.Pp
|
|
Apart from the warning, there are only two other effects on
|
|
.Li as
|
|
operation; Firstly, if you specify a CPU other than
|
|
.Li i486 ,
|
|
then shift by one instructions such as
|
|
.Li sarl $1, %eax
|
|
will automatically use a two byte opcode sequence. The larger three byte opcode
|
|
sequence is used on the 486 (and when no architecture is specified) because
|
|
it executes faster on the 486. Note that you can explicitly request the two
|
|
byte opcode by writing
|
|
.Li sarl %eax .
|
|
Secondly, if you specify
|
|
.Li i8086 ,
|
|
.Li i186 ,
|
|
or
|
|
.Li i286 ,
|
|
.Em and
|
|
.Li .code16
|
|
or
|
|
.Li .code16gcc
|
|
then byte offset conditional jumps will be promoted when necessary to a two
|
|
instruction sequence consisting of a conditional jump of the opposite sense
|
|
around an unconditional jump to the target.
|
|
.Pp
|
|
Following the CPU architecture (but not a sub-architecture, which are those
|
|
starting with a dot), you may specify
|
|
.Li jumps
|
|
or
|
|
.Li nojumps
|
|
to control automatic promotion of conditional jumps.
|
|
.Li jumps
|
|
is the default, and enables jump promotion; All external jumps will be of
|
|
the long variety, and file-local jumps will be promoted as necessary. (see Section
|
|
.Dq i386-Jumps )
|
|
.Li nojumps
|
|
leaves external conditional jumps as byte offset jumps, and warns about file-local
|
|
conditional jumps that
|
|
.Li as
|
|
promotes. Unconditional jumps are treated as for
|
|
.Li jumps .
|
|
.Pp
|
|
For example
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.arch i8086,nojumps
|
|
.Ed
|
|
.Pp
|
|
.Ss Notes
|
|
There is some trickery concerning the
|
|
.Li mul
|
|
and
|
|
.Li imul
|
|
instructions that deserves mention. The 16-, 32-, 64- and 128-bit expanding
|
|
multiplies (base opcode
|
|
.Li 0xf6 ;
|
|
extension 4 for
|
|
.Li mul
|
|
and 5 for
|
|
.Li imul )
|
|
can be output only in the one operand form. Thus,
|
|
.Li imul %ebx, %eax
|
|
does
|
|
.Em not
|
|
select the expanding multiply; the expanding multiply would clobber the
|
|
.Li %edx
|
|
register, and this would confuse
|
|
.Li gcc
|
|
output. Use
|
|
.Li imul %ebx
|
|
to get the 64-bit product in
|
|
.Li %edx:%eax .
|
|
.Pp
|
|
We have added a two operand form of
|
|
.Li imul
|
|
when the first operand is an immediate mode expression and the second operand
|
|
is a register. This is just a shorthand, so that, multiplying
|
|
.Li %eax
|
|
by 69, for example, can be done with
|
|
.Li imul $69, %eax
|
|
rather than
|
|
.Li imul $69, %eax, %eax .
|
|
.Pp
|
|
.Sh IA-64 Dependent Features
|
|
.Ss Options
|
|
.Bl -tag -width Ds
|
|
.It -mconstant-gp
|
|
This option instructs the assembler to mark the resulting object file as using
|
|
the \(lqconstant GP\(rq model. With this model, it is assumed that the entire program
|
|
uses a single global pointer (GP) value. Note that this option does not in
|
|
any fashion affect the machine code emitted by the assembler. All it does
|
|
is turn on the EF_IA_64_CONS_GP flag in the ELF file header.
|
|
.Pp
|
|
.It -mauto-pic
|
|
This option instructs the assembler to mark the resulting object file as using
|
|
the \(lqconstant GP without function descriptor\(rq data model. This model is like
|
|
the \(lqconstant GP\(rq model, except that it additionally does away with function
|
|
descriptors. What this means is that the address of a function refers directly
|
|
to the function's code entry-point. Normally, such an address would refer
|
|
to a function descriptor, which contains both the code entry-point and the
|
|
GP-value needed by the function. Note that this option does not in any fashion
|
|
affect the machine code emitted by the assembler. All it does is turn on the
|
|
EF_IA_64_NOFUNCDESC_CONS_GP flag in the ELF file header.
|
|
.Pp
|
|
.It -milp32
|
|
.It -milp64
|
|
.It -mlp64
|
|
.It -mp64
|
|
These options select the data model. The assembler defaults to
|
|
.Li -mlp64
|
|
(LP64 data model).
|
|
.Pp
|
|
.It -mle
|
|
.It -mbe
|
|
These options select the byte order. The
|
|
.Li -mle
|
|
option selects little-endian byte order (default) and
|
|
.Li -mbe
|
|
selects big-endian byte order. Note that IA-64 machine code always uses little-endian
|
|
byte order.
|
|
.Pp
|
|
.It -mtune=itanium1
|
|
.It -mtune=itanium2
|
|
Tune for a particular IA-64 CPU,
|
|
.Va itanium1
|
|
or
|
|
.Va itanium2 .
|
|
The default is
|
|
.Va itanium2 .
|
|
.Pp
|
|
.It -munwind-check=warning
|
|
.It -munwind-check=error
|
|
These options control what the assembler will do when performing consistency
|
|
checks on unwind directives.
|
|
.Li -munwind-check=warning
|
|
will make the assembler issue a warning when an unwind directive check fails.
|
|
This is the default.
|
|
.Li -munwind-check=error
|
|
will make the assembler issue an error when an unwind directive check fails.
|
|
.Pp
|
|
.It -mhint.b=ok
|
|
.It -mhint.b=warning
|
|
.It -mhint.b=error
|
|
These options control what the assembler will do when the
|
|
.Li hint.b
|
|
instruction is used.
|
|
.Li -mhint.b=ok
|
|
will make the assembler accept
|
|
.Li hint.b .
|
|
.Li -mint.b=warning
|
|
will make the assembler issue a warning when
|
|
.Li hint.b
|
|
is used.
|
|
.Li -mhint.b=error
|
|
will make the assembler treat
|
|
.Li hint.b
|
|
as an error, which is the default.
|
|
.Pp
|
|
.It -x
|
|
.It -xexplicit
|
|
These options turn on dependency violation checking.
|
|
.Pp
|
|
.It -xauto
|
|
This option instructs the assembler to automatically insert stop bits where
|
|
necessary to remove dependency violations. This is the default mode.
|
|
.Pp
|
|
.It -xnone
|
|
This option turns off dependency violation checking.
|
|
.Pp
|
|
.It -xdebug
|
|
This turns on debug output intended to help tracking down bugs in the dependency
|
|
violation checker.
|
|
.Pp
|
|
.It -xdebugn
|
|
This is a shortcut for -xnone -xdebug.
|
|
.Pp
|
|
.It -xdebugx
|
|
This is a shortcut for -xexplicit -xdebug.
|
|
.Pp
|
|
.El
|
|
.Ss Syntax
|
|
The assembler syntax closely follows the IA-64 Assembly Language Reference
|
|
Guide.
|
|
.Pp
|
|
.Em Special Characters
|
|
.Pp
|
|
.Li //
|
|
is the line comment token.
|
|
.Pp
|
|
.Li ;
|
|
can be used instead of a newline to separate statements.
|
|
.Pp
|
|
.Em Register Names
|
|
.Pp
|
|
The 128 integer registers are referred to as
|
|
.Li r Va n .
|
|
The 128 floating-point registers are referred to as
|
|
.Li f Va n .
|
|
The 128 application registers are referred to as
|
|
.Li ar Va n .
|
|
The 128 control registers are referred to as
|
|
.Li cr Va n .
|
|
The 64 one-bit predicate registers are referred to as
|
|
.Li p Va n .
|
|
The 8 branch registers are referred to as
|
|
.Li b Va n .
|
|
In addition, the assembler defines a number of aliases:
|
|
.Li gp
|
|
(
|
|
.Li r1 ) ,
|
|
.Li sp
|
|
(
|
|
.Li r12 ) ,
|
|
.Li rp
|
|
(
|
|
.Li b0 ) ,
|
|
.Li ret0
|
|
(
|
|
.Li r8 ) ,
|
|
.Li ret1
|
|
(
|
|
.Li r9 ) ,
|
|
.Li ret2
|
|
(
|
|
.Li r10 ) ,
|
|
.Li ret3
|
|
(
|
|
.Li r9 ) ,
|
|
.Li farg Va n
|
|
(
|
|
.Li f8+ Va n ) ,
|
|
and
|
|
.Li fret Va n
|
|
(
|
|
.Li f8+ Va n ) .
|
|
.Pp
|
|
For convenience, the assembler also defines aliases for all named application
|
|
and control registers. For example,
|
|
.Li ar.bsp
|
|
refers to the register backing store pointer (
|
|
.Li ar17 ) .
|
|
Similarly,
|
|
.Li cr.eoi
|
|
refers to the end-of-interrupt register (
|
|
.Li cr67 ) .
|
|
.Pp
|
|
.Em IA-64 Processor-Status-Register (PSR) Bit Names
|
|
.Pp
|
|
The assembler defines bit masks for each of the bits in the IA-64 processor
|
|
status register. For example,
|
|
.Li psr.ic
|
|
corresponds to a value of 0x2000. These masks are primarily intended for use
|
|
with the
|
|
.Li ssm
|
|
/
|
|
.Li sum
|
|
and
|
|
.Li rsm
|
|
/
|
|
.Li rum
|
|
instructions, but they can be used anywhere else where an integer constant
|
|
is expected.
|
|
.Pp
|
|
.Ss Opcodes
|
|
For detailed information on the IA-64 machine instruction set, see the
|
|
.Lk http://developer.intel.com/design/itanium/arch_spec.htm .
|
|
.Pp
|
|
.Sh MIPS Dependent Features
|
|
GNU
|
|
.Li as
|
|
for mips architectures supports several different mips processors, and MIPS
|
|
ISA levels I through V, MIPS32, and MIPS64. For information about the mips
|
|
instruction set, see
|
|
.Em MIPS RISC Architecture ,
|
|
by Kane and Heindrich (Prentice-Hall). For an overview of mips assembly conventions,
|
|
see \(lqAppendix D: Assembly Language Programming\(rq in the same work.
|
|
.Pp
|
|
.Ss Assembler options
|
|
The mips configurations of GNU
|
|
.Li as
|
|
support these special options:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It -G Va num
|
|
This option sets the largest size of an object that can be referenced implicitly
|
|
with the
|
|
.Li gp
|
|
register. It is only accepted for targets that use ecoff format. The default
|
|
value is 8.
|
|
.Pp
|
|
.It -EB
|
|
.It -EL
|
|
Any mips configuration of
|
|
.Li as
|
|
can select big-endian or little-endian output at run time (unlike the other
|
|
GNU development tools, which must be configured for one or the other). Use
|
|
.Li -EB
|
|
to select big-endian output, and
|
|
.Li -EL
|
|
for little-endian.
|
|
.Pp
|
|
.It -KPIC
|
|
Generate SVR4-style PIC. This option tells the assembler to generate SVR4-style
|
|
position-independent macro expansions. It also tells the assembler to mark
|
|
the output file as PIC.
|
|
.Pp
|
|
.It -mvxworks-pic
|
|
Generate VxWorks PIC. This option tells the assembler to generate VxWorks-style
|
|
position-independent macro expansions.
|
|
.Pp
|
|
.It -mips1
|
|
.It -mips2
|
|
.It -mips3
|
|
.It -mips4
|
|
.It -mips5
|
|
.It -mips32
|
|
.It -mips32r2
|
|
.It -mips64
|
|
.It -mips64r2
|
|
Generate code for a particular MIPS Instruction Set Architecture level.
|
|
.Li -mips1
|
|
corresponds to the r2000 and r3000 processors,
|
|
.Li -mips2
|
|
to the r6000 processor,
|
|
.Li -mips3
|
|
to the r4000 processor, and
|
|
.Li -mips4
|
|
to the r8000 and r10000 processors.
|
|
.Li -mips5 ,
|
|
.Li -mips32 ,
|
|
.Li -mips32r2 ,
|
|
.Li -mips64 ,
|
|
and
|
|
.Li -mips64r2
|
|
correspond to generic MIPS V, MIPS32, MIPS32 Release 2, MIPS64, and MIPS64
|
|
Release 2 ISA processors, respectively. You can also switch instruction sets
|
|
during the assembly; see MIPS ISA, Directives to override the ISA level.
|
|
.Pp
|
|
.It -mgp32
|
|
.It -mfp32
|
|
Some macros have different expansions for 32-bit and 64-bit registers. The
|
|
register sizes are normally inferred from the ISA and ABI, but these flags
|
|
force a certain group of registers to be treated as 32 bits wide at all times.
|
|
.Li -mgp32
|
|
controls the size of general-purpose registers and
|
|
.Li -mfp32
|
|
controls the size of floating-point registers.
|
|
.Pp
|
|
The
|
|
.Li .set gp=32
|
|
and
|
|
.Li .set fp=32
|
|
directives allow the size of registers to be changed for parts of an object.
|
|
The default value is restored by
|
|
.Li .set gp=default
|
|
and
|
|
.Li .set fp=default .
|
|
.Pp
|
|
On some MIPS variants there is a 32-bit mode flag; when this flag is set,
|
|
64-bit instructions generate a trap. Also, some 32-bit OSes only save the
|
|
32-bit registers on a context switch, so it is essential never to use the
|
|
64-bit registers.
|
|
.Pp
|
|
.It -mgp64
|
|
.It -mfp64
|
|
Assume that 64-bit registers are available. This is provided in the interests
|
|
of symmetry with
|
|
.Li -mgp32
|
|
and
|
|
.Li -mfp32 .
|
|
.Pp
|
|
The
|
|
.Li .set gp=64
|
|
and
|
|
.Li .set fp=64
|
|
directives allow the size of registers to be changed for parts of an object.
|
|
The default value is restored by
|
|
.Li .set gp=default
|
|
and
|
|
.Li .set fp=default .
|
|
.Pp
|
|
.It -mips16
|
|
.It -no-mips16
|
|
Generate code for the MIPS 16 processor. This is equivalent to putting
|
|
.Li .set mips16
|
|
at the start of the assembly file.
|
|
.Li -no-mips16
|
|
turns off this option.
|
|
.Pp
|
|
.It -msmartmips
|
|
.It -mno-smartmips
|
|
Enables the SmartMIPS extensions to the MIPS32 instruction set, which provides
|
|
a number of new instructions which target smartcard and cryptographic applications.
|
|
This is equivalent to putting
|
|
.Li .set smartmips
|
|
at the start of the assembly file.
|
|
.Li -mno-smartmips
|
|
turns off this option.
|
|
.Pp
|
|
.It -mips3d
|
|
.It -no-mips3d
|
|
Generate code for the MIPS-3D Application Specific Extension. This tells the
|
|
assembler to accept MIPS-3D instructions.
|
|
.Li -no-mips3d
|
|
turns off this option.
|
|
.Pp
|
|
.It -mdmx
|
|
.It -no-mdmx
|
|
Generate code for the MDMX Application Specific Extension. This tells the
|
|
assembler to accept MDMX instructions.
|
|
.Li -no-mdmx
|
|
turns off this option.
|
|
.Pp
|
|
.It -mdsp
|
|
.It -mno-dsp
|
|
Generate code for the DSP Release 1 Application Specific Extension. This tells
|
|
the assembler to accept DSP Release 1 instructions.
|
|
.Li -mno-dsp
|
|
turns off this option.
|
|
.Pp
|
|
.It -mdspr2
|
|
.It -mno-dspr2
|
|
Generate code for the DSP Release 2 Application Specific Extension. This option
|
|
implies -mdsp. This tells the assembler to accept DSP Release 2 instructions.
|
|
.Li -mno-dspr2
|
|
turns off this option.
|
|
.Pp
|
|
.It -mmt
|
|
.It -mno-mt
|
|
Generate code for the MT Application Specific Extension. This tells the assembler
|
|
to accept MT instructions.
|
|
.Li -mno-mt
|
|
turns off this option.
|
|
.Pp
|
|
.It -mfix7000
|
|
.It -mno-fix7000
|
|
Cause nops to be inserted if the read of the destination register of an mfhi
|
|
or mflo instruction occurs in the following two instructions.
|
|
.Pp
|
|
.It -mfix-vr4120
|
|
.It -no-mfix-vr4120
|
|
Insert nops to work around certain VR4120 errata. This option is intended
|
|
to be used on GCC-generated code: it is not designed to catch all problems
|
|
in hand-written assembler code.
|
|
.Pp
|
|
.It -mfix-vr4130
|
|
.It -no-mfix-vr4130
|
|
Insert nops to work around the VR4130
|
|
.Li mflo
|
|
/
|
|
.Li mfhi
|
|
errata.
|
|
.Pp
|
|
.It -m4010
|
|
.It -no-m4010
|
|
Generate code for the LSI r4010 chip. This tells the assembler to accept the
|
|
r4010 specific instructions (
|
|
.Li addciu ,
|
|
.Li ffc ,
|
|
etc.), and to not schedule
|
|
.Li nop
|
|
instructions around accesses to the
|
|
.Li HI
|
|
and
|
|
.Li LO
|
|
registers.
|
|
.Li -no-m4010
|
|
turns off this option.
|
|
.Pp
|
|
.It -m4650
|
|
.It -no-m4650
|
|
Generate code for the MIPS r4650 chip. This tells the assembler to accept
|
|
the
|
|
.Li mad
|
|
and
|
|
.Li madu
|
|
instruction, and to not schedule
|
|
.Li nop
|
|
instructions around accesses to the
|
|
.Li HI
|
|
and
|
|
.Li LO
|
|
registers.
|
|
.Li -no-m4650
|
|
turns off this option.
|
|
.Pp
|
|
.It -m3900
|
|
.It -no-m3900
|
|
.It -m4100
|
|
.It -no-m4100
|
|
For each option
|
|
.Li -m Va nnnn ,
|
|
generate code for the MIPS r
|
|
.Va nnnn
|
|
chip. This tells the assembler to accept instructions specific to that chip,
|
|
and to schedule for that chip's hazards.
|
|
.Pp
|
|
.It -march= Va cpu
|
|
Generate code for a particular MIPS cpu. It is exactly equivalent to
|
|
.Li -m Va cpu ,
|
|
except that there are more value of
|
|
.Va cpu
|
|
understood. Valid
|
|
.Va cpu
|
|
value are:
|
|
.Pp
|
|
.Qo
|
|
2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, vr4181, 4300, 4400,
|
|
4600, 4650, 5000, rm5200, rm5230, rm5231, rm5261, rm5721, vr5400, vr5500,
|
|
6000, rm7000, 8000, rm9000, 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem,
|
|
4kep, 4ksd, m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf,
|
|
34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a
|
|
.Qc
|
|
.Pp
|
|
.It -mtune= Va cpu
|
|
Schedule and tune for a particular MIPS cpu. Valid
|
|
.Va cpu
|
|
values are identical to
|
|
.Li -march= Va cpu .
|
|
.Pp
|
|
.It -mabi= Va abi
|
|
Record which ABI the source code uses. The recognized arguments are:
|
|
.Li 32 ,
|
|
.Li n32 ,
|
|
.Li o64 ,
|
|
.Li 64
|
|
and
|
|
.Li eabi .
|
|
.Pp
|
|
.It -msym32
|
|
.It -mno-sym32
|
|
Equivalent to adding
|
|
.Li .set sym32
|
|
or
|
|
.Li .set nosym32
|
|
to the beginning of the assembler input.See Section
|
|
.Dq MIPS symbol sizes .
|
|
.Pp
|
|
.It -nocpp
|
|
This option is ignored. It is accepted for command-line compatibility with
|
|
other assemblers, which use it to turn off C style preprocessing. With GNU
|
|
.Li as ,
|
|
there is no need for
|
|
.Li -nocpp ,
|
|
because the GNU assembler itself never runs the C preprocessor.
|
|
.Pp
|
|
.It --construct-floats
|
|
.It --no-construct-floats
|
|
The
|
|
.Li --no-construct-floats
|
|
option disables the construction of double width floating point constants
|
|
by loading the two halves of the value into the two single width floating
|
|
point registers that make up the double width register. This feature is useful
|
|
if the processor support the FR bit in its status register, and this bit is
|
|
known (by the programmer) to be set. This bit prevents the aliasing of the
|
|
double width register by the single width registers.
|
|
.Pp
|
|
By default
|
|
.Li --construct-floats
|
|
is selected, allowing construction of these floating point constants.
|
|
.Pp
|
|
.It --trap
|
|
.It --no-break
|
|
.Li as
|
|
automatically macro expands certain division and multiplication instructions
|
|
to check for overflow and division by zero. This option causes
|
|
.Li as
|
|
to generate code to take a trap exception rather than a break exception when
|
|
an error is detected. The trap instructions are only supported at Instruction
|
|
Set Architecture level 2 and higher.
|
|
.Pp
|
|
.It --break
|
|
.It --no-trap
|
|
Generate code to take a break exception rather than a trap exception when
|
|
an error is detected. This is the default.
|
|
.Pp
|
|
.It -mpdr
|
|
.It -mno-pdr
|
|
Control generation of
|
|
.Li .pdr
|
|
sections. Off by default on IRIX, on elsewhere.
|
|
.Pp
|
|
.It -mshared
|
|
.It -mno-shared
|
|
When generating code using the Unix calling conventions (selected by
|
|
.Li -KPIC
|
|
or
|
|
.Li -mcall_shared ) ,
|
|
gas will normally generate code which can go into a shared library. The
|
|
.Li -mno-shared
|
|
option tells gas to generate code which uses the calling convention, but can
|
|
not go into a shared library. The resulting code is slightly more efficient.
|
|
This option only affects the handling of the
|
|
.Li .cpload
|
|
and
|
|
.Li .cpsetup
|
|
pseudo-ops.
|
|
.El
|
|
.Pp
|
|
.Ss MIPS ECOFF object code
|
|
Assembling for a mips ecoff target supports some additional sections besides
|
|
the usual
|
|
.Li .text ,
|
|
.Li .data
|
|
and
|
|
.Li .bss .
|
|
The additional sections are
|
|
.Li .rdata ,
|
|
used for read-only data,
|
|
.Li .sdata ,
|
|
used for small data, and
|
|
.Li .sbss ,
|
|
used for small common objects.
|
|
.Pp
|
|
When assembling for ecoff, the assembler uses the
|
|
.Li $gp
|
|
(
|
|
.Li $28 )
|
|
register to form the address of a \(lqsmall object\(rq. Any object in the
|
|
.Li .sdata
|
|
or
|
|
.Li .sbss
|
|
sections is considered \(lqsmall\(rq in this sense. For external objects, or for objects
|
|
in the
|
|
.Li .bss
|
|
section, you can use the
|
|
.Li gcc
|
|
.Li -G
|
|
option to control the size of objects addressed via
|
|
.Li $gp ;
|
|
the default value is 8, meaning that a reference to any object eight bytes
|
|
or smaller uses
|
|
.Li $gp .
|
|
Passing
|
|
.Li -G 0
|
|
to
|
|
.Li as
|
|
prevents it from using the
|
|
.Li $gp
|
|
register on the basis of object size (but the assembler uses
|
|
.Li $gp
|
|
for objects in
|
|
.Li .sdata
|
|
or
|
|
.Li sbss
|
|
in any case). The size of an object in the
|
|
.Li .bss
|
|
section is set by the
|
|
.Li .comm
|
|
or
|
|
.Li .lcomm
|
|
directive that defines it. The size of an external object may be set with
|
|
the
|
|
.Li .extern
|
|
directive. For example,
|
|
.Li .extern sym,4
|
|
declares that the object at
|
|
.Li sym
|
|
is 4 bytes in length, whie leaving
|
|
.Li sym
|
|
otherwise undefined.
|
|
.Pp
|
|
Using small ecoff objects requires linker support, and assumes that the
|
|
.Li $gp
|
|
register is correctly initialized (normally done automatically by the startup
|
|
code). mips ecoff assembly code must not modify the
|
|
.Li $gp
|
|
register.
|
|
.Pp
|
|
.Ss Directives for debugging information
|
|
mips ecoff
|
|
.Li as
|
|
supports several directives used for generating debugging information which
|
|
are not support by traditional mips assemblers. These are
|
|
.Li .def ,
|
|
.Li .endef ,
|
|
.Li .dim ,
|
|
.Li .file ,
|
|
.Li .scl ,
|
|
.Li .size ,
|
|
.Li .tag ,
|
|
.Li .type ,
|
|
.Li .val ,
|
|
.Li .stabd ,
|
|
.Li .stabn ,
|
|
and
|
|
.Li .stabs .
|
|
The debugging information generated by the three
|
|
.Li .stab
|
|
directives can only be read by gdb, not by traditional mips debuggers (this
|
|
enhancement is required to fully support C++ debugging). These directives
|
|
are primarily used by compilers, not assembly language programmers!
|
|
.Pp
|
|
.Ss Directives to override the size of symbols
|
|
The n64 ABI allows symbols to have any 64-bit value. Although this provides
|
|
a great deal of flexibility, it means that some macros have much longer expansions
|
|
than their 32-bit counterparts. For example, the non-PIC expansion of
|
|
.Li dla $4,sym
|
|
is usually:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
lui $4,%highest(sym)
|
|
lui $1,%hi(sym)
|
|
daddiu $4,$4,%higher(sym)
|
|
daddiu $1,$1,%lo(sym)
|
|
dsll32 $4,$4,0
|
|
daddu $4,$4,$1
|
|
.Ed
|
|
.Pp
|
|
whereas the 32-bit expansion is simply:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
lui $4,%hi(sym)
|
|
daddiu $4,$4,%lo(sym)
|
|
.Ed
|
|
.Pp
|
|
n64 code is sometimes constructed in such a way that all symbolic constants
|
|
are known to have 32-bit values, and in such cases, it's preferable to use
|
|
the 32-bit expansion instead of the 64-bit expansion.
|
|
.Pp
|
|
You can use the
|
|
.Li .set sym32
|
|
directive to tell the assembler that, from this point on, all expressions
|
|
of the form
|
|
.Li Va symbol
|
|
or
|
|
.Li Va symbol + Va offset
|
|
have 32-bit values. For example:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
\&.set sym32
|
|
dla $4,sym
|
|
lw $4,sym+16
|
|
sw $4,sym+0x8000($4)
|
|
.Ed
|
|
.Pp
|
|
will cause the assembler to treat
|
|
.Li sym ,
|
|
.Li sym+16
|
|
and
|
|
.Li sym+0x8000
|
|
as 32-bit values. The handling of non-symbolic addresses is not affected.
|
|
.Pp
|
|
The directive
|
|
.Li .set nosym32
|
|
ends a
|
|
.Li .set sym32
|
|
block and reverts to the normal behavior. It is also possible to change the
|
|
symbol size using the command-line options
|
|
.Op -msym32
|
|
and
|
|
.Op -mno-sym32 .
|
|
.Pp
|
|
These options and directives are always accepted, but at present, they have
|
|
no effect for anything other than n64.
|
|
.Pp
|
|
.Ss Directives to override the ISA level
|
|
GNU
|
|
.Li as
|
|
supports an additional directive to change the mips Instruction Set Architecture
|
|
level on the fly:
|
|
.Li .set mips Va n .
|
|
.Va n
|
|
should be a number from 0 to 5, or 32, 32r2, 64 or 64r2. The values other
|
|
than 0 make the assembler accept instructions for the corresponding isa level,
|
|
from that point on in the assembly.
|
|
.Li .set mips Va n
|
|
affects not only which instructions are permitted, but also how certain macros
|
|
are expanded.
|
|
.Li .set mips0
|
|
restores the isa level to its original level: either the level you selected
|
|
with command line options, or the default for your configuration. You can
|
|
use this feature to permit specific mips3 instructions while assembling in
|
|
32 bit mode. Use this directive with care!
|
|
.Pp
|
|
The
|
|
.Li .set arch= Va cpu
|
|
directive provides even finer control. It changes the effective CPU target
|
|
and allows the assembler to use instructions specific to a particular CPU.
|
|
All CPUs supported by the
|
|
.Li -march
|
|
command line option are also selectable by this directive. The original value
|
|
is restored by
|
|
.Li .set arch=default .
|
|
.Pp
|
|
The directive
|
|
.Li .set mips16
|
|
puts the assembler into MIPS 16 mode, in which it will assemble instructions
|
|
for the MIPS 16 processor. Use
|
|
.Li .set nomips16
|
|
to return to normal 32 bit mode.
|
|
.Pp
|
|
Traditional mips assemblers do not support this directive.
|
|
.Pp
|
|
.Ss Directives for extending MIPS 16 bit instructions
|
|
By default, MIPS 16 instructions are automatically extended to 32 bits when
|
|
necessary. The directive
|
|
.Li .set noautoextend
|
|
will turn this off. When
|
|
.Li .set noautoextend
|
|
is in effect, any 32 bit instruction must be explicitly extended with the
|
|
.Li .e
|
|
modifier (e.g.,
|
|
.Li li.e $4,1000 ) .
|
|
The directive
|
|
.Li .set autoextend
|
|
may be used to once again automatically extend instructions when necessary.
|
|
.Pp
|
|
This directive is only meaningful when in MIPS 16 mode. Traditional mips assemblers
|
|
do not support this directive.
|
|
.Pp
|
|
.Ss Directive to mark data as an instruction
|
|
The
|
|
.Li .insn
|
|
directive tells
|
|
.Li as
|
|
that the following data is actually instructions. This makes a difference
|
|
in MIPS 16 mode: when loading the address of a label which precedes instructions,
|
|
.Li as
|
|
automatically adds 1 to the value, so that jumping to the loaded address will
|
|
do the right thing.
|
|
.Pp
|
|
.Ss Directives to save and restore options
|
|
The directives
|
|
.Li .set push
|
|
and
|
|
.Li .set pop
|
|
may be used to save and restore the current settings for all the options which
|
|
are controlled by
|
|
.Li .set .
|
|
The
|
|
.Li .set push
|
|
directive saves the current settings on a stack. The
|
|
.Li .set pop
|
|
directive pops the stack and restores the settings.
|
|
.Pp
|
|
These directives can be useful inside an macro which must change an option
|
|
such as the ISA level or instruction reordering but does not want to change
|
|
the state of the code which invoked the macro.
|
|
.Pp
|
|
Traditional mips assemblers do not support these directives.
|
|
.Pp
|
|
.Ss Directives to control generation of MIPS ASE instructions
|
|
The directive
|
|
.Li .set mips3d
|
|
makes the assembler accept instructions from the MIPS-3D Application Specific
|
|
Extension from that point on in the assembly. The
|
|
.Li .set nomips3d
|
|
directive prevents MIPS-3D instructions from being accepted.
|
|
.Pp
|
|
The directive
|
|
.Li .set smartmips
|
|
makes the assembler accept instructions from the SmartMIPS Application Specific
|
|
Extension to the MIPS32 isa from that point on in the assembly. The
|
|
.Li .set nosmartmips
|
|
directive prevents SmartMIPS instructions from being accepted.
|
|
.Pp
|
|
The directive
|
|
.Li .set mdmx
|
|
makes the assembler accept instructions from the MDMX Application Specific
|
|
Extension from that point on in the assembly. The
|
|
.Li .set nomdmx
|
|
directive prevents MDMX instructions from being accepted.
|
|
.Pp
|
|
The directive
|
|
.Li .set dsp
|
|
makes the assembler accept instructions from the DSP Release 1 Application
|
|
Specific Extension from that point on in the assembly. The
|
|
.Li .set nodsp
|
|
directive prevents DSP Release 1 instructions from being accepted.
|
|
.Pp
|
|
The directive
|
|
.Li .set dspr2
|
|
makes the assembler accept instructions from the DSP Release 2 Application
|
|
Specific Extension from that point on in the assembly. This dirctive implies
|
|
.Li .set dsp .
|
|
The
|
|
.Li .set nodspr2
|
|
directive prevents DSP Release 2 instructions from being accepted.
|
|
.Pp
|
|
The directive
|
|
.Li .set mt
|
|
makes the assembler accept instructions from the MT Application Specific Extension
|
|
from that point on in the assembly. The
|
|
.Li .set nomt
|
|
directive prevents MT instructions from being accepted.
|
|
.Pp
|
|
Traditional mips assemblers do not support these directives.
|
|
.Pp
|
|
.Sh PowerPC Dependent Features
|
|
.Ss Options
|
|
The PowerPC chip family includes several successive levels, using the same
|
|
core instruction set, but including a few additional instructions at each
|
|
level. There are exceptions to this however. For details on what instructions
|
|
each variant supports, please see the chip's architecture reference manual.
|
|
.Pp
|
|
The following table lists all available PowerPC options.
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It -mpwrx | -mpwr2
|
|
Generate code for POWER/2 (RIOS2).
|
|
.Pp
|
|
.It -mpwr
|
|
Generate code for POWER (RIOS1)
|
|
.Pp
|
|
.It -m601
|
|
Generate code for PowerPC 601.
|
|
.Pp
|
|
.It -mppc, -mppc32, -m603, -m604
|
|
Generate code for PowerPC 603/604.
|
|
.Pp
|
|
.It -m403, -m405
|
|
Generate code for PowerPC 403/405.
|
|
.Pp
|
|
.It -m440
|
|
Generate code for PowerPC 440. BookE and some 405 instructions.
|
|
.Pp
|
|
.It -m7400, -m7410, -m7450, -m7455
|
|
Generate code for PowerPC 7400/7410/7450/7455.
|
|
.Pp
|
|
.It -mppc64, -m620
|
|
Generate code for PowerPC 620/625/630.
|
|
.Pp
|
|
.It -me500, -me500x2
|
|
Generate code for Motorola e500 core complex.
|
|
.Pp
|
|
.It -mspe
|
|
Generate code for Motorola SPE instructions.
|
|
.Pp
|
|
.It -mppc64bridge
|
|
Generate code for PowerPC 64, including bridge insns.
|
|
.Pp
|
|
.It -mbooke64
|
|
Generate code for 64-bit BookE.
|
|
.Pp
|
|
.It -mbooke, mbooke32
|
|
Generate code for 32-bit BookE.
|
|
.Pp
|
|
.It -me300
|
|
Generate code for PowerPC e300 family.
|
|
.Pp
|
|
.It -maltivec
|
|
Generate code for processors with AltiVec instructions.
|
|
.Pp
|
|
.It -mpower4
|
|
Generate code for Power4 architecture.
|
|
.Pp
|
|
.It -mpower5
|
|
Generate code for Power5 architecture.
|
|
.Pp
|
|
.It -mpower6
|
|
Generate code for Power6 architecture.
|
|
.Pp
|
|
.It -mcell
|
|
Generate code for Cell Broadband Engine architecture.
|
|
.Pp
|
|
.It -mcom
|
|
Generate code Power/PowerPC common instructions.
|
|
.Pp
|
|
.It -many
|
|
Generate code for any architecture (PWR/PWRX/PPC).
|
|
.Pp
|
|
.It -mregnames
|
|
Allow symbolic names for registers.
|
|
.Pp
|
|
.It -mno-regnames
|
|
Do not allow symbolic names for registers.
|
|
.Pp
|
|
.It -mrelocatable
|
|
Support for GCC's -mrelocatable option.
|
|
.Pp
|
|
.It -mrelocatable-lib
|
|
Support for GCC's -mrelocatable-lib option.
|
|
.Pp
|
|
.It -memb
|
|
Set PPC_EMB bit in ELF flags.
|
|
.Pp
|
|
.It -mlittle, -mlittle-endian
|
|
Generate code for a little endian machine.
|
|
.Pp
|
|
.It -mbig, -mbig-endian
|
|
Generate code for a big endian machine.
|
|
.Pp
|
|
.It -msolaris
|
|
Generate code for Solaris.
|
|
.Pp
|
|
.It -mno-solaris
|
|
Do not generate code for Solaris.
|
|
.El
|
|
.Pp
|
|
.Ss PowerPC Assembler Directives
|
|
A number of assembler directives are available for PowerPC. The following
|
|
table is far from complete.
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It .machine "string"
|
|
This directive allows you to change the machine for which code is generated.
|
|
.Li "string"
|
|
may be any of the -m cpu selection options (without the -m) enclosed in double
|
|
quotes,
|
|
.Li "push" ,
|
|
or
|
|
.Li "pop" .
|
|
.Li .machine "push"
|
|
saves the currently selected cpu, which may be restored with
|
|
.Li .machine "pop" .
|
|
.El
|
|
.Pp
|
|
.Sh SPARC Dependent Features
|
|
.Ss Options
|
|
The SPARC chip family includes several successive levels, using the same core
|
|
instruction set, but including a few additional instructions at each level.
|
|
There are exceptions to this however. For details on what instructions each
|
|
variant supports, please see the chip's architecture reference manual.
|
|
.Pp
|
|
By default,
|
|
.Li as
|
|
assumes the core instruction set (SPARC v6), but \(lqbumps\(rq the architecture level
|
|
as needed: it switches to successively higher architectures as it encounters
|
|
instructions that only exist in the higher levels.
|
|
.Pp
|
|
If not configured for SPARC v9 (
|
|
.Li sparc64-*-* )
|
|
GAS will not bump passed sparclite by default, an option must be passed to
|
|
enable the v9 instructions.
|
|
.Pp
|
|
GAS treats sparclite as being compatible with v8, unless an architecture is
|
|
explicitly requested. SPARC v9 is always incompatible with sparclite.
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
|
|
.It -Av8plus | -Av8plusa | -Av9 | -Av9a
|
|
Use one of the
|
|
.Li -A
|
|
options to select one of the SPARC architectures explicitly. If you select
|
|
an architecture explicitly,
|
|
.Li as
|
|
reports a fatal error if it encounters an instruction or feature requiring
|
|
an incompatible or higher level.
|
|
.Pp
|
|
.Li -Av8plus
|
|
and
|
|
.Li -Av8plusa
|
|
select a 32 bit environment.
|
|
.Pp
|
|
.Li -Av9
|
|
and
|
|
.Li -Av9a
|
|
select a 64 bit environment and are not available unless GAS is explicitly
|
|
configured with 64 bit environment support.
|
|
.Pp
|
|
.Li -Av8plusa
|
|
and
|
|
.Li -Av9a
|
|
enable the SPARC V9 instruction set with UltraSPARC extensions.
|
|
.Pp
|
|
.It -xarch=v8plus | -xarch=v8plusa
|
|
For compatibility with the Solaris v9 assembler. These options are equivalent
|
|
to -Av8plus and -Av8plusa, respectively.
|
|
.Pp
|
|
.It -bump
|
|
Warn whenever it is necessary to switch to another level. If an architecture
|
|
level is explicitly requested, GAS will not issue warnings until that level
|
|
is reached, and will then bump the level as required (except between incompatible
|
|
levels).
|
|
.Pp
|
|
.It -32 | -64
|
|
Select the word size, either 32 bits or 64 bits. These options are only available
|
|
with the ELF object file format, and require that the necessary BFD support
|
|
has been included.
|
|
.El
|
|
.Pp
|
|
.Ss Enforcing aligned data
|
|
SPARC GAS normally permits data to be misaligned. For example, it permits
|
|
the
|
|
.Li .long
|
|
pseudo-op to be used on a byte boundary. However, the native SunOS and Solaris
|
|
assemblers issue an error when they see misaligned data.
|
|
.Pp
|
|
You can use the
|
|
.Li --enforce-aligned-data
|
|
option to make SPARC GAS also issue an error about misaligned data, just as
|
|
the SunOS and Solaris assemblers do.
|
|
.Pp
|
|
The
|
|
.Li --enforce-aligned-data
|
|
option is not the default because gcc issues misaligned data pseudo-ops when
|
|
it initializes certain packed data structures (structures defined using the
|
|
.Li packed
|
|
attribute). You may have to assemble with GAS in order to initialize packed
|
|
data structures in your own code.
|
|
.Pp
|
|
.Ss Floating Point
|
|
The Sparc uses ieee floating-point numbers.
|
|
.Pp
|
|
.Ss Sparc Machine Directives
|
|
The Sparc version of
|
|
.Li as
|
|
supports the following additional machine directives:
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It .align
|
|
This must be followed by the desired alignment in bytes.
|
|
.Pp
|
|
.It .common
|
|
This must be followed by a symbol name, a positive number, and
|
|
.Li "bss" .
|
|
This behaves somewhat like
|
|
.Li .comm ,
|
|
but the syntax is different.
|
|
.Pp
|
|
.It .half
|
|
This is functionally identical to
|
|
.Li .short .
|
|
.Pp
|
|
.It .nword
|
|
On the Sparc, the
|
|
.Li .nword
|
|
directive produces native word sized value, ie. if assembling with -32 it
|
|
is equivalent to
|
|
.Li .word ,
|
|
if assembling with -64 it is equivalent to
|
|
.Li .xword .
|
|
.Pp
|
|
.It .proc
|
|
This directive is ignored. Any text following it on the same line is also
|
|
ignored.
|
|
.Pp
|
|
.It .register
|
|
This directive declares use of a global application or system register. It
|
|
must be followed by a register name %g2, %g3, %g6 or %g7, comma and the symbol
|
|
name for that register. If symbol name is
|
|
.Li #scratch ,
|
|
it is a scratch register, if it is
|
|
.Li #ignore ,
|
|
it just suppresses any errors about using undeclared global register, but
|
|
does not emit any information about it into the object file. This can be useful
|
|
e.g. if you save the register before use and restore it after.
|
|
.Pp
|
|
.It .reserve
|
|
This must be followed by a symbol name, a positive number, and
|
|
.Li "bss" .
|
|
This behaves somewhat like
|
|
.Li .lcomm ,
|
|
but the syntax is different.
|
|
.Pp
|
|
.It .seg
|
|
This must be followed by
|
|
.Li "text" ,
|
|
.Li "data" ,
|
|
or
|
|
.Li "data1" .
|
|
It behaves like
|
|
.Li .text ,
|
|
.Li .data ,
|
|
or
|
|
.Li .data 1 .
|
|
.Pp
|
|
.It .skip
|
|
This is functionally identical to the
|
|
.Li .space
|
|
directive.
|
|
.Pp
|
|
.It .word
|
|
On the Sparc, the
|
|
.Li .word
|
|
directive produces 32 bit values, instead of the 16 bit values it produces
|
|
on many other machines.
|
|
.Pp
|
|
.It .xword
|
|
On the Sparc V9 processor, the
|
|
.Li .xword
|
|
directive produces 64 bit values.
|
|
.El
|
|
.Pp
|
|
.Sh Reporting Bugs
|
|
Your bug reports play an essential role in making
|
|
.Xr as
|
|
reliable.
|
|
.Pp
|
|
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
|
|
.Xr as
|
|
work better. Bug reports are your contribution to the maintenance of
|
|
.Xr as .
|
|
.Pp
|
|
In order for a bug report to serve its purpose, you must include the information
|
|
that enables us to fix the bug.
|
|
.Pp
|
|
.Ss Have You Found a Bug?
|
|
If you are not sure whether you have found a bug, here are some guidelines:
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
If the assembler gets a fatal signal, for any input whatever, that is a
|
|
.Xr as
|
|
bug. Reliable assemblers never crash.
|
|
.Pp
|
|
.It
|
|
If
|
|
.Xr as
|
|
produces an error message for valid input, that is a bug.
|
|
.Pp
|
|
.It
|
|
If
|
|
.Xr as
|
|
does not produce an error message for invalid input, that is a bug. However,
|
|
you should note that your idea of \(lqinvalid input\(rq might be our idea of \(lqan extension\(rq
|
|
or \(lqsupport for traditional practice\(rq.
|
|
.Pp
|
|
.It
|
|
If you are an experienced user of assemblers, your suggestions for improvement
|
|
of
|
|
.Xr as
|
|
are welcome in any case.
|
|
.El
|
|
.Pp
|
|
.Ss How to Report Bugs
|
|
A number of companies and individuals offer support for GNU products. If you
|
|
obtained
|
|
.Xr as
|
|
from a support organization, we recommend you contact that organization first.
|
|
.Pp
|
|
You can find contact information for many support companies and individuals
|
|
in the file
|
|
.Pa etc/SERVICE
|
|
in the GNU Emacs distribution.
|
|
.Pp
|
|
The fundamental principle of reporting bugs usefully is this:
|
|
.Sy report all the facts .
|
|
If you are not sure whether to state a fact or leave it out, state it!
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq
|
|
This cannot help us fix a bug, so it is basically useless. We respond by asking
|
|
for enough details to enable us to investigate. You might as well expedite
|
|
matters by sending them to begin with.
|
|
.Pp
|
|
To enable us to fix the bug, you should include all these things:
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
The version of
|
|
.Xr as .
|
|
.Xr as
|
|
announces it if you start it with the
|
|
.Li --version
|
|
argument.
|
|
.Pp
|
|
Without this, we will not know whether there is any point in looking for the
|
|
bug in the current version of
|
|
.Xr as .
|
|
.Pp
|
|
.It
|
|
Any patches you may have applied to the
|
|
.Xr as
|
|
source.
|
|
.Pp
|
|
.It
|
|
The type of machine you are using, and the operating system name and version
|
|
number.
|
|
.Pp
|
|
.It
|
|
What compiler (and its version) was used to compile
|
|
.Xr as
|
|
---e.g. \(lq
|
|
.Li gcc-2.7
|
|
\(rq\&.
|
|
.Pp
|
|
.It
|
|
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.
|
|
.Pp
|
|
If we were to try to guess the arguments, we would probably guess wrong and
|
|
then we might not encounter the bug.
|
|
.Pp
|
|
.It
|
|
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
|
|
.Li -S
|
|
option. If you are using
|
|
.Li gcc ,
|
|
use the options
|
|
.Li -v --save-temps ;
|
|
this will save the assembler source in a file with an extension of
|
|
.Pa .s ,
|
|
and also show you exactly how
|
|
.Xr as
|
|
is being run.
|
|
.Pp
|
|
.It
|
|
A description of what behavior you observe that you believe is incorrect.
|
|
For example, \(lqIt gets a fatal signal.\(rq
|
|
.Pp
|
|
Of course, if the bug is that
|
|
.Xr 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.
|
|
.Pp
|
|
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
|
|
.Xr as
|
|
is out of sync, 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.
|
|
.Pp
|
|
.It
|
|
If you wish to suggest changes to the
|
|
.Xr as
|
|
source, send us context diffs, as generated by
|
|
.Li diff
|
|
with the
|
|
.Li -u ,
|
|
.Li -c ,
|
|
or
|
|
.Li -p
|
|
option. Always send diffs from the old file to the new file. If you even discuss
|
|
something in the
|
|
.Xr as
|
|
source, refer to it by context, not by line number.
|
|
.Pp
|
|
The line numbers in our development sources will not match those in your sources.
|
|
Your line numbers would convey no useful information to us.
|
|
.El
|
|
.Pp
|
|
Here are some things that are not necessary:
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
A description of the envelope of the bug.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
Of course, if you can find a simpler example to report
|
|
.Em 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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.It
|
|
A patch for the bug.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
Sometimes with a program as complicated as
|
|
.Xr 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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.It
|
|
A guess about what the bug is or what it depends on.
|
|
.Pp
|
|
Such guesses are usually wrong. Even we cannot guess right about such things
|
|
without first using the debugger to find the facts.
|
|
.El
|
|
.Pp
|
|
.Sh Acknowledgements
|
|
If you have contributed to GAS 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 the maintainer is Ken Raeburn (email
|
|
address
|
|
.Li raeburn@cyGNUs.com ) .
|
|
.Pp
|
|
Dean Elsner wrote the original GNU assembler for the VAX.
|
|
.Pp
|
|
Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
|
|
information and the 68k series machines, most of the preprocessing pass, and
|
|
extensive changes in
|
|
.Pa messages.c ,
|
|
.Pa input-file.c ,
|
|
.Pa write.c .
|
|
.Pp
|
|
K. Richard Pixley maintained GAS for a while, adding various enhancements
|
|
and many bug fixes, including merging support for several processors, breaking
|
|
GAS up to handle multiple object file format back ends (including heavy rewrite,
|
|
testing, an integration of the coff and b.out back ends), adding configuration
|
|
including heavy testing and verification of cross assemblers and file splits
|
|
and renaming, converted GAS to strictly ANSI C including full prototypes,
|
|
added support for m680[34]0 and cpu32, did considerable work on i960 including
|
|
a COFF port (including considerable amounts of reverse engineering), a SPARC
|
|
opcode file rewrite, DECstation, rs6000, and hp300hpux host ports, updated
|
|
\(lqknow\(rq assertions and made them work, much other reorganization, cleanup, and
|
|
lint.
|
|
.Pp
|
|
Ken Raeburn wrote the high-level BFD interface code to replace most of the
|
|
code in format-specific I/O modules.
|
|
.Pp
|
|
The original VMS support was contributed by David L. Kashtan. Eric Youngdale
|
|
has done much work with it since.
|
|
.Pp
|
|
The Intel 80386 machine description was written by Eliot Dresselhaus.
|
|
.Pp
|
|
Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
|
|
.Pp
|
|
The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
|
|
University and Torbjorn Granlund of the Swedish Institute of Computer Science.
|
|
.Pp
|
|
Keith Knowles at the Open Software Foundation wrote the original MIPS back
|
|
end (
|
|
.Pa tc-mips.c ,
|
|
.Pa tc-mips.h ) ,
|
|
and contributed Rose format support (which hasn't been merged in yet). Ralph
|
|
Campbell worked with the MIPS code to support a.out format.
|
|
.Pp
|
|
Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, tc-h8300),
|
|
and IEEE 695 object file format (obj-ieee), was written by Steve Chamberlain
|
|
of CyGNUs Support. Steve also modified the COFF back end to use BFD for some
|
|
low-level operations, for use with the H8/300 and AMD 29k targets.
|
|
.Pp
|
|
John Gilmore built the AMD 29000 support, added
|
|
.Li .include
|
|
support, and simplified the configuration of which versions accept which directives.
|
|
He updated the 68k machine description so that Motorola's opcodes always produced
|
|
fixed-size instructions (e.g.,
|
|
.Li jsr ) ,
|
|
while synthetic instructions remained shrinkable (
|
|
.Li jbsr ) .
|
|
John fixed many bugs, including true tested cross-compilation support, and
|
|
one bug in relaxation that took a week and required the proverbial one-bit
|
|
fix.
|
|
.Pp
|
|
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, wrote the initial RS/6000
|
|
and PowerPC assembler, and made a few other minor patches.
|
|
.Pp
|
|
Steve Chamberlain made GAS able to generate listings.
|
|
.Pp
|
|
Hewlett-Packard contributed support for the HP9000/300.
|
|
.Pp
|
|
Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
|
|
along with a fairly extensive HPPA testsuite (for both SOM and ELF object
|
|
formats). This work was supported by both the Center for Software Science
|
|
at the University of Utah and CyGNUs Support.
|
|
.Pp
|
|
Support for ELF format files has been worked on by Mark Eichin of CyGNUs Support
|
|
(original, incomplete implementation for SPARC), Pete Hoogenboom and Jeff
|
|
Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
|
|
Software Foundation (i386 mainly), and Ken Raeburn of CyGNUs Support (sparc,
|
|
and some initial 64-bit support).
|
|
.Pp
|
|
Linas Vepstas added GAS support for the ESA/390 \(lqIBM 370\(rq architecture.
|
|
.Pp
|
|
Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and
|
|
BFD support for openVMS/Alpha.
|
|
.Pp
|
|
Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic*
|
|
flavors.
|
|
.Pp
|
|
David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica,
|
|
Inc. added support for Xtensa processors.
|
|
.Pp
|
|
Several engineers at CyGNUs Support have also provided many small bug fixes
|
|
and configuration enhancements.
|
|
.Pp
|
|
Many others have contributed large or small bugfixes and enhancements. If
|
|
you have contributed significant work and are not mentioned on this list,
|
|
and want to be, let us know. Some of the history has been lost; we are not
|
|
intentionally leaving anyone out.
|
|
.Pp
|
|
.Sh GNU Free Documentation License
|
|
.Bd -filled -offset indent
|
|
Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street,
|
|
Fifth Floor, Boston, MA 02110-1301 USA
|
|
.Pp
|
|
Everyone is permitted to copy and distribute verbatim copies of this license
|
|
document, but changing it is not allowed.
|
|
.Ed
|
|
.Pp
|
|
.Bl -enum
|
|
.It
|
|
PREAMBLE
|
|
.Pp
|
|
The purpose of this License is to make a manual, textbook, or other written
|
|
document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom
|
|
to copy and redistribute it, with or without modifying it, either commercially
|
|
or noncommercially. Secondarily, this License preserves for the author and
|
|
publisher a way to get credit for their work, while not being considered responsible
|
|
for modifications made by others.
|
|
.Pp
|
|
This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the
|
|
document must themselves be free in the same sense. It complements the GNU
|
|
General Public License, which is a copyleft license designed for free software.
|
|
.Pp
|
|
We have designed this License in order to use it for manuals for free software,
|
|
because free software needs free documentation: a free program should come
|
|
with manuals providing the same freedoms that the software does. But this
|
|
License is not limited to software manuals; it can be used for any textual
|
|
work, regardless of subject matter or whether it is published as a printed
|
|
book. We recommend this License principally for works whose purpose is instruction
|
|
or reference.
|
|
.Pp
|
|
.It
|
|
APPLICABILITY AND DEFINITIONS
|
|
.Pp
|
|
This License applies to any manual or other work that contains a notice placed
|
|
by the copyright holder saying it can be distributed under the terms of this
|
|
License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member
|
|
of the public is a licensee, and is addressed as \(lqyou.\(rq
|
|
.Pp
|
|
A \(lqModified Version\(rq of the Document means any work containing the Document
|
|
or a portion of it, either copied verbatim, or with modifications and/or translated
|
|
into another language.
|
|
.Pp
|
|
A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document
|
|
that deals exclusively with the relationship of the publishers or authors
|
|
of the Document to the Document's overall subject (or to related matters)
|
|
and contains nothing that could fall directly within that overall subject.
|
|
(For example, if the Document is in part a textbook of mathematics, a Secondary
|
|
Section may not explain any mathematics.) The relationship could be a matter
|
|
of historical connection with the subject or with related matters, or of legal,
|
|
commercial, philosophical, ethical or political position regarding them.
|
|
.Pp
|
|
The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated,
|
|
as being those of Invariant Sections, in the notice that says that the Document
|
|
is released under this License.
|
|
.Pp
|
|
The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover
|
|
Texts or Back-Cover Texts, in the notice that says that the Document is released
|
|
under this License.
|
|
.Pp
|
|
A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented
|
|
in a format whose specification is available to the general public, whose
|
|
contents can be viewed and edited directly and straightforwardly with generic
|
|
text editors or (for images composed of pixels) generic paint programs or
|
|
(for drawings) some widely available drawing editor, and that is suitable
|
|
for input to text formatters or for automatic translation to a variety of
|
|
formats suitable for input to text formatters. A copy made in an otherwise
|
|
Transparent file format whose markup has been designed to thwart or discourage
|
|
subsequent modification by readers is not Transparent. A copy that is not
|
|
\(lqTransparent\(rq is called \(lqOpaque.\(rq
|
|
.Pp
|
|
Examples of suitable formats for Transparent copies include plain ASCII without
|
|
markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
|
|
available DTD, and standard-conforming simple HTML designed for human modification.
|
|
Opaque formats include PostScript, PDF, proprietary formats that can be read
|
|
and edited only by proprietary word processors, SGML or XML for which the
|
|
DTD and/or processing tools are not generally available, and the machine-generated
|
|
HTML produced by some word processors for output purposes only.
|
|
.Pp
|
|
The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such
|
|
following pages as are needed to hold, legibly, the material this License
|
|
requires to appear in the title page. For works in formats which do not have
|
|
any title page as such, \(lqTitle Page\(rq means the text near the most prominent
|
|
appearance of the work's title, preceding the beginning of the body of the
|
|
text.
|
|
.Pp
|
|
.It
|
|
VERBATIM COPYING
|
|
.Pp
|
|
You may copy and distribute the Document in any medium, either commercially
|
|
or noncommercially, provided that this License, the copyright notices, and
|
|
the license notice saying this License applies to the Document are reproduced
|
|
in all copies, and that you add no other conditions whatsoever to those of
|
|
this License. You may not use technical measures to obstruct or control the
|
|
reading or further copying of the copies you make or distribute. However,
|
|
you may accept compensation in exchange for copies. If you distribute a large
|
|
enough number of copies you must also follow the conditions in section 3.
|
|
.Pp
|
|
You may also lend copies, under the same conditions stated above, and you
|
|
may publicly display copies.
|
|
.Pp
|
|
.It
|
|
COPYING IN QUANTITY
|
|
.Pp
|
|
If you publish printed copies of the Document numbering more than 100, and
|
|
the Document's license notice requires Cover Texts, you must enclose the copies
|
|
in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover
|
|
Texts on the front cover, and Back-Cover Texts on the back cover. Both covers
|
|
must also clearly and legibly identify you as the publisher of these copies.
|
|
The front cover must present the full title with all words of the title equally
|
|
prominent and visible. You may add other material on the covers in addition.
|
|
Copying with changes limited to the covers, as long as they preserve the title
|
|
of the Document and satisfy these conditions, can be treated as verbatim copying
|
|
in other respects.
|
|
.Pp
|
|
If the required texts for either cover are too voluminous to fit legibly,
|
|
you should put the first ones listed (as many as fit reasonably) on the actual
|
|
cover, and continue the rest onto adjacent pages.
|
|
.Pp
|
|
If you publish or distribute Opaque copies of the Document numbering more
|
|
than 100, you must either include a machine-readable Transparent copy along
|
|
with each Opaque copy, or state in or with each Opaque copy a publicly-accessible
|
|
computer-network location containing a complete Transparent copy of the Document,
|
|
free of added material, which the general network-using public has access
|
|
to download anonymously at no charge using public-standard network protocols.
|
|
If you use the latter option, you must take reasonably prudent steps, when
|
|
you begin distribution of Opaque copies in quantity, to ensure that this Transparent
|
|
copy will remain thus accessible at the stated location until at least one
|
|
year after the last time you distribute an Opaque copy (directly or through
|
|
your agents or retailers) of that edition to the public.
|
|
.Pp
|
|
It is requested, but not required, that you contact the authors of the Document
|
|
well before redistributing any large number of copies, to give them a chance
|
|
to provide you with an updated version of the Document.
|
|
.Pp
|
|
.It
|
|
MODIFICATIONS
|
|
.Pp
|
|
You may copy and distribute a Modified Version of the Document under the conditions
|
|
of sections 2 and 3 above, provided that you release the Modified Version
|
|
under precisely this License, with the Modified Version filling the role of
|
|
the Document, thus licensing distribution and modification of the Modified
|
|
Version to whoever possesses a copy of it. In addition, you must do these
|
|
things in the Modified Version:
|
|
.Pp
|
|
A. Use in the Title Page (and on the covers, if any) a title distinct from
|
|
that of the Document, and from those of previous versions (which should, if
|
|
there were any, be listed in the History section of the Document). You may
|
|
use the same title as a previous version if the original publisher of that
|
|
version gives permission. B. List on the Title Page, as authors, one or more
|
|
persons or entities responsible for authorship of the modifications in the
|
|
Modified Version, together with at least five of the principal authors of
|
|
the Document (all of its principal authors, if it has less than five). C.
|
|
State on the Title page the name of the publisher of the Modified Version,
|
|
as the publisher. D. Preserve all the copyright notices of the Document.
|
|
E. Add an appropriate copyright notice for your modifications adjacent to
|
|
the other copyright notices. F. Include, immediately after the copyright
|
|
notices, a license notice giving the public permission to use the Modified
|
|
Version under the terms of this License, in the form shown in the Addendum
|
|
below. G. Preserve in that license notice the full lists of Invariant Sections
|
|
and required Cover Texts given in the Document's license notice. H. Include
|
|
an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq,
|
|
and its title, and add to it an item stating at least the title, year, new
|
|
authors, and publisher of the Modified Version as given on the Title Page.
|
|
If there is no section entitled \(lqHistory\(rq in the Document, create one stating
|
|
the title, year, authors, and publisher of the Document as given on its Title
|
|
Page, then add an item describing the Modified Version as stated in the previous
|
|
sentence. J. Preserve the network location, if any, given in the Document
|
|
for public access to a Transparent copy of the Document, and likewise the
|
|
network locations given in the Document for previous versions it was based
|
|
on. These may be placed in the \(lqHistory\(rq section. You may omit a network location
|
|
for a work that was published at least four years before the Document itself,
|
|
or if the original publisher of the version it refers to gives permission.
|
|
K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's
|
|
title, and preserve in the section all the substance and tone of each of the
|
|
contributor acknowledgements and/or dedications given therein. L. Preserve
|
|
all the Invariant Sections of the Document, unaltered in their text and in
|
|
their titles. Section numbers or the equivalent are not considered part of
|
|
the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section
|
|
may not be included in the Modified Version. N. Do not retitle any existing
|
|
section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section.
|
|
.Pp
|
|
If the Modified Version includes new front-matter sections or appendices that
|
|
qualify as Secondary Sections and contain no material copied from the Document,
|
|
you may at your option designate some or all of these sections as invariant.
|
|
To do this, add their titles to the list of Invariant Sections in the Modified
|
|
Version's license notice. These titles must be distinct from any other section
|
|
titles.
|
|
.Pp
|
|
You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing
|
|
but endorsements of your Modified Version by various parties--for example,
|
|
statements of peer review or that the text has been approved by an organization
|
|
as the authoritative definition of a standard.
|
|
.Pp
|
|
You may add a passage of up to five words as a Front-Cover Text, and a passage
|
|
of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
|
|
in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover
|
|
Text may be added by (or through arrangements made by) any one entity. If
|
|
the Document already includes a cover text for the same cover, previously
|
|
added by you or by arrangement made by the same entity you are acting on behalf
|
|
of, you may not add another; but you may replace the old one, on explicit
|
|
permission from the previous publisher that added the old one.
|
|
.Pp
|
|
The author(s) and publisher(s) of the Document do not by this License give
|
|
permission to use their names for publicity for or to assert or imply endorsement
|
|
of any Modified Version.
|
|
.Pp
|
|
.It
|
|
COMBINING DOCUMENTS
|
|
.Pp
|
|
You may combine the Document with other documents released under this License,
|
|
under the terms defined in section 4 above for modified versions, provided
|
|
that you include in the combination all of the Invariant Sections of all of
|
|
the original documents, unmodified, and list them all as Invariant Sections
|
|
of your combined work in its license notice.
|
|
.Pp
|
|
The combined work need only contain one copy of this License, and multiple
|
|
identical Invariant Sections may be replaced with a single copy. If there
|
|
are multiple Invariant Sections with the same name but different contents,
|
|
make the title of each such section unique by adding at the end of it, in
|
|
parentheses, the name of the original author or publisher of that section
|
|
if known, or else a unique number. Make the same adjustment to the section
|
|
titles in the list of Invariant Sections in the license notice of the combined
|
|
work.
|
|
.Pp
|
|
In the combination, you must combine any sections entitled \(lqHistory\(rq in the
|
|
various original documents, forming one section entitled \(lqHistory\(rq; likewise
|
|
combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled
|
|
\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq
|
|
.Pp
|
|
.It
|
|
COLLECTIONS OF DOCUMENTS
|
|
.Pp
|
|
You may make a collection consisting of the Document and other documents released
|
|
under this License, and replace the individual copies of this License in the
|
|
various documents with a single copy that is included in the collection, provided
|
|
that you follow the rules of this License for verbatim copying of each of
|
|
the documents in all other respects.
|
|
.Pp
|
|
You may extract a single document from such a collection, and distribute it
|
|
individually under this License, provided you insert a copy of this License
|
|
into the extracted document, and follow this License in all other respects
|
|
regarding verbatim copying of that document.
|
|
.Pp
|
|
.It
|
|
AGGREGATION WITH INDEPENDENT WORKS
|
|
.Pp
|
|
A compilation of the Document or its derivatives with other separate and independent
|
|
documents or works, in or on a volume of a storage or distribution medium,
|
|
does not as a whole count as a Modified Version of the Document, provided
|
|
no compilation copyright is claimed for the compilation. Such a compilation
|
|
is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained
|
|
works thus compiled with the Document, on account of their being thus compiled,
|
|
if they are not themselves derivative works of the Document.
|
|
.Pp
|
|
If the Cover Text requirement of section 3 is applicable to these copies of
|
|
the Document, then if the Document is less than one quarter of the entire
|
|
aggregate, the Document's Cover Texts may be placed on covers that surround
|
|
only the Document within the aggregate. Otherwise they must appear on covers
|
|
around the whole aggregate.
|
|
.Pp
|
|
.It
|
|
TRANSLATION
|
|
.Pp
|
|
Translation is considered a kind of modification, so you may distribute translations
|
|
of the Document under the terms of section 4. Replacing Invariant Sections
|
|
with translations requires special permission from their copyright holders,
|
|
but you may include translations of some or all Invariant Sections in addition
|
|
to the original versions of these Invariant Sections. You may include a translation
|
|
of this License provided that you also include the original English version
|
|
of this License. In case of a disagreement between the translation and the
|
|
original English version of this License, the original English version will
|
|
prevail.
|
|
.Pp
|
|
.It
|
|
TERMINATION
|
|
.Pp
|
|
You may not copy, modify, sublicense, or distribute the Document except as
|
|
expressly provided for under this License. Any other attempt to copy, modify,
|
|
sublicense or distribute the Document is void, and will automatically terminate
|
|
your rights under this License. However, parties who have received copies,
|
|
or rights, from you under this License will not have their licenses terminated
|
|
so long as such parties remain in full compliance.
|
|
.Pp
|
|
.It
|
|
FUTURE REVISIONS OF THIS LICENSE
|
|
.Pp
|
|
The Free Software Foundation may publish new, revised versions of the GNU
|
|
Free Documentation License from time to time. Such new versions will be similar
|
|
in spirit to the present version, but may differ in detail to address new
|
|
problems or concerns. See http://www.gnu.org/copyleft/.
|
|
.Pp
|
|
Each version of the License is given a distinguishing version number. If the
|
|
Document specifies that a particular numbered version of this License \(lqor any
|
|
later version\(rq applies to it, you have the option of following the terms and
|
|
conditions either of that specified version or of any later version that has
|
|
been published (not as a draft) by the Free Software Foundation. If the Document
|
|
does not specify a version number of this License, you may choose any version
|
|
ever published (not as a draft) by the Free Software Foundation.
|
|
.Pp
|
|
.El
|
|
.Ss ADDENDUM: How to use this License for your documents
|
|
To use this License in a document you have written, include a copy of the
|
|
License in the document and put the following copyright and license notices
|
|
just after the title page:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
|
|
Copyright (C) year your name.
|
|
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 the Invariant Sections being list their titles, with the
|
|
Front-Cover Texts being list, and with the Back-Cover Texts being list.
|
|
A copy of the license is included in the section entitled "GNU
|
|
Free Documentation License."
|
|
|
|
.Ed
|
|
.Pp
|
|
If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead
|
|
of saying which ones are invariant. If you have no Front-Cover Texts, write
|
|
\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being
|
|
.Va list
|
|
\(rq; likewise for Back-Cover Texts.
|
|
.Pp
|
|
If your document contains nontrivial examples of program code, we recommend
|
|
releasing these examples in parallel under your choice of free software license,
|
|
such as the GNU General Public License, to permit their use in free software.
|
|
.Pp
|
|
.Sh AS Index
|