diff options
Diffstat (limited to 'contrib/binutils/gas/doc/as.7')
| -rw-r--r-- | contrib/binutils/gas/doc/as.7 | 8368 |
1 files changed, 8368 insertions, 0 deletions
diff --git a/contrib/binutils/gas/doc/as.7 b/contrib/binutils/gas/doc/as.7 new file mode 100644 index 000000000000..4d335576d060 --- /dev/null +++ b/contrib/binutils/gas/doc/as.7 @@ -0,0 +1,8368 @@ +.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 |