_if__(_I80386__) _fi__(_I80386__) _if__(_A29K__) _fi__(_A29K__) _if__(_I960__) _fi__(_I960__) _if__(_H8__) _fi__(_H8__) _if__(_M680X0__) _fi__(_M680X0__) _if__(_Z8000__) _fi__(_Z8000__) _if__(_SPARC__) _fi__(_SPARC__) _if__(_VAX__) _fi__(_VAX__) _if__(_ALL_ARCH__) _fi__(_ALL_ARCH__)

_if__(_AOUT__) _fi__(_AOUT__) _if__(_BOUT__) _fi__(_BOUT__) _if__(_COFF__) _fi__(_COFF__) _if__(_ELF__) _fi__(_ELF__)

_if__(_GENERIC__) _fi__(_GENERIC__) _if__(_INTERNALS__) _fi__(_INTERNALS__) _if__(_DIFFTABKLUG__) _fi__(_DIFFTABKLUG__) _if__(_W32__) _fi__(_W32__) _if__(_W16__) _fi__(_W16__) _if__(_IEEEFLOAT__) _fi__(_IEEEFLOAT__)

     START-INFO-DIR-ENTRY
     * As: (as).                     The GNU assembler.
     END-INFO-DIR-ENTRY

_if__(0)

NOTE: this manual is marked up for preprocessing with a collection of m4 macros called "pretex.m4".

THIS IS THE FULL SOURCE.  The full source needs to be run through m4 before either tex- or info- formatting: for example, m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo will produce (assuming your path finds either GNU or SysV m4; Berkeley won't do) a file, configured for the M680x0 version of GAS, suitable for formatting.  See the text in "pretex.m4" for a fuller explanation (and the macro definitions).

_fi__(0) This file documents the GNU Assembler "_AS__".

Copyright (C) 1991, 1992 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled ``GNU General Public License'' is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled ``GNU General Public License'' may be included in a translation approved by the Free Software Foundation instead of in the original English.

Using _AS__
***********

This file is a user guide to the GNU assembler _AS__.

Overview
********

Here is a brief summary of how to invoke _AS__.  For details, see Comand-Line Options.

       _AS__ [ -a | -al | -as ] [ -D ] [ -f ]
        [ -I PATH ] [ -K ] [ -L ]
        [ -o OBJFILE ] [ -R ] [ -v ] [ -w ]
        [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
        [ -b ] [ -norelax ]
        [ -l ] [ -mc68000 | -mc68010 | -mc68020 ]
        [ -- | FILES ... ]

-a[dhlns]
     Turn on listings; -ad, omit debugging pseudo-ops from listing, -ah, include high-level source, -al, assembly listing, -an, no forms processing, -as, symbols.  These options may be combined; e.g., -aln for assembly listing without forms processing. By itself, -a defaults to -ahls --- that is, all listings turned on.

-D
     This option is accepted only for script compatibility with calls to other assemblers; it has no effect on _AS__.

-f
     ``fast''---skip preprocessing (assume source is compiler output)

-I PATH
     Add PATH to the search list for .include directives

-K
     _if__((!_GENERIC__) && !_DIFFTABKLUG__) This option is accepted but has no effect on the _HOST__ family. _fi__((!_GENERIC__) && !_DIFFTABKLUG__) _if__(_GENERIC__ || _DIFFTABKLUG__) Issue warnings when difference tables altered for long displacements. _fi__(_GENERIC__ || _DIFFTABKLUG__)

-L
     Keep (in symbol table) local symbols, starting with L

-o OBJFILE
     Name the object-file output from _AS__

-R
     Fold data section into text section

-v
     Announce as version

-W
     Suppress warning messages

-- | FILES ...
     Standard input, or source files to assemble.

The following options are available when _AS__ is configured for the Intel 80960 processor.

-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
     Specify which variant of the 960 architecture is the target.

-b
     Add code to collect statistics about branches taken.

-norelax
     Do not alter compare-and-branch instructions for long displacements; error if necessary.

The following options are available when _AS__ is configured for the Motorola 68000 series.

-l
     Shorten references to undefined symbols, to one word instead of two.

-m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -mcpu32
     Specify what processor in the 68000 family is the target.  The default is normally the 68020, but this can be changed at configuration time.

-m68881 | -m68882 | -mno-68881 | -mno-68882
     The target machine does (or does not) have a floating-point coprocessor. The default is to assume a coprocessor for 68020, 68030, and cpu32.  Although the basic 68000 is not compatible with the 68881, a combination of the two can be specified, since it's possible to do emulation of the coprocessor instructions with the main processor.

-m68851 | -mno-68851
     The target machine does (or does not) have a memory-management unit coprocessor.  The default is to assume an MMU for 68020 and up.

Structure of this Manual
========================

This manual is intended to describe what you need to know to use GNU _AS__.  We cover the syntax expected in source files, including notation for symbols, constants, and expressions; the directives that _AS__ understands; and of course how to invoke _AS__.

This manual also describes some of the machine-dependent features of various flavors of the assembler. This manual also describes how the assembler works internally, and provides some information that may be useful to people attempting to port the assembler to another machine.

On the other hand, this manual is 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 not describe the instruction set, standard mnemonics, registers or addressing modes that are standard to a particular architecture. You may want to consult the manufacturer's machine architecture manual for this information.

_AS__, the GNU Assembler
========================

GNU as is really a family of assemblers. If you use (or have used) the GNU assembler on one architecture, you should find a fairly similar environment when you use it on another architecture.  Each version has much in common with the others, including object file formats, most assembler directives (often called pseudo-ops) and assembler syntax.

_AS__ is primarily intended to assemble the output of the GNU C compiler _GCC__ for use by the linker _LD__.  Nevertheless, we've tried to make _AS__ assemble correctly everything that the native assembler would. Any exceptions are documented explicitly (see _MACH_DEP__). This doesn't mean _AS__ always uses the same syntax as another assembler for the same architecture; for example, we know of several incompatible versions of 680x0 assembly language syntax.

Unlike older assemblers, _AS__ is designed to assemble a source program in one pass of the source file.  This has a subtle impact on the .org directive (see .org).

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 Symbol Attributes.

Command Line
============

After the program name _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.

-- (two hyphens) by itself names the standard input file explicitly, as one of the files for _AS__ to assemble.

Except for -- any command line argument that begins with a hyphen (-) is an option.  Each option changes the behavior of _AS__.  No option changes the way another option works.  An option is a - followed by one or more letters; the case of the letter is important.   All options are optional.

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:

     _AS__ -o my-object-file.o mumble.s
     _AS__ -omy-object-file.o mumble.s

Input Files
===========

We use the phrase source program, abbreviated source, to describe the program input to one run of _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.

The source program is a concatenation of the text in all the files, in the order specified.

Each time you run _AS__ it assembles exactly one source program.  The source program is made up of one or more files. (The standard input is also a file.)

You give _AS__ a command line that has zero or more input file names.  The input files are read (from left file name to right).  A command line argument (in any position) that has no special meaning is taken to be an input file name.

If you give _AS__ no file names it attempts to read one input file from the _AS__ standard input, which is normally your terminal.  You may have to type ctl-D to tell _AS__ there is no more program to assemble.

Use -- if you need to explicitly name the standard input file in your command line.

If the source is empty, _AS__ will produce a small, empty object file.

Filenames and Line-numbers
--------------------------

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 ``logical'' file.  See Error and Warning Messages.

Physical files are those files named in the command line given to _AS__.

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 _AS__ source is itself synthesized from other files. See .appfile.

Output (Object) File
====================

Every time you run _AS__ it produces an output file, which is your assembly language program translated into numbers.  This file is the object file, named _if__(_BOUT__) b.out, if _AS__ is configured for the Intel 80960, or _fi__(_BOUT__) _if__(!_BOUT__) a.out, _fi__(!_BOUT__) unless you tell _AS__ to give it another name by using the -o option.  Conventionally, object file names end with .o.  The default name of a.out 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 a.out format.)

The object file is meant for input to the linker _LD__.  It contains assembled program code, information to help _LD__ integrate the assembled program into a runnable file, and (optionally) symbolic information for the debugger.

Error and Warning Messages
==========================

_AS__ may write warnings and error messages to the standard error file (usually your terminal).  This should not happen when  a compiler runs _AS__ automatically.  Warnings report an assumption made so that _AS__ could keep assembling a flawed program; errors report a grave problem that stops the assembly.

Warning messages have the format

     file_name:NNN:Warning Message Text

(where NNN is a line number).  If a logical file name has been given (see .appfile) it is used for the filename, otherwise the name of the current input file is used.  If a logical line number was given _if__(!_A29K__) (see .line) _fi__(!_A29K__) _if__(_A29K__) (see .ln) _fi__(_A29K__) 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).

Error messages have the format

     file_name:NNN:FATAL:Error Message Text

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.

Command-Line Options
********************

This chapter describes command-line options available in all versions of the GNU assembler; see _MACH_DEP__, for options specific to particular machine architectures.

If you are invoking _AS__ via the GNU C compiler (version 2), you can use the -Wa option to pass arguments through to the assembler.  The assembler arguments must be separated from each other (and the -Wa) by commas.  For example:

     gcc -c -g -O -Wa,-alh,-L file.c

will cause a listing to be emitted to standard output with high-level and assembly source.

Many compiler command-line options, such as -R and many machine-specific options, will be automatically be passed to the assembler by the compiler, so usually you do not need to use this -Wa mechanism.

Enable Listings: -a[dhlns]
==========================

These options enable listing output from the assembler.  By itself, -a requests high-level, assembly, and symbols listing. Other letters may be used to select specific options for the list: -ah requests a high-level language listing, -al requests an output-program assembly listing, and -as requests a symbol table listing. High-level listings require that a compiler debugging option like -g be used, and that assembly listings (-al) be requested also.

The -ad option may be used to omit debugging pseudo-ops from the listing.

Once you have specified one of these options, you can further control listing output and its appearance using the directives .list, .nolist, .psize, .eject, .title, and .sbttl. The -an option turns off all forms processing. If you do not request listing output with one of the -a options, the listing-control directives have no effect.

The letters after -a may be combined into one option, e.g., -aln.

-D
==

This option has no effect whatsoever, but it is accepted to make it more likely that scripts written for other assemblers will also work with _AS__.

Work Faster: -f
===============

-f should only be used when assembling programs written by a (trusted) compiler.  -f stops the assembler from pre-processing the input file(s) before assembling them.  See Pre-processing.

     Warning: if the files actually need to be pre-processed (if they contain comments, for example), _AS__ will not work correctly if -f is used.

.include search path: -I PATH
=============================

Use this option to add a PATH to the list of directories _AS__ will search for files specified in .include directives (see .include).  You may use -I as many times as necessary to include a variety of paths.  The current working directory is always searched first; after that, _AS__ searches any -I directories in the same order as they were specified (left to right) on the command line.

Difference Tables: -K
=====================

_if__((!_GENERIC__) && (!_DIFFTABKLUG__)) On the _HOST__ 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 .word directives in difference tables.  The _HOST__ family does not have the addressing limitations that sometimes lead to this alteration on other platforms. _fi__((!_GENERIC__) && (!_DIFFTABKLUG__))

_if__(_GENERIC__ || _DIFFTABKLUG__ ) _AS__ sometimes alters the code emitted for directives of the form .word SYM1-SYM2; see .word. You can use the -K option if you want a warning issued when this is done. _fi__(_GENERIC__ || _DIFFTABKLUG__ )

Include Local Labels: -L
========================

Labels beginning with L (upper case only) are called local labels. See Symbol Names.  Normally you don't see such labels when debugging, because they are intended for the use of programs (like compilers) that compose assembler programs, not for your notice. Normally both _AS__ and _LD__ discard such labels, so you don't normally debug with them.

This option tells _AS__ to retain those L... symbols in the object file.  Usually if you do this you also tell the linker _LD__ to preserve symbols whose names begin with L.

Name the Object File: -o
========================

There is always one object file output when you run _AS__.  By default it has the name a.out or b.out, depending on the target for which _AS__ is configured. _if__(!_I960__) a.out. _fi__(!_I960__) You use this option (which takes exactly one filename) to give the object file a different name.

Whatever the object file is called, _AS__ will overwrite any existing file of the same name.

Join Data and Text Sections: -R
===============================

-R tells _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 Sections and Relocation.)

When you specify -R it would be possible to generate shorter address displacements (because we don't have to cross between text and data section).  We refrain from doing this simply for compatibility with older versions of _AS__.  In future, -R may work this way.

_if__(_COFF__) When _AS__ is configured for COFF output, this option is only useful if you use sections named .text and .data. _fi__(_COFF__)

Announce Version: -v
====================

You can find out what version of as is running by including the option -v (which you can also spell as -version) on the command line.

Suppress Warnings: -W
=====================

_AS__ should never give a warning or error message when assembling compiler output.  But programs written by people often cause _AS__ to give a warning that a particular assumption was made.  All such warnings are directed to the standard error file. If you use this option, no warnings are issued.  This option only affects the warning messages: it does not change any particular of how _AS__ assembles your file.  Errors, which stop the assembly, are still reported.

Syntax
******

This chapter describes the machine-independent syntax allowed in a source file.  _AS__ syntax is similar to what many other assemblers use; it is inspired by the BSD 4.2 _if__(!_VAX__) assembler. _fi__(!_VAX__) _if__(_VAX__) assembler, except that _AS__ does not assemble Vax bit-fields. _fi__(_VAX__)

Pre-Processing
==============

The pre-processor:

  * 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.

  * removes all comments, replacing them with a single space, or an appropriate number of newlines.

  * converts character constants into the appropriate numeric values.

Excess whitespace, comments, and character constants cannot be used in the portions of the input text that are not pre-processed.

If the first line of an input file is #NO_APP or the -f option is given, the input file will not be pre-processed.  Within such an input file, parts of the file can be pre-processed by putting a line that says #APP before the text that should be pre-processed, and putting a line that says #NO_APP after them.  This feature is mainly intend to support asm statements in compilers whose output normally does not need to be pre-processed.

Whitespace
==========

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 Character Constants), any whitespace means the same as exactly one space.

Comments
========

There are two ways of rendering comments to _AS__.  In both cases the comment is equivalent to one space.

Anything from /* through the next */ is a comment. This means you may not nest these comments.

     /*
       The only way to include a newline ('\n') in a comment
       is to use this sort of comment.
     */

     /* This sort of comment does not nest. */

Anything from the line comment character to the next newline is considered a comment and is ignored.  The line comment character is _if__(_VAX__) # on the Vax; _fi__(_VAX__) # on the i960; _if__(_SPARC__) ! on the SPARC; _fi__(_SPARC__) | on the 680x0; _if__(_A29K__) ; for the AMD 29K family; _fi__(_A29K__) _if__(_H8__) ; for the H8/300 family; _fi__(_H8__) _if__(_Z8000__) ! for the Z8000; _fi__(_Z8000__) see _MACH_DEP__.

On some machines there are two different line comment characters.  One will only begin a comment if it is the first non-whitespace character on a line, while the other will always begin a comment.

To be compatible with past assemblers, a special interpretation is given to lines that begin with #.  Following the # an absolute expression (see Expressions) is expected:  this will be the logical line number of the next line.  Then a string (see Strings.) is allowed: if present it is a new logical file name.  The rest of the line, if any, should be whitespace.

If the first non-whitespace characters on the line are not numeric, the line is ignored.  (Just like a comment.)

                               # This is an ordinary comment.
     # 42-6 "new_file_name"    # New logical file name
                               # This is logical line # 36.

This feature is deprecated, and may disappear from future versions of _AS__.

Symbols
=======

A symbol is one or more characters chosen from the set of all letters (both upper and lower case), digits and _if__(!_H8__) the three characters _.$ _fi__(!_H8__) _if__(_H8__) the two characters _. On most machines, you can also use $ in symbol names; exceptions are noted in _MACH_DEP__. _fi__(_H8__) 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 Symbols.

Statements
==========

A statement ends at a newline character (\n) or line separator character.  (The line separator is usually ;, unless this conflicts with the comment character; see _MACH_DEP__.)  The newline or separator character is considered part of the preceding statement.  Newlines and separators within character constants are an exception: they don't end statements.

It is an error to end any statement with end-of-file:  the last character of any input file should be a newline.

You may write a statement on more than one line if you put a backslash (\) immediately in front of any newlines within the statement.  When _AS__ reads a backslashed newline both characters are ignored.  You can even put backslashed newlines in the middle of symbol names without changing the meaning of your source program.

An empty statement is allowed, and may include whitespace.  It is ignored.

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 . 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 instruction: it will assemble into a machine language instruction. Different versions of _AS__ for different computers will recognize different instructions.  In fact, the same symbol may represent a different instruction in a different computer's assembly language.

A label is a symbol immediately followed by a colon (:). 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 Labels.

     label:     .directive    followed by something
     another_label:           # This is an empty statement.
                instruction   operand_1, operand_2, ...

Constants
=========

A constant is a number, written so that its value is known by inspection, without knowing any context.  Like this:

     .byte  74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
     .ascii "Ring the bell\7"                  # A string constant.
     .octa  0x123456789abcdef0123456789ABCDEF0 # A bignum.
     .float 0f-314159265358979323846264338327\
     95028841971.693993751E-40                 # - pi, a flonum.

Character Constants
-------------------

There are two kinds of character constants.  A character stands for one character in one byte and its value may be used in numeric expressions.  String constants (properly called string literals) are potentially many bytes and their values may not be used in arithmetic expressions.

Strings
.......

A 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 escape these characters: precede them with a backslash \ character.  For example \\ represents one backslash:  the first \ is an escape which tells _AS__ to interpret the second character literally as a backslash (which prevents _AS__ from recognizing the second \ as an escape character).  The complete list of escapes follows.

\b
     Mnemonic for backspace; for ASCII this is octal code 010.

\f
     Mnemonic for FormFeed; for ASCII this is octal code 014.

\n
     Mnemonic for newline; for ASCII this is octal code 012.

\r
     Mnemonic for carriage-Return; for ASCII this is octal code 015.

\t
     Mnemonic for horizontal Tab; for ASCII this is octal code 011.

\ DIGIT DIGIT 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, \008 has the value 010, and \009 the value 011.

\\
     Represents one \ character.

\"
     Represents one " character.  Needed in strings to represent this character, because an unescaped " would end the string.

\ ANYTHING-ELSE
     Any other character when escaped by \ will give a warning, but assemble as if the \ 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 _AS__ has no other interpretation, so _AS__ knows it is giving you the wrong code and warns you of the fact.

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, don't use an escape sequence.

Characters
..........

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 '\\ where the first \ escapes the second \.  As you can see, the quote is an acute accent, not a grave accent.  A newline 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.  _AS__ assumes your character code is ASCII: 'A means 65, 'B means 66, and so on.

Number Constants
----------------

_AS__ distinguishes three kinds of numbers according to how they are stored in the target machine.  Integers are numbers that would fit into an int in the C language.  Bignums are integers, but they are stored in more than 32 bits.  Flonums are floating point numbers, described below.

Integers
........

A binary integer is 0b or 0B followed by zero or more of the binary digits 01.

An octal integer is 0 followed by zero or more of the octal digits (01234567).

A decimal integer starts with a non-zero digit followed by zero or more digits (0123456789).

A hexadecimal integer is 0x or 0X followed by one or more hexadecimal digits chosen from 0123456789abcdefABCDEF.

Integers have the usual values.  To denote a negative integer, use the prefix operator - discussed under expressions (see Prefix Operators).

Bignums
.......

A 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.

Flonums
.......

A flonum represents a floating point number.  The translation is indirect: a decimal floating point number from the text is converted by _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 _AS__ specialized to that computer.

A flonum is written by writing (in order)

  * The digit 0.

  * A letter, to tell _AS__ the rest of the number is a flonum. e is recommended.  Case is not important. _if__(_A29K__||_H8__) On the AMD 29K and H8/300 architectures, the letter must be: One of the letters DFPRSX (in upper or lower case). _fi__(_A29K__||_H8__) On the Intel 960 architecture, the letter must be: One of the letters DFT (in upper or lower case).

  * An optional sign: either + or -.

  * An optional integer part: zero or more decimal digits.

  * An optional fractional part: . followed by zero or more decimal digits.

  * An optional exponent, consisting of:

       * An E or e.

       * Optional sign: either + or -.

       * One or more decimal digits.

At least one of the integer part or the fractional part must be present.  The floating point number has the usual base-10 value.

_AS__ does all processing using integers.  Flonums are computed independently of any floating point hardware in the computer running _AS__.

_if__(_I960__&&!_GENERIC__)

Bit Fields
..........

You can also define numeric constants as bit fields. specify two numbers separated by a colon---

     MASK:VALUE

the first will act as a mask; _AS__ will bitwise-and it with the second value.

The resulting number is then packed (in host-dependent byte order) into a field whose width depends on which assembler directive has the bit-field as its argument.  Overflow (a result from the bitwise and requiring more binary digits to represent) is not an error; instead, more constants are generated, of the specified width, beginning with the least significant digits.

The directives .byte, .hword, .int, .long, .short, and .word accept bit-field arguments. _fi__(_I960__&&!_GENERIC__)

Sections and Relocation
***********************

Background
==========

Roughly, a section is a range of addresses, with no gaps; all data ``in'' those addresses is treated the same for some particular purpose. For example there may be a ``read only'' section.

The linker _LD__ reads many object files (partial programs) and combines their contents to form a runnable program.  When _AS__ emits an object file, the partial program is assumed to start at address 0.  _LD__ will assign the final addresses the partial program occupies, so that different partial programs don't overlap.  This is actually an over-simplification, but it will suffice to explain how _AS__ uses sections.

_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 section.  Assigning run-time addresses to sections is called relocation.  It includes the task of adjusting mentions of object-file addresses so they refer to the proper run-time addresses. _if__(_H8__) For the H8/300, _AS__ pads sections if needed to ensure they end on a word (sixteen bit) boundary. _fi__(_H8__)

An object file written by _AS__ has at least three sections, any of which may be empty.  These are named text, data and bss sections.

_if__(_COFF__) When it generates COFF output, _AS__ can also generate whatever other named sections you specify using the .section directive (see .section). If you don't use any directives that place output in the .text or .data sections, these sections will still exist, but will be empty. _fi__(_COFF__)

Within the object file, the text section starts at address 0, the data section follows, and the bss section follows the data section.

To let _LD__ know which data will change when the sections are relocated, and how to change that data, _AS__ also writes to the object file details of the relocation needed.  To perform relocation _LD__ must know, each time an address in the object file is mentioned:

  * Where in the object file is the beginning of this reference to an address?

  * How long (in bytes) is this reference?

  * Which section does the address refer to?  What is the numeric value of

          (ADDRESS) - (START-ADDRESS OF SECTION)?

  * Is the reference to an address ``Program-Counter relative''?

In fact, every address _AS__ ever uses is expressed as

     (SECTION) + (OFFSET INTO SECTION)

Further, every expression _AS__ computes is of this section-relative nature.  Absolute expression means an expression with section ``absolute'' (see _LD__ Sections).  A pass1 expression means an expression with section ``pass1'' (see _AS__ Internal Sections).  In this manual we use the notation {SECNAME N} to mean ``offset N into section SECNAME''.

Apart from text, data and bss sections you need to know about the absolute section.  When _LD__ mixes partial programs, addresses in the absolute section remain unchanged.  For example, address {absolute 0} is ``relocated'' to run-time address 0 by _LD__. Although two partial programs' data sections will not overlap addresses after linking, by definition their absolute sections will overlap. Address {absolute 239} in one partial program will always be the same address when the program is running as address {absolute 239} in any other partial program.

The idea of sections is extended to the undefined section.  Any address whose section is unknown at assembly time is by definition rendered {undefined U}---where U will be 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 undefined.

By analogy the word section is used to describe groups of sections in the linked program.  _LD__ puts all partial programs' text sections in contiguous addresses in the linked program.  It is customary to refer to the text section of a program, meaning all the addresses of all partial program's text sections.  Likewise for data and bss sections.

Some sections are manipulated by _LD__; others are invented for use of _AS__ and have no meaning except during assembly.

_LD__ Sections
==============

_LD__ deals with just four kinds of sections, summarized below.

     _if__(_GENERIC__||_COFF__)

named sections
     _fi__(_GENERIC__||_COFF__)
     _if__(_AOUT__||_BOUT__)

text section
data section
     _fi__(_AOUT__||_BOUT__) These sections hold your program.  _AS__ and _LD__ treat them as separate but equal sections.  Anything you can say of one section is true another. _if__(_AOUT__||_BOUT__) 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 will contain 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. _fi__(_AOUT__||_BOUT__)

bss section
     This section contains zeroed bytes when your program begins running.  It is used to hold unitialized 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.

absolute section
     Address 0 of this section is always ``relocated'' to runtime address 0. This is useful if you want to refer to an address that _LD__ must not change when relocating.  In this sense we speak of absolute addresses being ``unrelocatable'': they don't change during relocation.

undefined section
     This ``section'' is a catch-all for address references to objects not in the preceding sections.

An idealized example of three relocatable sections follows. _if__(_COFF__) The example uses the traditional section names .text and .data. _fi__(_COFF__) Memory addresses are on the horizontal axis.

                           +-----+----+--+
     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 ...

_AS__ Internal Sections
=======================

These sections are meant only for the internal use of _AS__.  They have no meaning at run-time.  You don't really need to know about these sections for most purposes; but they can be mentioned in _AS__ warning messages, so it might be helpful to have an idea of their meanings to _AS__.  These sections are used to permit the value of every expression in your assembly language program to be a section-relative address.

absent
     An expression was expected and none was found.

ASSEMBLER-INTERNAL-LOGIC-ERROR!
     An internal assembler logic error has been found.  This means there is a bug in the assembler.

bignum/flonum
     If a number can't be written as a C int constant (a bignum or a flonum, but not an integer), it is recorded as belonging to this ``section''.  _AS__ has to remember that a flonum or a bignum does not fit into 32 bits, and cannot be an argument (see Arguments) in an expression: this is done by making a flonum or bignum be in a separate internal section.  This is purely for internal _AS__ convenience; bignum/flonum section behaves similarly to absolute section.

pass1 section
     The expression was impossible to evaluate in the first pass.  The assembler will attempt a second pass (second reading of the source) to evaluate the expression.  Your expression mentioned an undefined symbol in a way that defies the one-pass (section + offset in section) assembly process.  No compiler need emit such an expression.

          Warning: the second pass is currently not implemented.  _AS__ will abort with an error message if one is required.

difference section
     As an assist to the C compiler, expressions of the forms

             (UNDEFINED SYMBOL) - (EXPRESSION)
             SOMETHING - (UNDEFINED SYMBOL)
             (UNDEFINED SYMBOL) - (UNDEFINED SYMBOL)

     are permitted, and belong to the difference section.  _AS__ re-evaluates such expressions after the source file has been read and the symbol table built.  If by that time there are no undefined symbols in the expression then the expression assumes a new section.  The intention is to permit statements like .word label - base_of_table to be assembled in one pass where both label and base_of_table are undefined.  This is useful for compiling C and Algol switch statements, Pascal case statements, FORTRAN computed goto statements and the like.

Sub-Sections
============

_if__(_AOUT__||_BOUT__) Assembled bytes _if__(_COFF__) conventionally _fi__(_COFF__) fall into two sections: text and data. _fi__(_AOUT__||_BOUT__) You may have separate groups of _if__(_COFF__||_GENERIC__) data in named sections _fi__(_COFF__||_GENERIC__) _if__((_AOUT__||_BOUT__)&&!_GENERIC__) text or data _fi__((_AOUT__||_BOUT__)&&!_GENERIC__) that you want to end up near to each other in the object file, even though they are not contiguous in the assembler source. _AS__ allows you to use subsections for this purpose. Within each section, there can be numbered subsections with values from 0 to 8192.  Objects assembled into the same subsection will be grouped with other objects in the same subsection when they are all put into the object file.  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 .text 0 before each section of code being output, and a .text 1 before each group of constants being output.

Subsections are optional.  If you don't use subsections, everything will be stored in subsection number zero.

Each subsection is zero-padded up to a multiple of four bytes. (Subsections may be padded a different amount on different flavors of _AS__.)

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; _LD__ and other programs that manipulate object files will 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.

To specify which subsection you want subsequent statements assembled into, use a numeric argument to specify it, in a .text EXPRESSION or a .data EXPRESSION statement. _if__(_COFF__) When generating COFF output, you can also use an extra subsection argument with arbitrary named sections: .section NAME, EXPRESSION. _fi__(_COFF__) EXPRESSION should be an absolute expression. (see Expressions.)  If you just say .text then .text 0 is assumed.  Likewise .data means .data 0.  Assembly begins in text 0.  For instance:

     .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 (*)."

Each section has a location counter incremented by one for every byte assembled into that section.  Because subsections are merely a convenience restricted to _AS__ there is no concept of a subsection location counter.  There is no way to directly manipulate a location counter---but the .align directive will change it, and any label definition will capture its current value.  The location counter of the section that statements are being assembled into is said to be the active location counter.

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.

Addresses in the bss section are allocated with special directives; you may not assemble anything directly into the bss section.  Hence there are no bss subsections. See .comm, see .lcomm.

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.

     Warning: _AS__ does not place symbols in the object file in the same order they were declared.  This may break some debuggers.

Labels
======

A label is written as a symbol immediately followed by a colon :.  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.

Giving Symbols Other Values
===========================

A symbol can be given an arbitrary value by writing a symbol, followed by an equals sign =, followed by an expression (see Expressions).  This is equivalent to using the .set directive.  See .set.

Symbol Names
============

Symbol names begin with a letter or with one of _if__(!_H8__) _.$ _fi__(!_H8__) _if__(_H8__) _. (On most machines, you can also use $ in symbol names; exceptions are noted in _MACH_DEP__.) _fi__(_H8__) That character may be followed by any string of digits, letters, _if__(!_H8__) underscores and dollar signs. _fi__(!_H8__) _if__(_H8__) dollar signs (unless otherwise noted in _MACH_DEP__), and underscores. _fi__(_H8__) Case of letters is significant: foo is a different symbol name than Foo.

_if__(_A29K__) For the AMD 29K family, ? is also allowed in the body of a symbol name, though not at its beginning. _fi__(_A29K__)

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.

Local Symbol Names
------------------

Local symbols help compilers and programmers use names temporarily. There are ten local symbol names, which are re-used throughout the program.  You may refer to them using the names 0 1 ... 9.  To define a local symbol, write a label of the form N: (where N represents any digit).  To refer to the most recent previous definition of that symbol write Nb, using the same digit as when you defined the label.  To refer to the next definition of a local label, write Nf---where N gives you a choice of 10 forward references.  The b stands for ``backwards'' and the f stands for ``forwards''.

Local symbols are not emitted by the current GNU C compiler.

There is no restriction on how you can use these labels, but remember that at any point in the assembly you can refer to at most 10 prior local labels and to at most 10 forward local labels.

Local symbol names are only a notation device.  They are immediately transformed into more conventional symbol names before the assembler uses them.  The symbol names stored in the symbol table, appearing in error messages and optionally emitted to the object file have these parts:

L
     All local labels begin with L. Normally both _AS__ and _LD__ forget symbols that start with L. These labels are used for symbols you are never intended to see.  If you give the -L option then _AS__ will retain these symbols in the object file. If you also instruct _LD__ to retain these symbols, you may use them in debugging.

DIGIT
     If the label is written 0: then the digit is 0. If the label is written 1: then the digit is 1. And so on up through 9:.

A
     This unusual character is included so you don't accidentally invent a symbol of the same name.  The character has ASCII value \001.

ordinal number
     This is a serial number to keep the labels distinct.  The first 0: gets the number 1; The 15th 0: gets the number 15; etc..  Likewise for the other labels 1: through 9:.

For instance, the first 1: is named L1A1, the 44th 3: is named L3A44.

The Special Dot Symbol
======================

The special symbol . refers to the current address that _AS__ is assembling into.  Thus, the expression melvin:
.long . will cause melvin to contain its own address. Assigning a value to . is treated the same as a .org directive.  Thus, the expression .=.+4 is the same as saying _if__(!_A29K__) .space 4. _fi__(!_A29K__) _if__(_A29K__) .block 4. _fi__(_A29K__)

Symbol Attributes
=================

Every symbol has, as well as its name, the attributes ``Value'' and ``Type''.  Depending on output format, symbols can also have auxiliary attributes. The detailed definitions are in _0__<a.out.h>_1__.

If you use a symbol without defining it, _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.

Value
-----

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 _LD__ changes section base addresses during linking.  Absolute symbols' values do not change during linking: that is why they are called absolute.

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 program, and _LD__ will try to determine its value from other programs it is linked with.  You make this kind of symbol simply by mentioning a symbol name without defining it.  A non-zero value represents a .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.

Type
----

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.

_if__(_AOUT__||_BOUT__)
_if__(_BOUT__&&!_GENERIC__)

Symbol Attributes: a.out, b.out
-------------------------------

These symbol attributes appear only when _AS__ is configured for one of the Berkeley-descended object output formats. _fi__(_BOUT__&&!_GENERIC__) _if__(_GENERIC__||!_BOUT__)

Symbol Attributes: a.out
------------------------

_fi__(_GENERIC__||!_BOUT__)

Descriptor
..........

This is an arbitrary 16-bit value.  You may establish a symbol's descriptor value by using a .desc statement (see .desc).  A descriptor value means nothing to _AS__.

Other
.....

This is an arbitrary 8-bit value.  It means nothing to _AS__. _fi__(_AOUT__||_BOUT__)

_if__(_COFF__)

Symbol Attributes for COFF
--------------------------

The COFF format supports a multitude of auxiliary symbol attributes; like the primary symbol attributes, they are set between .def and .endef directives.

Primary Attributes
..................

The symbol name is set with .def; the value and type, respectively, with .val and .type.

Auxiliary Attributes
....................

The _AS__ directives .dim, .line, .scl, .size, and .tag can generate auxiliary symbol table information for COFF. _fi__(_COFF__)

Expressions
***********

An expression specifies an address or numeric value. Whitespace may precede and/or follow an expression.

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 _AS__ will assume a value of (absolute) 0.  This is compatible with other assemblers.

Integer Expressions
===================

An integer expression is one or more arguments delimited by operators.

Arguments
---------

Arguments are symbols, numbers or subexpressions.  In other contexts arguments are sometimes called ``arithmetic operands''.  In this manual, to avoid confusing them with the ``instruction operands'' of the machine language, we use the term ``argument'' to refer to parts of expressions only, reserving the word ``operand'' to refer only to machine instruction operands.

Symbols are evaluated to yield {SECTION NNN} where SECTION is one of text, data, bss, absolute, or undefined.  NNN is a signed, 2's complement 32 bit integer.

Numbers are usually integers.

A number can be a flonum or bignum.  In this case, you are warned that only the low order 32 bits are used, and _AS__ pretends these 32 bits are an integer.  You may write integer-manipulating instructions that act on exotic constants, compatible with other assemblers.

Subexpressions are a left parenthesis ( followed by an integer expression, followed by a right parenthesis ); or a prefix operator followed by an argument.

Operators
---------

Operators are arithmetic functions, like + or %.  Prefix operators are followed by an argument.  Infix operators appear between their arguments.  Operators may be preceded and/or followed by whitespace.

Prefix Operator
---------------

_AS__ has the following prefix operators.  They each take one argument, which must be absolute.

-
     Negation.  Two's complement negation.

~
     Complementation.  Bitwise not.

Infix Operators
---------------

Infix operators take two arguments, one on either side.  Operators have precedence, but operations with equal precedence are performed left to right.  Apart from + or -, both arguments must be absolute, and the result is absolute.

 1. Highest Precedence

     *
          Multiplication.

     /
          Division.  Truncation is the same as the C operator /

     %
          Remainder.

     _0__<_1__
     _0__<<_1__
          Shift Left.  Same as the C operator _0__<<_1__

     _0__>_1__
     _0__>>_1__
          Shift Right.  Same as the C operator _0__>>_1__

 2. Intermediate precedence

     |

          Bitwise Inclusive Or.

     &
          Bitwise And.

     ^
          Bitwise Exclusive Or.

     !
          Bitwise Or Not.

 3. Lowest Precedence

     +
          Addition.  If either argument is absolute, the result has the section of the other argument. If either argument is pass1 or undefined, the result is pass1. Otherwise + is illegal.

     -
          Subtraction.  If the right argument is absolute, the result has the section of the left argument. If either argument is pass1 the result is pass1. If either argument is undefined the result is difference section. If both arguments are in the same section, the result is absolute---provided that section is one of text, data or bss. Otherwise subtraction is illegal.

The sense of the rule for addition is that it's only meaningful to add the offsets in an address; you can only have a defined section in one of the two arguments.

Similarly, you can't subtract quantities from two different sections.

Assembler Directives
********************

All assembler directives have names that begin with a period (.). The rest of the name is letters, usually in lower case.

This chapter discusses directives present regardless of the target machine configuration for the GNU assembler. _if__(!_H8__) see _MACH_DEP__ for additional directives. _fi__(!_H8__)

.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 _AS__ to quit also.  One day .abort will not be supported.

_if__(_COFF__)

.ABORT
======

When producing COFF output, _AS__ accepts this directive as a synonym for .abort. _fi__(_COFF__)

_if__(_BOUT__) _if__(!_COFF__)

.ABORT
======

_fi__(!_COFF__)

When producing b.out output, _AS__ accepts this directive, but ignores it. _fi__(_BOUT__)

.align ABS-EXPR , 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 will have after advancement.  For example .align 3 will advance the location counter until it a multiple of 8.  If the location counter is already a multiple of 8, no change is needed.

The second expression (also absolute) gives the value to be stored in the padding bytes.  It (and the comma) may be omitted.  If it is omitted, the padding bytes are zero.

.appfile STRING
===============

.appfile _if__(!_A29K__) (which may also be spelled .file) _fi__(!_A29K__) tells _AS__ that we are about to start a new logical file.  STRING is the new file name.  In general, the filename is recognized whether or not it is surrounded by quotes "; but if you wish to specify an empty file name is permitted, you must give the quotes--"".  This statement may go away in future: it is only recognized to be compatible with old _AS__ programs.

.ascii "STRING"...
==================

.ascii expects zero or more string literals (see Strings) separated by commas.  It assembles each string (with no automatic trailing zero byte) into consecutive addresses.

.asciz "STRING"...
==================

.asciz is just like .ascii, but each string is followed by a zero byte.  The ``z'' in .asciz stands for ``zero''.

.byte EXPRESSIONS
=================

.byte expects zero or more expressions, separated by commas. Each expression is assembled into the next byte.

.comm SYMBOL , LENGTH
=====================

.comm declares a named common area in the bss section.  Normally _LD__ reserves memory addresses for it during linking, so no partial program defines the location of the symbol.  Use .comm to tell _LD__ that it must be at least LENGTH bytes long.  _LD__ will allocate space for each .comm symbol that is at least as long as the longest .comm request in any of the partial programs linked.  LENGTH is an absolute expression.

.data SUBSECTION
================

.data tells _AS__ to assemble the following statements onto the end of the data subsection numbered SUBSECTION (which is an absolute expression).  If SUBSECTION is omitted, it defaults to zero.

_if__(_COFF__ || _BOUT__)

.def NAME
=========

Begin defining debugging information for a symbol NAME; the definition extends until the .endef directive is encountered. _if__(_BOUT__)

This directive is only observed when _AS__ is configured for COFF format output; when producing b.out, .def is recognized, but ignored. _fi__(_BOUT__) _fi__(_COFF__ || _BOUT__)

_if__(_AOUT__||_BOUT__)

.desc SYMBOL, ABS-EXPRESSION
============================

This directive sets the descriptor of the symbol (see Symbol Attributes) to the low 16 bits of an absolute expression.

_if__(_COFF__) The .desc directive is not available when _AS__ is configured for COFF output; it is only for a.out or b.out object format.  For the sake of compatibility, _AS__ will accept it, but produce no output, when configured for COFF. _fi__(_COFF__) _fi__(_AOUT__||_BOUT__)

_if__(_COFF__ || _BOUT__)

.dim
====

This directive is generated by compilers to include auxiliary debugging information in the symbol table.  It is only permitted inside .def/.endef pairs. _if__(_BOUT__)

.dim is only meaningful when generating COFF format output; when _AS__ is generating b.out, it accepts this directive but ignores it. _fi__(_BOUT__) _fi__(_COFF__ || _BOUT__)

.double FLONUMS
===============

.double expects zero or more flonums, separated by commas.  It assembles floating point numbers. The exact kind of floating point numbers emitted depends on how _AS__ is configured.  See _MACH_DEP__. _if__((!_GENERIC__) && _IEEEFLOAT__) On the _HOST__ family .double emits 64-bit floating-point numbers in IEEE format. _fi__((!_GENERIC__) && _IEEEFLOAT__)

.eject
======

Force a page break at this point, when generating assembly listings.

.else
=====

.else is part of the _AS__ support for conditional assembly; see .if.  It marks the beginning of a section of code to be assembled if the condition for the preceding .if was false.

_if__(0)

.end
====

This doesn't do anything---but isn't an s_ignore, so I suspect it's meant to do something eventually (which is why it isn't documented here as "for compatibility with blah"). _fi__(0)

_if__(_COFF__||_BOUT__)

.endef
======

This directive flags the end of a symbol definition begun with .def. _if__(_BOUT__)

.endef is only meaningful when generating COFF format output; if _AS__ is configured to generate b.out, it accepts this directive but ignores it. _fi__(_BOUT__) _fi__(_COFF__||_BOUT__)

.endif
======

.endif is part of the _AS__ support for conditional assembly; it marks the end of a block of code that is only assembled conditionally.  See .if.

.equ SYMBOL, EXPRESSION
=======================

This directive sets the value of SYMBOL to EXPRESSION. It is synonymous with .set; see .set.

.extern
=======

.extern is accepted in the source program---for compatibility with other assemblers---but it is ignored.  _AS__ treats all undefined symbols as external.

_if__(_GENERIC__||!_A29K__)

.file STRING
============

.file (which may also be spelled .appfile) tells _AS__ that we are about to start a new logical file. STRING is the new file name.  In general, the filename is recognized whether or not it is surrounded by quotes "; but if you wish to specify an empty file name, you must give the quotes--"".  This statement may go away in future: it is only recognized to be compatible with old _AS__ programs. _if__(_A29K__) In some configurations of _AS__, .file has already been removed to avoid conflicts with other assemblers.  See _MACH_DEP__. _fi__(_A29K__) _fi__(_GENERIC__||!_A29K__)

.fill REPEAT , SIZE , VALUE
===========================

RESULT, SIZE and VALUE are absolute expressions. This emits REPEAT copies of SIZE bytes.  REPEAT may be zero or more.  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 REPEAT bytes is taken from an 8-byte number.  The highest order 4 bytes are zero.  The lowest order 4 bytes are VALUE rendered in the byte-order of an integer on the computer _AS__ is assembling for. Each SIZE bytes in a repetition is taken from the lowest order SIZE bytes of this number.  Again, this bizarre behavior is compatible with other people's assemblers.

SIZE and VALUE are optional. If the second comma and VALUE are absent, VALUE is assumed zero.  If the first comma and following tokens are absent, SIZE is assumed to be 1.

.float FLONUMS
==============

This directive assembles zero or more flonums, separated by commas.  It has the same effect as .single. The exact kind of floating point numbers emitted depends on how _AS__ is configured. See _MACH_DEP__. _if__((!_GENERIC__) && _IEEEFLOAT__) On the _HOST__ family, .float emits 32-bit floating point numbers in IEEE format. _fi__((!_GENERIC__) && _IEEEFLOAT__)

.global SYMBOL, .globl SYMBOL
=============================

.global makes the symbol visible to _LD__.  If you define SYMBOL in your partial program, its value is made available to other partial programs that are linked with it.  Otherwise, SYMBOL will take its attributes from a symbol of the same name from another partial program it is linked with.

Both spellings (.globl and .global) are accepted, for compatibility with other assemblers.

.hword EXPRESSIONS
==================

This expects zero or more EXPRESSIONS, and emits a 16 bit number for each.

This directive is a synonym for .short; depending on the target architecture, it may also be a synonym for .word. _if__( _W32__ && !_GENERIC__ ) This directive is a synonym for .short. _fi__( _W32__ && !_GENERIC__ ) _if__(_W16__ && !_GENERIC__ ) This directive is a synonym for both .short and .word. _fi__(_W16__ && !_GENERIC__ )

_if__(_AOUT__||_BOUT__||_COFF__)

.ident
======

This directive is used by some assemblers to place tags in object files. _AS__ simply accepts the directive for source-file compatibility with such assemblers, but does not actually emit anything for it. _fi__(_AOUT__||_BOUT__||_COFF__)

.if ABSOLUTE EXPRESSION
=======================

.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 ABSOLUTE EXPRESSION) is non-zero.  The end of the conditional section of code must be marked by .endif (see .endif); optionally, you may include code for the alternative condition, flagged by .else (see .else.

The following variants of .if are also supported:

.ifdef SYMBOL
     Assembles the following section of code if the specified SYMBOL has been defined.

     _if__(0)

.ifeqs
     Not yet implemented. _fi__(0)

.ifndef SYMBOL
ifnotdef SYMBOL
     Assembles the following section of code if the specified SYMBOL has not been defined.  Both spelling variants are equivalent.

     _if__(0)

ifnes
     Not yet implemented. _fi__(0)

.include "FILE"
===============

This directive provides a way to include supporting files at specified points in your source program.  The code from FILE is assembled as if it followed the point of the .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 -I command-line option (see Command-Line Options).  Quotation marks are required around FILE.

.int EXPRESSIONS
================

_if__(_GENERIC__||!_H8__) _fi__(_GENERIC__||!_H8__) Expect zero or more EXPRESSIONS, of any section, separated by commas.  For each expression, emit a _if__(_GENERIC__||!_H8__) 32-bit _fi__(_GENERIC__||!_H8__) _if__(_H8__&&!_GENERIC__) 16-bit _fi__(_H8__&&!_GENERIC__) number that will, at run time, be the value of that expression.  The byte order of the expression depends on what kind of computer will run the program.

.lcomm SYMBOL , LENGTH
======================

Reserve LENGTH (an absolute expression) bytes for a local common denoted by SYMBOL.  The section and value of SYMBOL are those of the new local common.  The addresses are allocated in the bss section, so at run-time the bytes will start off zeroed.  SYMBOL is not declared global (see .global), so is normally not visible to _LD__.

.lflags
=======

_AS__ accepts this directive, for compatibility with other assemblers, but ignores it.

_if__(_GENERIC__ || !_A29K__)

.line LINE-NUMBER
=================

_fi__(_GENERIC__ || (!_A29K__)) _if__(_A29K__ && (!_GENERIC__) && !_COFF__)

.ln LINE-NUMBER
===============

_fi__(_A29K__ && (!_GENERIC__) && !_COFF__) _if__(_AOUT__||_BOUT__) Tell _AS__ to change the logical line number.  LINE-NUMBER must be an absolute expression.  The next line will have that logical line number.  So any other statements on the current line (after a statement separator character) will be reported as on logical line number LINE-NUMBER - 1. One day this directive will be unsupported: it is used only for compatibility with existing assembler programs.

_if__(_GENERIC__ && _A29K__) Warning: In the AMD29K configuration of _AS__, this command is only available with the name .ln, rather than as either .line or .ln. _fi__(_GENERIC__ && _A29K__) _fi__(_AOUT__||_BOUT__) _if__(_COFF__ && !_A29K__)

Even though this is a directive associated with the a.out or b.out object-code formats, _AS__ will still recognize it when producing COFF output, and will treat .line as though it were the COFF .ln if it is found outside a .def/.endef pair.

Inside a .def, .line is, instead, one of the directives used by compilers to generate auxiliary symbol information for debugging. _fi__(_COFF__ && !_A29K__)

_if__(_AOUT__&&(_GENERIC__||!_A29K__))

.ln LINE-NUMBER
===============

.ln is a synonym for .line. _fi__(_AOUT__&&(_GENERIC__||!_A29K__)) _if__(_COFF__&&!_AOUT__)

.ln LINE-NUMBER
===============

Tell _AS__ to change the logical line number.  LINE-NUMBER must be an absolute expression.  The next line will have that logical line number, so any other statements on the current line (after a statement separator character ;) will be reported as on logical line number LINE-NUMBER - 1. _if__(_BOUT__)

This directive is accepted, but ignored, when _AS__ is configured for b.out; its effect is only associated with COFF output format. _fi__(_BOUT__) _fi__(_COFF__&&!_AOUT__)

.list
=====

Control (in conjunction with the .nolist directive) whether or not assembly listings are generated.  These two directives maintain an internal counter (which is zero initially).   .list increments the counter, and .nolist decrements it.  Assembly listings are generated whenever the counter is greater than zero.

By default, listings are disabled.  When you enable them (with the -a command line option; see Command-Line Options), the initial value of the listing counter is one.

.long EXPRESSIONS
=================

.long is the same as .int, see .int.

.nolist
=======

Control (in conjunction with the .list directive) whether or not assembly listings are generated.  These two directives maintain an internal counter (which is zero initially).   .list increments the counter, and .nolist decrements it.  Assembly listings are generated whenever the counter is greater than zero.

.octa BIGNUMS
=============

This directive expects zero or more bignums, separated by commas.  For each bignum, it emits a 16-byte integer.

The term ``octa'' comes from contexts in which a ``word'' is two bytes; hence octa-word for 16 bytes.

.org NEW-LC , FILL
==================

.org will advance the location counter of the current section to NEW-LC.  NEW-LC is either an absolute expression or an expression with the same section as the current subsection.  That is, you can't use .org to cross sections: if NEW-LC has the wrong section, the .org directive is ignored.  To be compatible with former assemblers, if the section of NEW-LC is absolute, _AS__ will issue a warning, then pretend the section of NEW-LC is the same as the current subsection.

.org may only increase the location counter, or leave it unchanged; you cannot use .org to move the location counter backwards.

Because _AS__ tries to assemble programs in one pass NEW-LC may not be undefined.  If you really detest this restriction we eagerly await a chance to share your improved assembler.

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.

When the location counter (of the current subsection) is advanced, the intervening bytes are filled with FILL which should be an absolute expression.  If the comma and FILL are omitted, FILL defaults to zero.

.psize LINES , COLUMNS
======================

Use this directive to declare the number of lines---and, optionally, the number of columns---to use for each page, when generating listings.

If you don't use .psize, listings will use a default line-count of 60.  You may omit the comma and COLUMNS specification; the default width is 200 columns.

_AS__ will generate formfeeds whenever the specified number of lines is exceeded (or whenever you explicitly request one, using .eject).

If you specify LINES as 0, no formfeeds are generated save those explicitly specified with .eject.

.quad BIGNUMS
=============

.quad expects zero or more bignums, separated by commas.  For each bignum, it emits _if__(_GENERIC__||(!_I960__)) 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.

The term ``quad'' comes from contexts in which a ``word'' is two bytes; hence quad-word for 8 bytes. _fi__(_GENERIC__||(!_I960__)) _if__(_I960__&&(!_GENERIC__)) a 16-byte integer.  If the bignum won't fit in 16 bytes, it prints a warning message; and just takes the lowest order 16 bytes of the bignum. _fi__(_I960__&&(!_GENERIC__))

.sbttl "SUBHEADING"
===================

Use SUBHEADING as the title (third line, immediately after the title line) when generating assembly listings.

This directive affects subsequent pages, as well as the current page if it appears within ten lines of the top of a page.

_if__(_COFF__||_BOUT__)

.scl CLASS
==========

Set the storage-class value for a symbol.  This directive may only be used inside a .def/.endef pair.  Storage class may flag whether a symbol is static or external, or it may record further symbolic debugging information. _if__(_BOUT__)

The .scl directive is primarily associated with COFF output; when configured to generate b.out output format, _AS__ will accept this directive but ignore it. _fi__(_BOUT__) _fi__(_COFF__||_BOUT__)

_if__(_COFF__)

.section NAME, SUBSECTION
=========================

Assemble the following code into end of subsection numbered SUBSECTION in the COFF named section NAME.  If you omit SUBSECTION, _AS__ uses subsection number zero. .section .text is equivalent to the .text directive; .section .data is equivalent to the .data directive. _fi__(_COFF__)

.set SYMBOL, EXPRESSION
=======================

This directive sets the value of SYMBOL to EXPRESSION.  This will change SYMBOL's value and type to conform to EXPRESSION.  If SYMBOL was flagged as external, it remains flagged. (see Symbol Attributes.)

You may .set a symbol many times in the same assembly. If the expression's section is unknowable during pass 1, a second pass over the source program will be forced.  The second pass is currently not implemented.  _AS__ will abort with an error message if one is required.

If you .set a global symbol, the value stored in the object file is the last value stored into it.

.short EXPRESSIONS
==================

_if__(_GENERIC__ || _W16__) .short is the same as .word.  See .word. _if__(_W32__) In some configurations, however, .short and .word generate numbers of different lengths; see _MACH_DEP__. _fi__(_W32__) _fi__(_GENERIC__|| _W16__) _if__((!_GENERIC__) && _W32__) This expects zero or more EXPRESSIONS, and emits a 16 bit number for each. _fi__((!_GENERIC__) && _W32__)

.single FLONUMS
===============

This directive assembles zero or more flonums, separated by commas.  It has the same effect as .float. The exact kind of floating point numbers emitted depends on how _AS__ is configured.  See _MACH_DEP__. _if__((!_GENERIC__) && _IEEEFLOAT__) On the _HOST__ family, .single emits 32-bit floating point numbers in IEEE format. _fi__((!_GENERIC__) && _IEEEFLOAT__)

_if__(_COFF__||_BOUT__)

.size
=====

This directive is generated by compilers to include auxiliary debugging information in the symbol table.  It is only permitted inside .def/.endef pairs. _if__(_BOUT__)

.size is only meaningful when generating COFF format output; when _AS__ is generating b.out, it accepts this directive but ignores it. _fi__(_BOUT__) _fi__(_COFF__||_BOUT__)

_if__(_GENERIC__ || !_A29K__)

.space SIZE , FILL
==================

This directive emits SIZE bytes, each of value FILL.  Both SIZE and FILL are absolute expressions.  If the comma and FILL are omitted, FILL is assumed to be zero. _fi__(_GENERIC__ || !_A29K__)

_if__(_A29K__) On the AMD 29K, this directive is ignored; it is accepted for compatibility with other AMD 29K assemblers.

     Warning: In other versions of the GNU assembler, the directive .space has the effect of .block  see _MACH_DEP__.

_fi__(_A29K__)

_if__(_GENERIC__||!_H8__)
_if__(_AOUT__||_BOUT__||_COFF__)

.stabd, .stabn, .stabs
======================

There are three directives that begin .stab. All emit symbols (see Symbols), for use by symbolic debuggers. The symbols are not entered in the _AS__ hash table: they cannot be referenced elsewhere in the source file. Up to five fields are required:

string
     This is the symbol's name.  It may contain any character except \000, so is more general than ordinary symbol names.  Some debuggers used to code arbitrarily complex structures into symbol names using this field.

type
     An absolute expression.  The symbol's type is set to the low 8 bits of this expression. Any bit pattern is permitted, but _LD__ and debuggers will choke on silly bit patterns.

other
     An absolute expression. The symbol's ``other'' attribute is set to the low 8 bits of this expression.

desc
     An absolute expression. The symbol's descriptor is set to the low 16 bits of this expression.

value
     An absolute expression which becomes the symbol's value.

If a warning is detected while reading a .stabd, .stabn, or .stabs statement, the symbol has probably already been created and you will get a half-formed symbol in your object file.  This is compatible with earlier assemblers!

.stabd TYPE , OTHER , DESC

     The ``name'' 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.

     The symbol's value is set to the location counter, relocatably.  When your program is linked, the value of this symbol will be where the location counter was when the .stabd was assembled.

.stabn TYPE , OTHER , DESC , VALUE
     The name of the symbol is set to the empty string "".

.stabs STRING ,  TYPE , OTHER , DESC , VALUE
     All five fields are specified.

_fi__(_AOUT__||_BOUT__||_COFF__)
_fi__(_GENERIC__||!_H8__)

_if__(_COFF__||_BOUT__)

.tag STRUCTNAME
===============

This directive is generated by compilers to include auxiliary debugging information in the symbol table.  It is only permitted inside .def/.endef pairs.  Tags are used to link structure definitions in the symbol table with instances of those structures. _if__(_BOUT__)

.tag is only used when generating COFF format output; when _AS__ is generating b.out, it accepts this directive but ignores it. _fi__(_BOUT__) _fi__(_COFF__||_BOUT__)

.text SUBSECTION
================

Tells _AS__ to assemble the following statements onto the end of the text subsection numbered SUBSECTION, which is an absolute expression.  If SUBSECTION is omitted, subsection number zero is used.

.title "HEADING"
================

Use HEADING as the title (second line, immediately after the source file name and pagenumber) when generating assembly listings.

This directive affects subsequent pages, as well as the current page if it appears within ten lines of the top of a page.

_if__(_COFF__||_BOUT__)

.type INT
=========

This directive, permitted only within .def/.endef pairs, records the integer INT as the type attribute of a symbol table entry. _if__(_BOUT__)

.type is associated only with COFF format output; when _AS__ is configured for b.out output, it accepts this directive but ignores it. _fi__(_BOUT__) _fi__(_COFF__||_BOUT__)

_if__(_COFF__||_BOUT__)

.val ADDR
=========

This directive, permitted only within .def/.endef pairs, records the address ADDR as the value attribute of a symbol table entry. _if__(_BOUT__)

.val is used only for COFF output; when _AS__ is configured for b.out, it accepts this directive but ignores it. _fi__(_BOUT__) _fi__(_COFF__||_BOUT__)

.word EXPRESSIONS
=================

This directive expects zero or more EXPRESSIONS, of any section, separated by commas. _if__((!_GENERIC__) && _W32__) For each expression, _AS__ emits a 32-bit number. _fi__((!_GENERIC__) && _W32__) _if__((!_GENERIC__) && _W16__) For each expression, _AS__ emits a 16-bit number. _fi__((!_GENERIC__) && _W16__)

The size of the number emitted, and its byte order, depends on what kind of computer will run the program.

_if__(_GENERIC__ || _DIFFTABKLUG__)

     Warning: Special Treatment to support Compilers

Machines with a 32-bit address space, but that do less than 32-bit addressing, require the following special treatment.  If the machine of interest to you does 32-bit addressing (or doesn't require it; see _MACH_DEP__), you can ignore this issue.

In order to assemble compiler output into something that will work, _AS__ will occasionlly do strange things to .word directives. Directives of the form .word sym1-sym2 are often emitted by compilers as part of jump tables.  Therefore, when _AS__ assembles a directive of the form .word sym1-sym2, and the difference between sym1 and sym2 does not fit in 16 bits, _AS__ will create a secondary jump table, immediately before the next label. This secondary jump table will be preceded by a short-jump to the first byte after the secondary table.  This short-jump prevents the flow of control from accidentally falling into the new table.  Inside the table will be a long-jump to sym2.  The original .word will contain sym1 minus the address of the long-jump to sym2.

If there were several occurrences of .word sym1-sym2 before the secondary jump table, all of them will be adjusted.  If there was a .word sym3-sym4, that also did not fit in sixteen bits, a long-jump to sym4 will be included in the secondary jump table, and the .word directives will be adjusted to contain sym3 minus the address of the long-jump to sym4; and so on, for as many entries in the original jump table as necessary.

This feature may be disabled by compiling _AS__ with the
-DWORKING_DOT_WORD option. This feature is likely to confuse assembly language programmers. _fi__(_GENERIC__ || _DIFFTABKLUG__)

Deprecated Directives
=====================

One day these directives won't work. They are included for compatibility with older assemblers.

.abort

.appfile

.line

Machine Dependent Features
**************************

The machine instruction sets are (almost by definition) different on each machine where _AS__ runs.  Floating point representations vary as well, and _AS__ often supports a few additional directives or command-line options for compatibility with other assemblers on a particular platform.  Finally, some versions of _AS__ support special pseudo-instructions for branch optimization.

This chapter discusses most of these differences, though it does not include details on any machine's instruction set.  For details on that subject, see the hardware manufacturer's manual.

_if__(_VAX__)
_CHAPSEC__(0+_GENERIC__) VAX Dependent Features

_CHAPSEC__(1+_GENERIC__) VAX Command-Line Options

The Vax version of _AS__ accepts any of the following options, gives a warning message that the option was ignored and proceeds. These options are for compatibility with scripts designed for other people's assemblers.

-D (Debug)
-S (Symbol Table)
-T (Token Trace)
     These are obsolete options used to debug old assemblers.

-d (Displacement size for JUMPs)
     This option expects a number following the -d.  Like options that expect filenames, the number may immediately follow the -d (old standard) or constitute the whole of the command line argument that follows -d (GNU standard).

-V (Virtualize Interpass Temporary File)
     Some other assemblers use a temporary file.  This option commanded them to keep the information in active memory rather than in a disk file.  _AS__ always does this, so this option is redundant.

-J (JUMPify Longer Branches)
     Many 32-bit computers permit a variety of branch instructions to do the same job.  Some of these instructions are short (and fast) but have a limited range; others are long (and slow) but can branch anywhere in virtual memory.  Often there are 3 flavors of branch: short, medium and long.  Some other assemblers would emit short and medium branches, unless told by this option to emit short and long branches.

-t (Temporary File Directory)
     Some other assemblers may use a temporary file, and this option takes a filename being the directory to site the temporary file.  _AS__ does not use a temporary disk file, so this option makes no difference.  -t needs exactly one filename.

The Vax version of the assembler accepts two options when compiled for VMS.  They are -h, and -+.  The -h option prevents _AS__ from modifying the symbol-table entries for symbols that contain lowercase characters (I think).  The -+ option causes _AS__ to print warning messages if the FILENAME part of the object file, or any symbol name is larger than 31 characters.  The -+ option also insertes some code following the _main symbol so that the object file will be compatible with Vax-11 "C".

_CHAPSEC__(1+_GENERIC__) VAX Floating Point

Conversion of flonums to floating point is correct, and compatible with previous assemblers.  Rounding is towards zero if the remainder is exactly half the least significant bit.

D, F, G and H floating point formats are understood.

Immediate floating literals (e.g. S`$6.9) are rendered correctly.  Again, rounding is towards zero in the boundary case.

The .float directive produces f format numbers. The .double directive produces d format numbers.

_CHAPSEC__(1+_GENERIC__) Vax Machine Directives

The Vax version of the assembler supports four directives for generating Vax floating point constants.  They are described in the table below.

.dfloat
     This expects zero or more flonums, separated by commas, and assembles Vax d format 64-bit floating point constants.

.ffloat
     This expects zero or more flonums, separated by commas, and assembles Vax f format 32-bit floating point constants.

.gfloat
     This expects zero or more flonums, separated by commas, and assembles Vax g format 64-bit floating point constants.

.hfloat
     This expects zero or more flonums, separated by commas, and assembles Vax h format 128-bit floating point constants.

_CHAPSEC__(1+_GENERIC__) VAX Opcodes

All DEC mnemonics are supported.  Beware that case... instructions have exactly 3 operands.  The dispatch table that follows the case... instruction should be made with .word statements.  This is compatible with all unix assemblers we know of.

_CHAPSEC__(1+_GENERIC__) VAX Branch Improvement

Certain pseudo opcodes are permitted.  They are for branch instructions.  They expand to the shortest branch instruction that will reach the target.  Generally these mnemonics are made by substituting j for b at the start of a DEC mnemonic. This feature is included both for compatibility and to help compilers.  If you don't need this feature, don't use these opcodes.  Here are the mnemonics, and the code they can expand into.

jbsb
     Jsb is already an instruction mnemonic, so we chose jbsb.

     (byte displacement)
          bsbb ...

     (word displacement)
          bsbw ...

     (long displacement)
          jsb ...

jbr
jr
     Unconditional branch.

     (byte displacement)
          brb ...

     (word displacement)
          brw ...

     (long displacement)
          jmp ...

jCOND
     COND may be any one of the conditional branches neq, nequ, eql, eqlu, gtr, geq, lss, gtru, lequ, vc, vs, gequ, cc, lssu, cs. COND may also be one of the bit tests bs, bc, bss, bcs, bsc, bcc, bssi, bcci, lbs, lbc. NOTCOND is the opposite condition to COND.

     (byte displacement)
          bCOND ...

     (word displacement)
          bNOTCOND foo ; brw ... ; foo:

     (long displacement)
          bNOTCOND foo ; jmp ... ; foo:

jacbX
     X may be one of b d f g h l w.

     (word displacement)
          OPCODE ...

     (long displacement)

               OPCODE ..., foo ;
               brb bar ;
               foo: jmp ... ;
               bar:

jaobYYY
     YYY may be one of lss leq.

jsobZZZ
     ZZZ may be one of geq gtr.

     (byte displacement)
          OPCODE ...

     (word displacement)

               OPCODE ..., foo ;
               brb bar ;
               foo: brw DESTINATION ;
               bar:

     (long displacement)

               OPCODE ..., foo ;
               brb bar ;
               foo: jmp DESTINATION ;
               bar:

aobleq
aoblss
sobgeq
sobgtr

     (byte displacement)
          OPCODE ...

     (word displacement)

               OPCODE ..., foo ;
               brb bar ;
               foo: brw DESTINATION ;
               bar:

     (long displacement)

               OPCODE ..., foo ;
               brb bar ;
               foo: jmp DESTINATION ;
               bar:

_CHAPSEC__(1+_GENERIC__) VAX Operands

The immediate character is $ for Unix compatibility, not # as DEC writes it.

The indirect character is * for Unix compatibility, not @ as DEC writes it.

The displacement sizing character is ` (an accent grave) for Unix compatibility, not ^ as DEC writes it.  The letter preceding ` may have either case.  G is not understood, but all other letters (b i l s w) are understood.

Register names understood are r0 r1 r2 ... r15 ap fp sp pc.  Any case of letters will do.

For instance

     tstb *w`$4(r5)

Any expression is permitted in an operand.  Operands are comma separated.

_CHAPSEC__(1+_GENERIC__) Not Supported on VAX

Vax bit fields can not be assembled with _AS__.  Someone can add the required code if they really need it.

_fi__(_VAX__) _if__(_A29K__)
_CHAPSEC__(0+_GENERIC__) AMD 29K Dependent Features

_CHAPSEC__(1+_GENERIC__) Options _AS__ has no additional command-line options for the AMD 29K family.

_CHAPSEC__(1+_GENERIC__) Syntax

_CHAPSEC__(2+_GENERIC__) Special Characters

; is the line comment character.

@ can be used instead of a newline to separate statements.

The character ? is permitted in identifiers (but may not begin an identifier).

_CHAPSEC__(2+_GENERIC__) Register Names

General-purpose registers are represented by predefined symbols of the form GRNNN (for global registers) or LRNNN (for local registers), where NNN represents a number between 0 and 127, written with no leading zeros.  The leading letters may be in either upper or lower case; for example, gr13 and LR7 are both valid register names.

You may also refer to general-purpose registers by specifying the register number as the result of an expression (prefixed with %% to flag the expression as a register number):

     %%EXPRESSION

---where EXPRESSION must be an absolute expression evaluating to a number between 0 and 255.  The range [0, 127] refers to global registers, and the range [128, 255] to local registers.

In addition, _AS__ understands the following protected special-purpose register names for the AMD 29K family:

       vab    chd    pc0
       ops    chc    pc1
       cps    rbp    pc2
       cfg    tmc    mmu
       cha    tmr    lru

These unprotected special-purpose register names are also recognized:

       ipc    alu    fpe
       ipa    bp     inte
       ipb    fc     fps
       q      cr     exop

_CHAPSEC__(1+_GENERIC__) Floating Point

The AMD 29K family uses IEEE floating-point numbers.

_CHAPSEC__(1+_GENERIC__) AMD 29K Machine Directives

.block SIZE , FILL
     This directive emits SIZE bytes, each of value FILL.  Both SIZE and FILL are absolute expressions.  If the comma and FILL are omitted, FILL is assumed to be zero.

     In other versions of the GNU assembler, this directive is called .space.

.cputype
     This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers.

.file
     This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers.

          Warning: in other versions of the GNU assembler, .file is used for the directive called .appfile in the AMD 29K support.

.line
     This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers.

.sect
     This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers.

.use SECTION NAME
     Establishes the section and subsection for the following code; SECTION NAME may be one of .text, .data, .data1, or .lit.  With one of the first three SECTION NAME options, .use is equivalent to the machine directive SECTION NAME; the remaining case, .use .lit, is the same as .data 200.

_CHAPSEC__(1+_GENERIC__) Opcodes

_AS__ implements all the standard AMD 29K opcodes.  No additional pseudo-instructions are needed on this family.

For information on the 29K machine instruction set, see Am29000 User's Manual, Advanced Micro Devices, Inc.

_fi__(_A29K__) _if__(_H8__)
_CHAPSEC__(0+_GENERIC__) H8/300 Dependent Features

_CHAPSEC__(1+_GENERIC__) Options

_AS__ has no additional command-line options for the Hitachi H8/300 family.

_CHAPSEC__(1+_GENERIC__) Syntax

_CHAPSEC__(2+_GENERIC__) Special Characters

; is the line comment character.

$ can be used instead of a newline to separate statements. Therefore you may not use $ in symbol names on the H8/300.

_CHAPSEC__(2+_GENERIC__) Register Names

You can use predefined symbols of the form rNh and rNl to refer to the H8/300 registers as sixteen 8-bit general-purpose registers.  N is a digit from 0 to 7); for instance, both r0h and r7l are valid register names.

You can also use the eight predefined symbols rN to refer to the H8/300 registers as 16-bit registers (you must use this form for addressing).

The two control registers are called pc (program counter; a 16-bit register) and ccr (condition code register; an 8-bit register).   r7 is used as the stack pointer, and can also be called sp.

_CHAPSEC__(2+_GENERIC__) Addressing Modes

_AS__ understands the following addressing modes for the H8/300:

rN
     Register direct

@rN
     Register indirect

@(D, rN)
@(D:16, rN)
     Register indirect: 16-bit displacement D from register N. (You may specify the :16 for clarity if you wish, but it is not required and has no effect.)

@rN+
     Register indirect with post-increment

@-rN
     Register indirect with pre-decrement

@AA
@AA:8
@AA:16
     Absolute address aa.  You may specify the :8 or :16 for clarity, if you wish; but _AS__ neither requires this nor uses it---the address size required is taken from context.

#XX
#XX:8
#XX:16
     Immediate data XX.  You may specify the :8 or :16 for clarity, if you wish; but _AS__ neither requires this nor uses it---the data size required is taken from context.

@@AA
@@AA:8
     Memory indirect.  You may specify the :8 for clarity, if you wish; but _AS__ neither requires this nor uses it.

_CHAPSEC__(1+_GENERIC__) Floating Point

The H8/300 family uses IEEE floating-point numbers.

_CHAPSEC__(1+_GENERIC__) H8/300 Machine Directives

_AS__ has no machine-dependent directives for the H8/300. However, on this platform the .int and .word directives generate 16-bit numbers.

_CHAPSEC__(1+_GENERIC__) Opcodes

For detailed information on the H8/300 machine instruction set, see H8/300 Series Programming Manual (Hitachi ADE--602--025).

_AS__ implements all the standard H8/300 opcodes.  No additional pseudo-instructions are needed on this family.

The following table summarizes the opcodes and their arguments:

                 Rs   source register
                 Rd   destination register
                 imm  immediate data
                 x:3  a bit (as a number between 0 and 7)
                 d:8  eight bit displacement from pc
                 d:16 sixteen bit displacement from Rs

     add.b   Rs,Rd                  biand   #x:3,Rd
     add.b   #imm:8,Rd              biand   #x:3,@Rd
     add.w   Rs,Rd                  biand   #x:3,@aa:8
     adds    #1,Rd                  bild    #x:3,Rd
     adds    #2,Rd                  bild    #x:3,@Rd
     addx    #imm:8,Rd              bild    #x:3,@aa:8
     addx    Rs,Rd                  bior    #x:3,Rd
     and     #imm:8,Rd              bior    #x:3,@Rd
     and     Rs,Rd                  bior    #x:3,@aa:8
     andc    #imm:8,ccr             bist    #x:3,Rd
     band    #x:3,Rd                bist    #x:3,@Rd
     band    #x:3,@Rd               bist    #x:3,@aa:8
     bra     d:8                    bixor   #x:3,Rd
     bt      d:8                    bixor   #x:3,@Rd
     brn     d:8                    bixor   #x:3,@aa:8
     bf      d:8                    bld     #x:3,Rd
     bhi     d:8                    bld     #x:3,@Rd
     bls     d:8                    bld     #x:3,@aa:8
     bcc     d:8                    bnot    #x:3,Rd
     bhs     d:8                    bnot    #x:3,@Rd
     bcs     d:8                    bnot    #x:3,@aa:8
     blo     d:8                    bnot    Rs,Rd
     bne     d:8                    bnot    Rs,@Rd
     beq     d:8                    bnot    Rs,@aa:8
     bvc     d:8                    bor     #x:3,Rd
     bvs     d:8                    bor     #x:3,@Rd
     bpl     d:8                    bor     #x:3,@aa:8
     bmi     d:8                    bset    #x:3,@Rd
     bge     d:8                    bset    #x:3,@aa:8
     blt     d:8                    bset    Rs,Rd
     bgt     d:8                    bset    Rs,@Rd
     ble     d:8                    bset    Rs,@aa:8
     bclr    #x:3,Rd                bsr     d:8
     bclr    #x:3,@Rd               bst     #x:3,Rd
     bclr    #x:3,@aa:8             bst     #x:3,@Rd
     bclr    Rs,Rd                  bst     #x:3,@aa:8
     bclr    Rs,@Rd                 btst    #x:3,Rd

     btst    #x:3,@Rd               mov.w   @(d:16, Rs),Rd
     btst    #x:3,@aa:8             mov.w   @Rs+,Rd
     btst    Rs,Rd                  mov.w   @aa:16,Rd
     btst    Rs,@Rd                 mov.w   Rs,@Rd
     btst    Rs,@aa:8               mov.w   Rs,@(d:16, Rd)
     bxor    #x:3,Rd                mov.w   Rs,@-Rd
     bxor    #x:3,@Rd               mov.w   Rs,@aa:16
     bxor    #x:3,@aa:8             movfpe  @aa:16,Rd
     cmp.b   #imm:8,Rd              movtpe  Rs,@aa:16
     cmp.b   Rs,Rd                  mulxu   Rs,Rd
     cmp.w   Rs,Rd                  neg     Rs
     daa     Rs                     nop
     das     Rs                     not     Rs
     dec     Rs                     or      #imm:8,Rd
     divxu   Rs,Rd                  or      Rs,Rd
     eepmov                         orc     #imm:8,ccr
     inc     Rs                     pop     Rs
     jmp     @Rs                    push    Rs
     jmp     @aa:16                 rotl    Rs
     jmp     @@aa                   rotr    Rs
     jsr     @Rs                    rotxl   Rs
     jsr     @aa:16                 rotxr   Rs
     jsr     @@aa:8                 rte
     ldc     #imm:8,ccr             rts
     ldc     Rs,ccr                 shal    Rs
     mov.b   Rs,Rd                  shar    Rs
     mov.b   #imm:8,Rd              shll    Rs
     mov.b   @Rs,Rd                 shlr    Rs
     mov.b   @(d:16, Rs),Rd         sleep
     mov.b   @Rs+,Rd                stc     ccr,Rd
     mov.b   @aa:16,Rd              sub.b   Rs,Rd
     mov.b   @aa:8,Rd               sub.w   Rs,Rd
     mov.b   Rs,@Rd                 subs    #1,Rd
     mov.b   Rs,@(d:16, Rd)         subs    #2,Rd
     mov.b   Rs,@-Rd                subx    #imm:8,Rd
     mov.b   Rs,@aa:16              subx    Rs,Rd
     mov.b   Rs,@aa:8               xor     #imm:8,Rd
     mov.w   Rs,Rd                  xor     Rs,Rd
     mov.w   #imm:16,Rd             xorc    #imm:8,ccr
     mov.w   @Rs,Rd

Four H8/300 instructions (add, cmp, mov, sub) are defined with variants using the suffixes .b and .w to specify the size of a memory operand.  _AS__ supports these suffixes, but does not require them; since one of the operands is always a register, _AS__ can deduce the correct size.

For example, since r0 refers to a 16-bit register,

     mov    r0,@foo
     is equivalent to
     mov.w  r0,@foo

If you use the size suffixes, _AS__ will issue a warning if there's a mismatch between the suffix and the register size.

_fi__(_H8__)
_CHAPSEC__(0+_GENERIC__) Intel 80960 Dependent Features

_CHAPSEC__(1+_GENERIC__) i960 Command-line Options

-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
     Select the 80960 architecture.  Instructions or features not supported by the selected architecture cause fatal errors.

     -ACA is equivalent to -ACA_A; -AKC is equivalent to -AMC.  Synonyms are provided for compatibility with other tools.

     If none of these options is specified, _AS__ will generate code for any instruction or feature that is supported by some version of the 960 (even if this means mixing architectures!).  In principle, _AS__ will attempt to deduce the minimal sufficient processor type if none is specified; depending on the object code format, the processor type may be recorded in the object file.  If it is critical that the _AS__ output match a specific architecture, specify that architecture explicitly.

-b
     Add code to collect information about conditional branches taken, for later optimization using branch prediction bits.  (The conditional branch instructions have branch prediction bits in the CA, CB, and CC architectures.)  If BR represents a conditional branch instruction, the following represents the code generated by the assembler when -b is specified:

                  call    INCREMENT ROUTINE
                  .word   0       # pre-counter
          Label:  BR
                  call    INCREMENT ROUTINE
                  .word   0       # post-counter

     The counter following a branch records the number of times that branch was not taken; the differenc between the two counters is the number of times the branch was taken.

     A table of every such Label is also generated, so that the external postprocessor gbr960 (supplied by Intel) can locate all the counters.  This table is always labelled __BRANCH_TABLE__; this is a local symbol to permit collecting statistics for many separate object files.  The table is word aligned, and begins with a two-word header.  The first word, initialized to 0, is used in maintaining linked lists of branch tables.  The second word is a count of the number of entries in the table, which follow immediately: each is a word, pointing to one of the labels illustrated above.

           +------------+------------+------------+ ... +------------+
           |            |            |            |     |            |
           |  *NEXT     |  COUNT: N  | *BRLAB 1   |     | *BRLAB N   |
           |            |            |            |     |            |
           +------------+------------+------------+ ... +------------+

                         __BRANCH_TABLE__ layout

     The first word of the header is used to locate multiple branch tables, since each object file may contain one. Normally the links are maintained with a call to an initialization routine, placed at the beginning of each function in the file.  The GNU C compiler will generate these calls automatically when you give it a -b option. For further details, see the documentation of gbr960.

-norelax
     Normally, Compare-and-Branch instructions with targets that require displacements greater than 13 bits (or that have external targets) are replaced with the corresponding compare (or chkbit) and branch instructions.  You can use the -norelax option to specify that _AS__ should generate errors instead, if the target displacement is larger than 13 bits.

     This option does not affect the Compare-and-Jump instructions; the code emitted for them is always adjusted when necessary (depending on displacement size), regardless of whether you use -norelax.

_CHAPSEC__(1+_GENERIC__) Floating Point

_AS__ generates IEEE floating-point numbers for the directives .float, .double, .extended, and .single.

_CHAPSEC__(1+_GENERIC__) i960 Machine Directives

.bss SYMBOL, LENGTH, ALIGN
     Reserve LENGTH bytes in the bss section for a local SYMBOL, aligned to the power of two specified by ALIGN.  LENGTH and ALIGN must be positive absolute expressions.  This directive differs from .lcomm only in that it permits you to specify an alignment.  See .lcomm.

.extended FLONUMS
     .extended expects zero or more flonums, separated by commas; for each flonum, .extended emits an IEEE extended-format (80-bit) floating-point number.

.leafproc CALL-LAB, BAL-LAB
     You can use the .leafproc directive in conjunction with the optimized callj instruction to enable faster calls of leaf procedures.  If a procedure is known to call no other procedures, you may define an entry point that skips procedure prolog code (and that does not depend on system-supplied saved context), and declare it as the BAL-LAB using .leafproc.  If the procedure also has an entry point that goes through the normal prolog, you can specify that entry point as CALL-LAB.

     A .leafproc declaration is meant for use in conjunction with the optimized call instruction callj; the directive records the data needed later to choose between converting the callj into a bal or a call.

     CALL-LAB is optional; if only one argument is present, or if the two arguments are identical, the single argument is assumed to be the bal entry point.

.sysproc NAME, INDEX
     The .sysproc directive defines a name for a system procedure. After you define it using .sysproc, you can use NAME to refer to the system procedure identified by INDEX when calling procedures with the optimized call instruction callj.

     Both arguments are required; INDEX must be between 0 and 31 (inclusive).

_CHAPSEC__(1+_GENERIC__) i960 Opcodes

All Intel 960 machine instructions are supported; see i960 Command-line Options for a discussion of selecting the instruction subset for a particular 960 architecture.

Some opcodes are processed beyond simply emitting a single corresponding instruction: callj, and Compare-and-Branch or Compare-and-Jump instructions with target displacements larger than 13 bits.

_CHAPSEC__(2+_GENERIC__) callj

You can write callj to have the assembler or the linker determine the most appropriate form of subroutine call: call, bal, or calls.  If the assembly source contains enough information---a .leafproc or .sysproc directive defining the operand---then _AS__ will translate the callj; if not, it will simply emit the callj, leaving it for the linker to resolve.

_CHAPSEC__(2+_GENERIC__) Compare-and-Branch

The 960 architectures provide combined Compare-and-Branch instructions that permit you to store the branch target in the lower 13 bits of the instruction word itself.  However, if you specify a branch target far enough away that its address won't fit in 13 bits, the assembler can either issue an error, or convert your Compare-and-Branch instruction into separate instructions to do the compare and the branch.

Whether _AS__ gives an error or expands the instruction depends on two choices you can make: whether you use the -norelax option, and whether you use a ``Compare and Branch'' instruction or a ``Compare and Jump'' instruction.  The ``Jump'' instructions are always expanded if necessary; the ``Branch'' instructions are expanded when necessary unless you specify -norelax---in which case _AS__ gives an error instead.

These are the Compare-and-Branch instructions, their ``Jump'' variants, and the instruction pairs they may expand into:

             Compare and
          Branch      Jump       Expanded to
          ------    ------       ------------
             bbc                 chkbit; bno
             bbs                 chkbit; bo
          cmpibe    cmpije       cmpi; be
          cmpibg    cmpijg       cmpi; bg
         cmpibge   cmpijge       cmpi; bge
          cmpibl    cmpijl       cmpi; bl
         cmpible   cmpijle       cmpi; ble
         cmpibno   cmpijno       cmpi; bno
         cmpibne   cmpijne       cmpi; bne
          cmpibo    cmpijo       cmpi; bo
          cmpobe    cmpoje       cmpo; be
          cmpobg    cmpojg       cmpo; bg
         cmpobge   cmpojge       cmpo; bge
          cmpobl    cmpojl       cmpo; bl
         cmpoble   cmpojle       cmpo; ble
         cmpobne   cmpojne       cmpo; bne

_CHAPSEC__(0+_GENERIC__) M680x0 Dependent Features

_CHAPSEC__(1+_GENERIC__) M680x0 Options

The Motorola 680x0 version of _AS__ has two machine dependent options. One shortens undefined references from 32 to 16 bits, while the other is used to tell _AS__ what kind of machine it is assembling for.

You can use the -l option to shorten the size of references to undefined symbols.  If the -l option is not given, references to undefined symbols will be a full long (32 bits) wide.  (Since _AS__ cannot know where these symbols will end up, _AS__ can only allocate space for the linker to fill in later.  Since _AS__ doesn't know how far away these symbols will be, it allocates as much space as it can.) If this option is given, the references will only be one word wide (16 bits).  This may be useful if you want the object file to be as small as possible, and you know that the relevant symbols will be less than 17 bits away.

The 680x0 version of _AS__ is most frequently used to assemble programs for the Motorola MC68020 microprocessor.  Occasionally it is used to assemble programs for the mostly similar, but slightly different MC68000 or MC68010 microprocessors.  You can give _AS__ the options -m68000, -mc68000, -m68010, -mc68010, -m68020, and -mc68020 to tell it what processor is the target.

_CHAPSEC__(1+_GENERIC__) Syntax

The 680x0 version of _AS__ uses syntax similar to the Sun assembler. Size modifiers are appended directly to the end of the opcode without an intervening period.  For example, write movl rather than move.l.

If _AS__ is compiled with SUN_ASM_SYNTAX defined, it will also allow Sun-style local labels of the form 1$ through $9.

In the following table apc stands for any of the address registers (a0 through a7), nothing,, the Program Counter (pc), or the zero-address relative to the program counter (zpc).

The following addressing modes are understood:

Immediate
     #DIGITS

Data Register
     d0 through d7

Address Register
     a0 through a7

Address Register Indirect
     a0@ through a7@

Address Register Postincrement
     a0@+ through a7@+

Address Register Predecrement
     a0@- through a7@-

Indirect Plus Offset
     APC@(DIGITS)

Index
     APC@(DIGITS,REGISTER:SIZE:SCALE)

     or APC@(REGISTER:SIZE:SCALE)

Postindex
     APC@(DIGITS)@(DIGITS,REGISTER:SIZE:SCALE)

     or APC@(DIGITS)@(REGISTER:SIZE:SCALE)

Preindex
     APC@(DIGITS,REGISTER:SIZE:SCALE)@(DIGITS)

     or APC@(REGISTER:SIZE:SCALE)@(DIGITS)

Memory Indirect
     APC@(DIGITS)@(DIGITS)

Absolute
     SYMBOL, or DIGITS

_CHAPSEC__(1+_GENERIC__) Floating Point

The floating point code is not too well tested, and may have subtle bugs in it.

Packed decimal (P) format floating literals are not supported. Feel free to add the code!

The floating point formats generated by directives are these.

.float
     Single precision floating point constants.

.double
     Double precision floating point constants.

There is no directive to produce regions of memory holding extended precision numbers, however they can be used as immediate operands to floating-point instructions.  Adding a directive to create extended precision numbers would not be hard, but it has not yet seemed necessary.

_CHAPSEC__(1+_GENERIC__) 680x0 Machine Directives

In order to be compatible with the Sun assembler the 680x0 assembler understands the following directives.

.data1
     This directive is identical to a .data 1 directive.

.data2
     This directive is identical to a .data 2 directive.

.even
     This directive is identical to a .align 1 directive.

.skip
     This directive is identical to a .space directive.

_CHAPSEC__(1+_GENERIC__) Opcodes

_CHAPSEC__(2+_GENERIC__) Branch Improvement

Certain pseudo opcodes are permitted for branch instructions. They expand to the shortest branch instruction that will reach the target.  Generally these mnemonics are made by substituting j for b at the start of a Motorola mnemonic.

The following table summarizes the pseudo-operations.  A * flags cases that are more fully described after the table:

               Displacement
               +-------------------------------------------------
               |                68020   68000/10
     Pseudo-Op |BYTE    WORD    LONG    LONG      non-PC relative
               +-------------------------------------------------
          jbsr |bsrs    bsr     bsrl    jsr       jsr
           jra |bras    bra     bral    jmp       jmp
     *     jXX |bXXs    bXX     bXXl    bNXs;jmpl bNXs;jmp
     *    dbXX |dbXX    dbXX        dbXX; bra; jmpl
     *    fjXX |fbXXw   fbXXw   fbXXl             fbNXw;jmp

     XX: condition
     NX: negative of condition XX

*---see full description below

jbsr
jra
     These are the simplest jump pseudo-operations; they always map to one particular machine instruction, depending on the displacement to the branch target.

jXX
     Here, jXX stands for an entire family of pseudo-operations, where XX is a conditional branch or condition-code test.  The full list of pseudo-ops in this family is:

           jhi   jls   jcc   jcs   jne   jeq   jvc
           jvs   jpl   jmi   jge   jlt   jgt   jle

     For the cases of non-PC relative displacements and long displacements on the 68000 or 68010, _AS__ will issue a longer code fragment in terms of NX, the opposite condition to XX.  For example, for the non-PC relative case:

              jXX foo

     gives

               bNXs oof
               jmp foo
           oof:

dbXX
     The full family of pseudo-operations covered here is

           dbhi   dbls   dbcc   dbcs   dbne   dbeq   dbvc
           dbvs   dbpl   dbmi   dbge   dblt   dbgt   dble
           dbf    dbra   dbt

     Other than for word and byte displacements, when the source reads dbXX foo, _AS__ will emit

               dbXX oo1
               bra oo2
           oo1:jmpl foo
           oo2:

fjXX
     This family includes

           fjne   fjeq   fjge   fjlt   fjgt   fjle   fjf
           fjt    fjgl   fjgle  fjnge  fjngl  fjngle fjngt
           fjnle  fjnlt  fjoge  fjogl  fjogt  fjole  fjolt
           fjor   fjseq  fjsf   fjsne  fjst   fjueq  fjuge
           fjugt  fjule  fjult  fjun

     For branch targets that are not PC relative, _AS__ emits

               fbNX oof
               jmp foo
           oof:

     when it encounters fjXX foo.

_CHAPSEC__(2+_GENERIC__) Special Characters

The immediate character is # for Sun compatibility.  The line-comment character is |.  If a # appears at the beginning of a line, it is treated as a comment unless it looks like # line file, in which case it is treated normally.

_if__(0)

32x32
=====

Options
=======

The 32x32 version of _AS__ accepts a -m32032 option to specify thiat it is compiling for a 32032 processor, or a -m32532 to specify that it is compiling for a 32532 option. The default (if neither is specified) is chosen when the assembler is compiled.

Syntax
------

I don't know anything about the 32x32 syntax assembled by _AS__.  Someone who undersands the processor (I've never seen one) and the possible syntaxes should write this section.

Floating Point
--------------

The 32x32 uses IEEE floating point numbers, but _AS__ will only create single or double precision values.  I don't know if the 32x32 understands extended precision numbers.

32x32 Machine Directives
------------------------

The 32x32 has no machine dependent directives.

_fi__(0) _if__(_SPARC__)
_CHAPSEC__(0+_GENERIC__) SPARC Dependent Features

_CHAPSEC__(1+_GENERIC__) Options

The Sparc has no machine dependent options.

_CHAPSEC__(1+_GENERIC__) Floating Point

The Sparc uses IEEE floating-point numbers.

_CHAPSEC__(1+_GENERIC__) Sparc Machine Directives

The Sparc version of _AS__ supports the following additional machine directives:

.common
     This must be followed by a symbol name, a positive number, and "bss".  This behaves somewhat like .comm, but the syntax is different.

.half
     This is functionally identical to .short.

.proc
     This directive is ignored.  Any text following it on the same line is also ignored.

.reserve
     This must be followed by a symbol name, a positive number, and "bss".  This behaves somewhat like .lcomm, but the syntax is different.

.seg
     This must be followed by "text", "data", or "data1".  It behaves like .text, .data, or .data 1.

.skip
     This is functionally identical to the .space directive.

.word
     On the Sparc, the .word directive produces 32 bit values, instead of the 16 bit values it produces on many other machines.

_fi__(_SPARC__) _if__(_I80386__)
_CHAPSEC__(0+_GENERIC__) 80386 Dependent Features

_CHAPSEC__(1+_GENERIC__) Options

The 80386 has no machine dependent options.

_CHAPSEC__(1+_GENERIC__) AT&T Syntax versus Intel Syntax

In order to maintain compatibility with the output of _GCC__, _AS__ supports AT&T System V/386 assembler syntax.  This is quite different from Intel syntax.  We mention these differences because almost all 80386 documents used only Intel syntax.  Notable differences between the two syntaxes are:

  * AT&T immediate operands are preceded by $; Intel immediate operands are undelimited (Intel push 4 is AT&T pushl $4). AT&T register operands are preceded by %; Intel register operands are undelimited.  AT&T absolute (as opposed to PC relative) jump/call operands are prefixed by *; they are undelimited in Intel syntax.

  * AT&T and Intel syntax use the opposite order for source and destination operands.  Intel add eax, 4 is addl $4, %eax.  The source, dest convention is maintained for compatibility with previous Unix assemblers.

  * In AT&T syntax the size of memory operands is determined from the last character of the opcode name.  Opcode suffixes of b, w, and l specify byte (8-bit), word (16-bit), and long (32-bit) memory references.  Intel syntax accomplishes this by prefixes memory operands (not the opcodes themselves) with byte ptr, word ptr, and dword ptr.  Thus, Intel mov al, byte ptr FOO is movb FOO, %al in AT&T syntax.

  * Immediate form long jumps and calls are lcall/ljmp $SECTION, $OFFSET in AT&T syntax; the Intel syntax is call/jmp far SECTION:OFFSET.  Also, the far return instruction is lret $STACK-ADJUST in AT&T syntax; Intel syntax is ret far STACK-ADJUST.

  * The AT&T assembler does not provide support for multiple section programs.  Unix style systems expect all programs to be single sections.

_CHAPSEC__(1+_GENERIC__) Opcode Naming

Opcode names are suffixed with one character modifiers which specify the size of operands.  The letters b, w, and l specify byte, word, and long operands.  If no suffix is specified by an instruction and it contains no memory operands then _AS__ tries to fill in the missing suffix based on the destination register operand (the last one by convention).  Thus, mov %ax, %bx is equivalent to movw %ax, %bx; also, mov $1, %bx is equivalent to movw $1, %bx.  Note that this is incompatible with the AT&T Unix assembler which assumes that a missing opcode suffix implies long operand size.  (This incompatibility does not affect compiler output since compilers always explicitly specify the opcode suffix.)

Almost all opcodes 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 from and a size to zero extend to.  This is accomplished by using two opcode suffixes in AT&T syntax.  Base names for sign extend and zero extend are movs... and movz... in AT&T syntax (movsx and movzx in Intel syntax).  The opcode suffixes are tacked on to this base name, the from suffix before the to suffix.  Thus, movsbl %al, %edx is AT&T syntax for ``move sign extend from %al to %edx.''  Possible suffixes, thus, are bl (from byte to long), bw (from byte to word), and wl (from word to long).

The Intel-syntax conversion instructions

  * cbw --- sign-extend byte in %al to word in %ax,

  * cwde --- sign-extend word in %ax to long in %eax,

  * cwd --- sign-extend word in %ax to long in %dx:%ax,

  * cdq --- sign-extend dword in %eax to quad in %edx:%eax,

are called cbtw, cwtl, cwtd, and cltd in AT&T naming.  _AS__ accepts either naming for these instructions.

Far call/jump instructions are lcall and ljmp in AT&T syntax, but are call far and jump far in Intel convention.

_CHAPSEC__(1+_GENERIC__) Register Naming

Register operands are always prefixes with %.  The 80386 registers consist of

  * the 8 32-bit registers %eax (the accumulator), %ebx, %ecx, %edx, %edi, %esi, %ebp (the frame pointer), and %esp (the stack pointer).

  * the 8 16-bit low-ends of these: %ax, %bx, %cx, %dx, %di, %si, %bp, and %sp.

  * the 8 8-bit registers: %ah, %al, %bh, %bl, %ch, %cl, %dh, and %dl (These are the high-bytes and low-bytes of %ax, %bx, %cx, and %dx)

  * the 6 section registers %cs (code section), %ds (data section), %ss (stack section), %es, %fs, and %gs.

  * the 3 processor control registers %cr0, %cr2, and %cr3.

  * the 6 debug registers %db0, %db1, %db2, %db3, %db6, and %db7.

  * the 2 test registers %tr6 and %tr7.

  * the 8 floating point register stack %st or equivalently %st(0), %st(1), %st(2), %st(3), %st(4), %st(5), %st(6), and %st(7).

_CHAPSEC__(1+_GENERIC__) Opcode Prefixes

Opcode prefixes are used to modify the following opcode.  They are used to repeat string instructions, to provide section overrides, to perform bus lock operations, and to give operand and address size (16-bit operands are specified in an instruction by prefixing what would normally be 32-bit operands with a ``operand size'' opcode prefix). Opcode prefixes are usually given as single-line instructions with no operands, and must directly precede the instruction they act upon.  For example, the scas (scan string) instruction is repeated with:

             repne
             scas

Here is a list of opcode prefixes:

  * Section override prefixes cs, ds, ss, es, fs, gs.  These are automatically added by specifying using the SECTION:MEMORY-OPERAND form for memory references.

  * Operand/Address size prefixes data16 and addr16 change 32-bit operands/addresses into 16-bit operands/addresses.  Note that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes) are not supported (yet).

  * The bus lock prefix lock inhibits interrupts during execution of the instruction it precedes.  (This is only valid with certain instructions; see a 80386 manual for details).

  * The wait for coprocessor prefix wait waits for the coprocessor to complete the current instruction.  This should never be needed for the 80386/80387 combination.

  * The rep, repe, and repne prefixes are added to string instructions to make them repeat %ecx times.

_CHAPSEC__(1+_GENERIC__) Memory References

An Intel syntax indirect memory reference of the form

     SECTION:[BASE + INDEX*SCALE + DISP]

is translated into the AT&T syntax

     SECTION:DISP(BASE, INDEX, SCALE)

where BASE and INDEX are the optional 32-bit base and index registers, DISP is the optional displacement, and SCALE, taking the values 1, 2, 4, and 8, multiplies INDEX to calculate the address of the operand.  If no SCALE is specified, SCALE is taken to be 1.  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 must have be preceded by a %.  If you specify a section override which coincides with the default section register, _AS__ will 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.

Here are some examples of Intel and AT&T style memory references:

AT&T: -4(%ebp), Intel:  [ebp - 4]
     BASE is %ebp; DISP is -4. SECTION is missing, and the default section is used (%ss for addressing with %ebp as the base register).  INDEX, SCALE are both missing.

AT&T: foo(,%eax,4), Intel: [foo + eax*4]
     INDEX is %eax (scaled by a SCALE 4); DISP is foo.  All other fields are missing.  The section register here defaults to %ds.

AT&T: foo(,1); Intel [foo]
     This uses the value pointed to by foo as a memory operand. Note that BASE and INDEX are both missing, but there is only one ,.  This is a syntactic exception.

AT&T: %gs:foo; Intel gs:foo
     This selects the contents of the variable foo with section register SECTION being %gs.

Absolute (as opposed to PC relative) call and jump operands must be prefixed with *.  If no * is specified, _AS__ will always choose PC relative addressing for jump/call labels.

Any instruction that has a memory operand must specify its size (byte, word, or long) with an opcode suffix (b, w, or l, respectively).

_CHAPSEC__(1+_GENERIC__) 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 (32-bit) displacement is used.  We do not support word (16-bit) displacement jumps (i.e. prefixing the jump instruction with the addr16 opcode prefix), since the 80386 insists upon masking %eip to 16 bits after the word displacement is added.

Note that the jcxz, jecxz, loop, loopz, loope, loopnz and loopne instructions only come in byte displacements, so that it is possible that use of these instructions (_GCC__ does not use them) will cause the assembler to print an error message (and generate incorrect code).  The AT&T 80386 assembler tries to get around this problem by expanding jcxz foo to

              jcxz cx_zero
              jmp cx_nonzero
     cx_zero: jmp foo
     cx_nonzero:

_CHAPSEC__(1+_GENERIC__) 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 opcode suffix and a constructor associated with it.  Opcode suffixes specify operand's data types.  Constructors build these data types into memory.

  * Floating point constructors are .float or .single, .double, and .tfloat for 32-, 64-, and 80-bit formats. These correspond to opcode suffixes s, l, and t. t stands for temporary real, and that the 80387 only supports this format via the fldt (load temporary real to stack top) and fstpt (store temporary real and pop stack) instructions.

  * Integer constructors are .word, .long or .int, and .quad for the 16-, 32-, and 64-bit integer formats.  The corresponding opcode suffixes are s (single), l (long), and q (quad).  As with the temporary real format the 64-bit q format is only present in the fildq (load quad integer to stack top) and fistpq (store quad integer and pop stack) instructions.

Register to register operations do not require opcode suffixes, so that fst %st, %st(1) is equivalent to fstl %st, %st(1).

Since the 80387 automatically synchronizes with the 80386 fwait instructions are almost never needed (this is not the case for the 80286/80287 and 8086/8087 combinations).  Therefore, _AS__ suppresses the fwait instruction whenever it is implicitly selected by one of the fn... instructions.  For example, fsave and fnsave are treated identically.  In general, all the fn... instructions are made equivalent to f... instructions.  If fwait is desired it must be explicitly coded.

_CHAPSEC__(1+_GENERIC__) Notes

There is some trickery concerning the mul and imul instructions that deserves mention.  The 16-, 32-, and 64-bit expanding multiplies (base opcode 0xf6; extension 4 for mul and 5 for imul) can be output only in the one operand form.  Thus, imul %ebx, %eax does not select the expanding multiply; the expanding multiply would clobber the %edx register, and this would confuse _GCC__ output.  Use imul %ebx to get the 64-bit product in %edx:%eax.

We have added a two operand form of 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 %eax by 69, for example, can be done with imul $69, %eax rather than imul $69, %eax, %eax.

_fi__(_I80386__) _if__(_Z8000__)
_CHAPSEC__(0+_GENERIC__) Z8000 Dependent Features

The Z8000 _AS__ supports both members of the Z8000 family: the unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with 24 bit addresses.

When the assembler is in unsegmented mode (specified with the unsegm directive), an address will take up one word (16 bit) sized register.  When the assembler is in segmented mode (specified with the segm directive), a 24-bit address takes up a long (32 bit) register.  See Assembler Directives for the Z8000, for a list of other Z8000 specific assembler directives.

_CHAPSEC__(1+_GENERIC__) Options

_AS__ has no additional command-line options for the Zilog Z8000 family.

_CHAPSEC__(1+_GENERIC__) Syntax

_CHAPSEC__(2+_GENERIC__) Special Characters

! is the line comment character.

You can use ; instead of a newline to separate statements.

_CHAPSEC__(2+_GENERIC__) Register Names

The Z8000 has sixteen 16 bit registers, numbered 0 to 15.  You can refer to different sized groups of registers by register number, with the prefix r for 16 bit registers, rr for 32 bit registers and rq for 64 bit registers.  You can also refer to the contents of the first eight (of the sixteen 16 bit registers) by bytes.  They are named rNh and rNl.

     byte registers
     r0l r0h r1h r1l r2h r2l r3h r3l
     r4h r4l r5h r5l r6h r6l r7h r7l

     word registers
     r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15

     long word registers
     rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14

     quad word registers
     rq0 rq4 rq8 rq12

_CHAPSEC__(2+_GENERIC__) Addressing Modes

_AS__ understands the following addressing modes for the Z8000:

rN
     Register direct

@rN
     Indirect register

ADDR
     Direct: the 16 bit or 24 bit address (depending on whether the assembler is in segmented or unsegmented mode) of the operand is in the instruction.

address(rN)
     Indexed: the 16 or 24 bit address is added to the 16 bit register to produce the final address in memory of the operand.

rN(#IMM)
     Base Address: the 16 or 24 bit register is added to the 16 bit sign extended immediate displacement to produce the final address in memory of the operand.

rN(rM)
     Base Index: the 16 or 24 bit register rN is added to the sign extended 16 bit index register rM to produce the final address in memory of the operand.

#XX
     Immediate data XX.

_CHAPSEC__(1+_GENERIC__) Assembler Directives for the Z8000

The Z8000 port of _AS__ includes these additional assembler directives, for compatibility with other Z8000 assemblers.  As shown, these do not begin with . (unlike the ordinary _AS__ directives).

segm
     Generates code for the segmented Z8001.

unsegm
     Generates code for the unsegmented Z8002.

name
     Synonym for .file

global
     Synonum for .global

wval
     Synonym for .word

lval
     Synonym for .long

bval
     Synonym for .byte

sval
     Assemble a string.  sval expects one string literal, delimited by single quotes.  It assembles each byte of the string into consecutive addresses.  You can use the escape sequence %XX (where XX represents a two-digit hexadecimal number) to represent the character whose ASCII value is XX.  Use this feature to describe single quote and other characters that may not appear in string literals as themselves.  For example, the C statement char *a = "he said \"it's 50% off\""; is represented in Z8000 assembly language (shown with the assembler output in hex at the left) as

          68652073    sval    'he said %22it%27s 50%25 off%22%00'
          61696420
          22697427
          73203530
          25206F66
          662200

rsect
     synonym for .section

block
     synonym for .space

even
     synonym for .align 1

_CHAPSEC__(1+_GENERIC__) Opcodes

For detailed information on the Z8000 machine instruction set, see Z8000 Technical Manual.

The following table summarizes the opcodes and their arguments:

                 rs   16 bit source register
                 rd   16 bit destination register
                 rbs   8 bit source register
                 rbd   8 bit destination register
                 rrs   32 bit source register
                 rrd   32 bit destination register
                 rqs   64 bit source register
                 rqd   64 bit destination register
                 addr 16/24 bit address
                 imm  immediate data

     adc rd,rs               clrb addr               cpsir @rd,@rs,rr,cc
     adcb rbd,rbs            clrb addr(rd)           cpsirb @rd,@rs,rr,cc
     add rd,@rs              clrb rbd                dab rbd
     add rd,addr             com @rd                 dbjnz rbd,disp7
     add rd,addr(rs)         com addr                dec @rd,imm4m1
     add rd,imm16            com addr(rd)            dec addr(rd),imm4m1
     add rd,rs               com rd                  dec addr,imm4m1
     addb rbd,@rs            comb @rd                dec rd,imm4m1
     addb rbd,addr           comb addr               decb @rd,imm4m1
     addb rbd,addr(rs)       comb addr(rd)           decb addr(rd),imm4m1
     addb rbd,imm8           comb rbd                decb addr,imm4m1
     addb rbd,rbs            comflg flags            decb rbd,imm4m1
     addl rrd,@rs            cp @rd,imm16            di i2
     addl rrd,addr           cp addr(rd),imm16       div rrd,@rs
     addl rrd,addr(rs)       cp addr,imm16           div rrd,addr
     addl rrd,imm32          cp rd,@rs               div rrd,addr(rs)
     addl rrd,rrs            cp rd,addr              div rrd,imm16
     and rd,@rs              cp rd,addr(rs)          div rrd,rs
     and rd,addr             cp rd,imm16             divl rqd,@rs
     and rd,addr(rs)         cp rd,rs                divl rqd,addr
     and rd,imm16            cpb @rd,imm8            divl rqd,addr(rs)
     and rd,rs               cpb addr(rd),imm8       divl rqd,imm32
     andb rbd,@rs            cpb addr,imm8           divl rqd,rrs
     andb rbd,addr           cpb rbd,@rs             djnz rd,disp7
     andb rbd,addr(rs)       cpb rbd,addr            ei i2
     andb rbd,imm8           cpb rbd,addr(rs)        ex rd,@rs
     andb rbd,rbs            cpb rbd,imm8            ex rd,addr
     bit @rd,imm4            cpb rbd,rbs             ex rd,addr(rs)
     bit addr(rd),imm4       cpd rd,@rs,rr,cc        ex rd,rs
     bit addr,imm4           cpdb rbd,@rs,rr,cc      exb rbd,@rs
     bit rd,imm4             cpdr rd,@rs,rr,cc       exb rbd,addr
     bit rd,rs               cpdrb rbd,@rs,rr,cc     exb rbd,addr(rs)
     bitb @rd,imm4           cpi rd,@rs,rr,cc        exb rbd,rbs
     bitb addr(rd),imm4      cpib rbd,@rs,rr,cc      ext0e imm8
     bitb addr,imm4          cpir rd,@rs,rr,cc       ext0f imm8
     bitb rbd,imm4           cpirb rbd,@rs,rr,cc     ext8e imm8
     bitb rbd,rs             cpl rrd,@rs             ext8f imm8
     bpt                     cpl rrd,addr            exts rrd
     call @rd                cpl rrd,addr(rs)        extsb rd
     call addr               cpl rrd,imm32           extsl rqd
     call addr(rd)           cpl rrd,rrs             halt
     calr disp12             cpsd @rd,@rs,rr,cc      in rd,@rs
     clr @rd                 cpsdb @rd,@rs,rr,cc     in rd,imm16
     clr addr                cpsdr @rd,@rs,rr,cc     inb rbd,@rs
     clr addr(rd)            cpsdrb @rd,@rs,rr,cc    inb rbd,imm16
     clr rd                  cpsi @rd,@rs,rr,cc      inc @rd,imm4m1
     clrb @rd                cpsib @rd,@rs,rr,cc     inc addr(rd),imm4m1
     inc addr,imm4m1         ldb rbd,rs(rx)          mult rrd,addr(rs)
     inc rd,imm4m1           ldb rd(imm16),rbs       mult rrd,imm16
     incb @rd,imm4m1         ldb rd(rx),rbs          mult rrd,rs
     incb addr(rd),imm4m1    ldctl ctrl,rs           multl rqd,@rs
     incb addr,imm4m1        ldctl rd,ctrl           multl rqd,addr
     incb rbd,imm4m1         ldd @rs,@rd,rr          multl rqd,addr(rs)
     ind @rd,@rs,ra          lddb @rs,@rd,rr         multl rqd,imm32
     indb @rd,@rs,rba        lddr @rs,@rd,rr         multl rqd,rrs
     inib @rd,@rs,ra         lddrb @rs,@rd,rr        neg @rd
     inibr @rd,@rs,ra        ldi @rd,@rs,rr          neg addr
     iret                    ldib @rd,@rs,rr         neg addr(rd)
     jp cc,@rd               ldir @rd,@rs,rr         neg rd
     jp cc,addr              ldirb @rd,@rs,rr        negb @rd
     jp cc,addr(rd)          ldk rd,imm4             negb addr
     jr cc,disp8             ldl @rd,rrs             negb addr(rd)
     ld @rd,imm16            ldl addr(rd),rrs        negb rbd
     ld @rd,rs               ldl addr,rrs            nop
     ld addr(rd),imm16       ldl rd(imm16),rrs       or rd,@rs
     ld addr(rd),rs          ldl rd(rx),rrs          or rd,addr
     ld addr,imm16           ldl rrd,@rs             or rd,addr(rs)
     ld addr,rs              ldl rrd,addr            or rd,imm16
     ld rd(imm16),rs         ldl rrd,addr(rs)        or rd,rs
     ld rd(rx),rs            ldl rrd,imm32           orb rbd,@rs
     ld rd,@rs               ldl rrd,rrs             orb rbd,addr
     ld rd,addr              ldl rrd,rs(imm16)       orb rbd,addr(rs)
     ld rd,addr(rs)          ldl rrd,rs(rx)          orb rbd,imm8
     ld rd,imm16             ldm @rd,rs,n            orb rbd,rbs
     ld rd,rs                ldm addr(rd),rs,n       out @rd,rs
     ld rd,rs(imm16)         ldm addr,rs,n           out imm16,rs
     ld rd,rs(rx)            ldm rd,@rs,n            outb @rd,rbs
     lda rd,addr             ldm rd,addr(rs),n       outb imm16,rbs
     lda rd,addr(rs)         ldm rd,addr,n           outd @rd,@rs,ra
     lda rd,rs(imm16)        ldps @rs                outdb @rd,@rs,rba
     lda rd,rs(rx)           ldps addr               outib @rd,@rs,ra
     ldar rd,disp16          ldps addr(rs)           outibr @rd,@rs,ra
     ldb @rd,imm8            ldr disp16,rs           pop @rd,@rs
     ldb @rd,rbs             ldr rd,disp16           pop addr(rd),@rs
     ldb addr(rd),imm8       ldrb disp16,rbs         pop addr,@rs
     ldb addr(rd),rbs        ldrb rbd,disp16         pop rd,@rs
     ldb addr,imm8           ldrl disp16,rrs         popl @rd,@rs
     ldb addr,rbs            ldrl rrd,disp16         popl addr(rd),@rs
     ldb rbd,@rs             mbit                    popl addr,@rs
     ldb rbd,addr            mreq rd                 popl rrd,@rs
     ldb rbd,addr(rs)        mres                    push @rd,@rs
     ldb rbd,imm8            mset                    push @rd,addr
     ldb rbd,rbs             mult rrd,@rs            push @rd,addr(rs)
     ldb rbd,rs(imm16)       mult rrd,addr           push @rd,imm16
     push @rd,rs             set addr,imm4           subl rrd,imm32
     pushl @rd,@rs           set rd,imm4             subl rrd,rrs
     pushl @rd,addr          set rd,rs               tcc cc,rd
     pushl @rd,addr(rs)      setb @rd,imm4           tccb cc,rbd
     pushl @rd,rrs           setb addr(rd),imm4      test @rd
     res @rd,imm4            setb addr,imm4          test addr
     res addr(rd),imm4       setb rbd,imm4           test addr(rd)
     res addr,imm4           setb rbd,rs             test rd
     res rd,imm4             setflg imm4             testb @rd
     res rd,rs               sinb rbd,imm16          testb addr
     resb @rd,imm4           sinb rd,imm16           testb addr(rd)
     resb addr(rd),imm4      sind @rd,@rs,ra         testb rbd
     resb addr,imm4          sindb @rd,@rs,rba       testl @rd
     resb rbd,imm4           sinib @rd,@rs,ra        testl addr
     resb rbd,rs             sinibr @rd,@rs,ra       testl addr(rd)
     resflg imm4             sla rd,imm8             testl rrd
     ret cc                  slab rbd,imm8           trdb @rd,@rs,rba
     rl rd,imm1or2           slal rrd,imm8           trdrb @rd,@rs,rba
     rlb rbd,imm1or2         sll rd,imm8             trib @rd,@rs,rbr
     rlc rd,imm1or2          sllb rbd,imm8           trirb @rd,@rs,rbr
     rlcb rbd,imm1or2        slll rrd,imm8           trtdrb @ra,@rb,rbr
     rldb rbb,rba            sout imm16,rs           trtib @ra,@rb,rr
     rr rd,imm1or2           soutb imm16,rbs         trtirb @ra,@rb,rbr
     rrb rbd,imm1or2         soutd @rd,@rs,ra        trtrb @ra,@rb,rbr
     rrc rd,imm1or2          soutdb @rd,@rs,rba      tset @rd
     rrcb rbd,imm1or2        soutib @rd,@rs,ra       tset addr
     rrdb rbb,rba            soutibr @rd,@rs,ra      tset addr(rd)
     rsvd36                  sra rd,imm8             tset rd
     rsvd38                  srab rbd,imm8           tsetb @rd
     rsvd78                  sral rrd,imm8           tsetb addr
     rsvd7e                  srl rd,imm8             tsetb addr(rd)
     rsvd9d                  srlb rbd,imm8           tsetb rbd
     rsvd9f                  srll rrd,imm8           xor rd,@rs
     rsvdb9                  sub rd,@rs              xor rd,addr
     rsvdbf                  sub rd,addr             xor rd,addr(rs)
     sbc rd,rs               sub rd,addr(rs)         xor rd,imm16
     sbcb rbd,rbs            sub rd,imm16            xor rd,rs
     sc imm8                 sub rd,rs               xorb rbd,@rs
     sda rd,rs               subb rbd,@rs            xorb rbd,addr
     sdab rbd,rs             subb rbd,addr           xorb rbd,addr(rs)
     sdal rrd,rs             subb rbd,addr(rs)       xorb rbd,imm8
     sdl rd,rs               subb rbd,imm8           xorb rbd,rbs
     sdlb rbd,rs             subb rbd,rbs            xorb rbd,rbs
     sdll rrd,rs             subl rrd,@rs
     set @rd,imm4            subl rrd,addr
     set addr(rd),imm4       subl rrd,addr(rs)

_fi__(_Z8000__) _if__(0)

Maintaining the Assembler
*************************

[[this chapter is still being built]]

Design
======

We had these goals, in descending priority:

Accuracy.
     For every program composed by a compiler, _AS__ should emit ``correct'' code.  This leaves some latitude in choosing addressing modes, order of relocation_info structures in the object file, etc.

Speed, for usual case.
     By far the most common use of _AS__ will be assembling compiler emissions.

Upward compatibility for existing assembler code.
     Well ... we don't support Vax bit fields but everything else seems to be upward compatible.

Readability.
     The code should be maintainable with few surprises.  (JF: ha!)

We assumed that disk I/O was slow and expensive while memory was fast and access to memory was cheap.  We expect the in-memory data structures to be less than 10 times the size of the emitted object file.  (Contrast this with the C compiler where in-memory structures might be 100 times object file size!) This suggests:

  * Try to read the source file from disk only one time.  For other reasons, we keep large chunks of the source file in memory during assembly so this is not a problem.  Also the assembly algorithm should only scan the source text once if the compiler composed the text according to a few simple rules.

  * Emit the object code bytes only once.  Don't store values and then backpatch later.

  * Build the object file in memory and do direct writes to disk of large buffers.

RMS suggested a one-pass algorithm which seems to work well.  By not parsing text during a second pass considerable time is saved on large programs (e.g. the sort of C program yacc would emit).

It happened that the data structures needed to emit relocation information to the object file were neatly subsumed into the data structures that do backpatching of addresses after pass 1.

Many of the functions began life as re-usable modules, loosely connected.  RMS changed this to gain speed.  For example, input parsing routines which used to work on pre-sanitized strings now must parse raw data.  Hence they have to import knowledge of the assemblers' comment conventions etc.

Deprecated Feature(?)s
======================

We have stopped supporting some features:

  * .org statements must have defined expressions.

  * Vax Bit fields (: operator) are entirely unsupported.

It might be a good idea to not support these features in a future release:

  * # should begin a comment, even in column 1.

  * Why support the logical line & file concept any more?

  * Subsections are a good candidate for flushing. Depends on which compilers need them I guess.

Bugs, Ideas, Further Work
=========================

Clearly the major improvement is DON'T USE A TEXT-READING ASSEMBLER for the back end of a compiler.  It is much faster to interpret binary gobbledygook from a compiler's tables than to ask the compiler to write out human-readable code just so the assembler can parse it back to binary.

Assuming you use _AS__ for human written programs: here are some ideas:

  * Document (here) APP.

  * Take advantage of knowing no spaces except after opcode to speed up _AS__.  (Modify app.c to flush useless spaces: only keep space/tabs at begin of line or between 2 symbols.)

  * Put pointers in this documentation to a.out documentation.

  * Split the assembler into parts so it can gobble direct binary from e.g. cc.  It is silly forcc to compose text just so _AS__ can parse it back to binary.

  * Rewrite hash functions: I want a more modular, faster library.

  * Clean up LOTS of code.

  * Include all the non-.c files in the maintenance chapter.

  * Document flonums.

  * Implement flonum short literals.

  * Change all talk of expression operands to expression quantities, or perhaps to expression arguments.

  * Implement pass 2.

  * Whenever a .text or .data statement is seen, we close of the current frag with an imaginary .fill 0.  This is because we only have one obstack for frags, and we can't grow new frags for a new subsection, then go back to the old subsection and append bytes to the old frag.  All this nonsense goes away if we give each subsection its own obstack.  It makes code simpler in about 10 places, but nobody has bothered to do it because C compiler output rarely changes subsections (compared to ending frags with relaxable addresses, which is common).

Sources
=======

Here is a list of the source files in the _AS__ directory.

app.c
     This contains the pre-processing phase, which deletes comments, handles whitespace, etc.  This was recently re-written, since app used to be a separate program, but RMS wanted it to be inline.

append.c
     This is a subroutine to append a string to another string returning a pointer just after the last char appended.  (JF:  All these little routines should probably all be put in one file.)

as.c
     Here you will find the main program of the assembler _AS__.

expr.c
     This is a branch office of read.c.  This understands expressions, arguments.  Inside _AS__, arguments are called (expression) operands.  This is confusing, because we also talk (elsewhere) about instruction operands.  Also, expression operands are called quantities explicitly to avoid confusion with instruction operands.  What a mess.

frags.c
     This implements the frag concept.  Without frags, finding the right size for branch instructions would be a lot harder.

hash.c
     This contains the symbol table, opcode table etc. hashing functions.

hex_value.c
     This is a table of values of digits, for use in atoi() type functions.  Could probably be flushed by using calls to strtol(), or something similar.

input-file.c
     This contains Operating system dependent source file reading routines.  Since error messages often say where we are in reading the source file, they live here too.  Since _AS__ is intended to run under GNU and Unix only, this might be worth flushing.  Anyway, almost all C compilers support stdio.

input-scrub.c
     This deals with calling the pre-processor (if needed) and feeding the chunks back to the rest of the assembler the right way.

messages.c
     This contains operating system independent parts of fatal and warning message reporting.  See append.c above.

output-file.c
     This contains operating system dependent functions that write an object file for _AS__.  See input-file.c above.

read.c
     This implements all the directives of _AS__.  This also deals with passing input lines to the machine dependent part of the assembler.

strstr.c
     This is a C library function that isn't in most C libraries yet. See append.c above.

subsegs.c
     This implements subsections.

symbols.c
     This implements symbols.

write.c
     This contains the code to perform relaxation, and to write out the object file.  It is mostly operating system independent, but different OSes have different object file formats in any case.

xmalloc.c
     This implements malloc() or bust.  See append.c above.

xrealloc.c
     This implements realloc() or bust.  See append.c above.

atof-generic.c
     The following files were taken from a machine-independent subroutine library for manipulating floating point numbers and very large integers.

     atof-generic.c turns a string into a flonum internal format floating-point number.

flonum-const.c
     This contains some potentially useful floating point numbers in flonum format.

flonum-copy.c
     This copies a flonum.

flonum-multip.c
     This multiplies two flonums together.

bignum-copy.c
     This copies a bignum.

Here is a table of all the machine-specific files (this includes both source and header files).  Typically, there is a MACHINE.c file, a MACHINE-opcode.h file, and an atof-MACHINE.c file.  The MACHINE-opcode.h file should be identical to the one used by GDB (which uses it for disassembly.)

atof-ieee.c
     This contains code to turn a flonum into a ieee literal constant. This is used by tye 680x0, 32x32, sparc, and i386 versions of _AS__.

i386-opcode.h
     This is the opcode-table for the i386 version of the assembler.

i386.c
     This contains all the code for the i386 version of the assembler.

i386.h
     This defines constants and macros used by the i386 version of the assembler.

m-generic.h
     generic 68020 header file.  To be linked to m68k.h on a non-sun3, non-hpux system.

m-sun2.h
     68010 header file for Sun2 workstations.  Not well tested.  To be linked to m68k.h on a sun2.  (See also -DSUN_ASM_SYNTAX in the Makefile.)

m-sun3.h
     68020 header file for Sun3 workstations.  To be linked to m68k.h before compiling on a Sun3 system.  (See also -DSUN_ASM_SYNTAX in the Makefile.)

m-hpux.h
     68020 header file for a HPUX (system 5?) box.  Which box, which version of HPUX, etc?  I don't know.

m68k.h
     A hard- or symbolic- link to one of m-generic.h, m-hpux.h or m-sun3.h depending on which kind of 680x0 you are assembling for.   (See also -DSUN_ASM_SYNTAX in the Makefile.)

m68k-opcode.h
     Opcode table for 68020.  This is now a link to the opcode table in the GDB source directory.

m68k.c
     All the mc680x0 code, in one huge, slow-to-compile file.

ns32k.c
     This contains the code for the ns32032/ns32532 version of the assembler.

ns32k-opcode.h
     This contains the opcode table for the ns32032/ns32532 version of the assembler.

vax-inst.h
     Vax specific file for describing Vax operands and other Vax-ish things.

vax-opcode.h
     Vax opcode table.

vax.c
     Vax specific parts of _AS__.  Also includes the former files vax-ins-parse.c, vax-reg-parse.c and vip-op.c.

atof-vax.c
     Turns a flonum into a Vax constant.

vms.c
     This file contains the special code needed to put out a VMS style object file for the Vax.

Here is a list of the header files in the source directory. (Warning:  This section may not be very accurate.  I didn't write the header files; I just report them.)  Also note that I think many of these header files could be cleaned up or eliminated.

a.out.h
     This describes the structures used to create the binary header data inside the object file.  Perhaps we should use the one in /usr/include?

as.h
     This defines all the globally useful things, and pulls in _0__<stdio.h>_1__ and _0__<assert.h>_1__.

bignum.h
     This defines macros useful for dealing with bignums.

expr.h
     Structure and macros for dealing with expression()

flonum.h
     This defines the structure for dealing with floating point numbers.  It #includes bignum.h.

frags.h
     This contains macro for appending a byte to the current frag.

hash.h
     Structures and function definitions for the hashing functions.

input-file.h
     Function headers for the input-file.c functions.

md.h
     structures and function headers for things defined in the machine dependent part of the assembler.

obstack.h
     This is the GNU systemwide include file for manipulating obstacks. Since nobody is running under real GNU yet, we include this file.

read.h
     Macros and function headers for reading in source files.

struct-symbol.h
     Structure definition and macros for dealing with the _AS__ internal form of a symbol.

subsegs.h
     structure definition for dealing with the numbered subsections of the text and data sections.

symbols.h
     Macros and function headers for dealing with symbols.

write.h
     Structure for doing section fixups.

Teaching the Assembler about a New Machine
******************************************

This chapter describes the steps required in order to make the assembler work with another machine's assembly language.  This chapter is not complete, and only describes the steps in the broadest terms.  You should look at the source for the currently supported machine in order to discover some of the details that aren't mentioned here.

You should create a new file called MACHINE.c, and add the appropriate lines to the file Makefile so that you can compile your new version of the assembler.  This should be straighforward; simply add lines similar to the ones there for the four current versions of the assembler.

If you want to be compatible with GDB, (and the current machine-dependent versions of the assembler), you should create a file called MACHINE-opcode.h which should contain all the information about the names of the machine instructions, their opcodes, and what addressing modes they support.  If you do this right, the assembler and GDB can share this file, and you'll only have to write it once.  Note that while you're writing _AS__, you may want to use an independent program (if you have access to one), to make sure that _AS__ is emitting the correct bytes.  Since _AS__ and GDB share the opcode table, an incorrect opcode table entry may make invalid bytes look OK when you disassemble them with GDB.

Functions You will Have to Write
================================

Your file MACHINE.c should contain definitions for the following functions and variables.  It will need to include some header files in order to use some of the structures defined in the machine-independent part of the assembler.  The needed header files are mentioned in the descriptions of the functions that will need them.

long omagic;
     This long integer holds the value to place at the beginning of the a.out file.  It is usually OMAGIC, except on machines that store additional information in the magic-number.

char comment_chars[];
     This character array holds the values of the characters that start a comment anywhere in a line.  Comments are stripped off automatically by the machine independent part of the assembler.  Note that the /* will always start a comment, and that only */ will end a comment started by */.

char line_comment_chars[];
     This character array holds the values of the chars that start a comment only if they are the first (non-whitespace) character on a line.  If the character # does not appear in this list, you may get unexpected results.  (Various machine-independent parts of the assembler treat the comments #APP and #NO_APP specially, and assume that lines that start with # are comments.)

char EXP_CHARS[];
     This character array holds the letters that can separate the mantissa and the exponent of a floating point number.  Typical values are e and E.

char FLT_CHARS[];
     This character array holds the letters that--when they appear immediately after a leading zero--indicate that a number is a floating-point number.  (Sort of how 0x indicates that a hexadecimal number follows.)

pseudo_typeS md_pseudo_table[];
     (PSEUDO_TYPES is defined in md.h) This array contains a list of the machine_dependent directives the assembler must support.  It contains the name of each pseudo op (Without the leading .), a pointer to a function to be called when that directive is encountered, and an integer argument to be passed to that function.

void md_begin(void)
     This function is called as part of the assembler's initialization.  It should do any initialization required by any of your other routines.

int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR)
     This routine is called once for each option on the command line that the machine-independent part of _AS__ does not understand.  This function should return non-zero if the option pointed to by OPTIONPTR is a valid option.  If it is not a valid option, this routine should return zero.  The variables ARGCPTR and ARGVPTR are provided in case the option requires a filename or something similar as an argument.  If the option is multi-character, OPTIONPTR should be advanced past the end of the option, otherwise every letter in the option will be treated as a separate single-character option.

void md_assemble(char *string)
     This routine is called for every machine-dependent non-directive line in the source file.  It does all the real work involved in reading the opcode, parsing the operands, etc.  STRING is a pointer to a null-terminated string, that comprises the input line, with all excess whitespace and comments removed.

void md_number_to_chars(char *outputPTR,long value,int nbytes)
     This routine is called to turn a C long int, short int, or char into the series of bytes that represents that number on the target machine.  OUTPUTPTR points to an array where the result should be stored; VALUE is the value to store; and NBYTES is the number of bytes in 'value' that should be stored.

void md_number_to_imm(char *outputPTR,long value,int nbytes)
     This routine is called to turn a C long int, short int, or char into the series of bytes that represent an immediate value on the target machine.  It is identical to the function md_number_to_chars, except on NS32K machines.

void md_number_to_disp(char *outputPTR,long value,int nbytes)
     This routine is called to turn a C long int, short int, or char into the series of bytes that represent an displacement value on the target machine.  It is identical to the function md_number_to_chars, except on NS32K machines.

void md_number_to_field(char *outputPTR,long value,int nbytes)
     This routine is identical to md_number_to_chars, except on NS32K machines.

void md_ri_to_chars(struct relocation_info *riPTR,ri)
     (struct relocation_info is defined in a.out.h) This routine emits the relocation info in RI in the appropriate bit-pattern for the target machine. The result should be stored in the location pointed to by RIPTR.  This routine may be a no-op unless you are attempting to do cross-assembly.

char *md_atof(char type,char *outputPTR,int *sizePTR)
     This routine turns a series of digits into the appropriate internal representation for a floating-point number. TYPE is a character from FLT_CHARS[] that describes what kind of floating point number is wanted; OUTPUTPTR is a pointer to an array that the result should be stored in; and SIZEPTR is a pointer to an integer where the size (in bytes) of the result should be stored.  This routine should return an error message, or an empty string (not (char *)0) for success.

int md_short_jump_size;
     This variable holds the (maximum) size in bytes of a short (16 bit or so) jump created by md_create_short_jump().  This variable is used as part of the broken-word feature, and isn't needed if the assembler is compiled with -DWORKING_DOT_WORD.

int md_long_jump_size;
     This variable holds the (maximum) size in bytes of a long (32 bit or so) jump created by md_create_long_jump().  This variable is used as part of the broken-word feature, and isn't needed if the assembler is compiled with -DWORKING_DOT_WORD.

void md_create_short_jump(char *resultPTR,long from_addr,
     long to_addr,fragS *frag,symbolS *to_symbol) This function emits a jump from FROM_ADDR to TO_ADDR in the array of bytes pointed to by RESULTPTR.  If this creates a type of jump that must be relocated, this function should call fix_new() with FRAG and TO_SYMBOL.  The jump emitted by this function may be smaller than MD_SHORT_JUMP_SIZE, but it must never create a larger one. (If it creates a smaller jump, the extra bytes of memory will not be used.)  This function is used as part of the broken-word feature, and isn't needed if the assembler is compiled with -DWORKING_DOT_WORD.

void md_create_long_jump(char *ptr,long from_addr,
     long to_addr,fragS *frag,symbolS *to_symbol) This function is similar to the previous function, md_create_short_jump(), except that it creates a long jump instead of a short one.  This function is used as part of the broken-word feature, and isn't needed if the assembler is compiled with -DWORKING_DOT_WORD.

int md_estimate_size_before_relax(fragS *fragPTR,int segment_type)
     This function does the initial setting up for relaxation.  This includes forcing references to still-undefined symbols to the appropriate addressing modes.

relax_typeS md_relax_table[];
     (relax_typeS is defined in md.h) This array describes the various machine dependent states a frag may be in before relaxation.  You will need one group of entries for each type of addressing mode you intend to relax.

void md_convert_frag(fragS *fragPTR)
     (FRAGS is defined in as.h) This routine does the required cleanup after relaxation. Relaxation has changed the type of the frag to a type that can reach its destination.  This function should adjust the opcode of the frag to use the appropriate addressing mode. FRAGPTR points to the frag to clean up.

void md_end(void)
     This function is called just before the assembler exits.  It need not free up memory unless the operating system doesn't do it automatically on exit.  (In which case you'll also have to track down all the other places where the assembler allocates space but never frees it.)

External Variables You will Need to Use
=======================================

You will need to refer to or change the following external variables from within the machine-dependent part of the assembler.

extern char flagseen[];
     This array holds non-zero values in locations corresponding to the options that were on the command line.  Thus, if the assembler was called with -W, FLAGSEEN['W'] would be non-zero.

extern fragS *frag_now;
     This pointer points to the current frag--the frag that bytes are currently being added to.  If nothing else, you will need to pass it as an argument to various machine-independent functions.  It is maintained automatically by the frag-manipulating functions; you should never have to change it yourself.

extern LITTLENUM_TYPE generic_bignum[];
     (LITTLENUM_TYPE is defined in bignum.h. This is where bignums--numbers larger than 32 bits--are returned when they are encountered in an expression. You will need to use this if you need to implement directives (or anything else) that must deal with these large numbers. Bignums are of segT SEG_BIG (defined in as.h, and have a positive X_add_number.  The X_add_number of a bignum is the number of LITTLENUMS in GENERIC_BIGNUM that the number takes up.

extern FLONUM_TYPE generic_floating_point_number;
     (FLONUM_TYPE is defined in flonum.h. The is where flonums--floating-point numbers within expressions--are returned.  Flonums are of segT SEG_BIG, and have a negative X_add_number. Flonums are returned in a generic format.  You will have to write a routine to turn this generic format into the appropriate floating-point format for your machine.

extern int need_pass_2;
     If this variable is non-zero, the assembler has encountered an expression that cannot be assembled in a single pass.  Since the second pass isn't implemented, this flag means that the assembler is punting, and is only looking for additional syntax errors.  (Or something like that.)

extern segT now_seg;
     This variable holds the value of the section the assembler is currently assembling into.

External functions will you need
================================

You will find the following external functions useful (or indispensable) when you're writing the machine-dependent part of the assembler.

char *frag_more(int bytes)
     This function allocates BYTES more bytes in the current frag (or starts a new frag, if it can't expand the current frag any more.)  for you to store some object-file bytes in.  It returns a pointer to the bytes, ready for you to store data in.

void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel)
     This function stores a relocation fixup to be acted on later. FRAG points to the frag the relocation belongs in; WHERE is the location within the frag where the relocation begins; SIZE is the size of the relocation, and is usually 1 (a single byte), 2 (sixteen bits), or 4 (a longword). The value ADD_SYMBOL - SUB_SYMBOL + OFFSET, is added to the byte(s) at _0__FRAG->LITERAL[WHERE]_1__.  If PCREL is non-zero, the address of the location is subtracted from the result.  A relocation entry is also added to the a.out file.  ADD_SYMBOL, SUB_SYMBOL, and/or OFFSET may be NULL.

char *frag_var(relax_stateT type, int max_chars, int var,
     relax_substateT subtype, symbolS *symbol, char *opcode) This function creates a machine-dependent frag of type TYPE (usually rs_machine_dependent). MAX_CHARS is the maximum size in bytes that the frag may grow by; VAR is the current size of the variable end of the frag; SUBTYPE is the sub-type of the frag.  The sub-type is used to index into MD_RELAX_TABLE[] during relaxation. SYMBOL is the symbol whose value should be used to when relax-ing this frag. OPCODE points into a byte whose value may have to be modified if the addressing mode used by this frag changes.  It typically points into the FR_LITERAL[] of the previous frag, and is used to point to a location that md_convert_frag(), may have to change.

void frag_wane(fragS *fragPTR)
     This function is useful from within md_convert_frag.  It changes a frag to type rs_fill, and sets the variable-sized piece of the frag to zero.  The frag will never change in size again.

segT expression(expressionS *retval)
     (SEGT is defined in as.h; EXPRESSIONS is defined in expr.h) This function parses the string pointed to by the external char pointer INPUT_LINE_POINTER, and returns the section-type of the expression.  It also stores the results in the EXPRESSIONS pointed to by RETVAL. INPUT_LINE_POINTER is advanced to point past the end of the expression.  (INPUT_LINE_POINTER is used by other parts of the assembler.  If you modify it, be sure to restore it to its original value.)

as_warn(char *message,...)
     If warning messages are disabled, this function does nothing. Otherwise, it prints out the current file name, and the current line number, then uses fprintf to print the MESSAGE and any arguments it was passed.

as_bad(char *message,...)
     This function should be called when _AS__ encounters conditions that are bad enough that _AS__ should not produce an object file, but should continue reading input and printing warning and bad error messages.

as_fatal(char *message,...)
     This function prints out the current file name and line number, prints the word FATAL:, then uses fprintf to print the MESSAGE and any arguments it was passed.  Then the assembler exits.  This function should only be used for serious, unrecoverable errors.

void float_const(int float_type)
     This function reads floating-point constants from the current input line, and calls md_atof to assemble them.  It is useful as the function to call for the directives .single, .double, .float, etc. FLOAT_TYPE must be a character from FLT_CHARS.

void demand_empty_rest_of_line(void);
     This function can be used by machine-dependent directives to make sure the rest of the input line is empty.  It prints a warning message if there are additional characters on the line.

long int get_absolute_expression(void)
     This function can be used by machine-dependent directives to read an absolute number from the current input line.  It returns the result.  If it isn't given an absolute expression, it prints a warning message and returns zero.

The concept of Frags
====================

This assembler works to optimize the size of certain addressing modes.  (e.g. branch instructions) This means the size of many pieces of object code cannot be determined until after assembly is finished.  (This means that the addresses of symbols cannot be determined until assembly is finished.)  In order to do this, _AS__ stores the output bytes as frags.

Here is the definition of a frag (from as.h)

     struct frag
     {
             long int fr_fix;
             long int fr_var;
             relax_stateT fr_type;
             relax_substateT fr_substate;
             unsigned long fr_address;
             long int fr_offset;
             struct symbol *fr_symbol;
             char *fr_opcode;
             struct frag *fr_next;
             char fr_literal[];
     }

fr_fix
     is the size of the fixed-size piece of the frag.

fr_var
     is the maximum (?) size of the variable-sized piece of the frag.

fr_type
     is the type of the frag. Current types are: rs_fill rs_align rs_org rs_machine_dependent

fr_substate
     This stores the type of machine-dependent frag this is.  (what kind of addressing mode is being used, and what size is being tried/will fit/etc.

fr_address
     FR_ADDRESS is only valid after relaxation is finished. Before relaxation, the only way to store an address is (pointer to frag containing the address) plus (offset into the frag).

fr_offset
     This contains a number, whose meaning depends on the type of the frag. for machine_dependent frags, this contains the offset from fr_symbol that the frag wants to go to.  Thus, for branch instructions it is usually zero.  (unless the instruction was jba foo+12  or something like that.)

fr_symbol
     for machine_dependent frags, this points to the symbol the frag needs to reach.

fr_opcode
     This points to the location in the frag (or in a previous frag) of the opcode for the instruction that caused this to be a frag. FR_OPCODE is needed if the actual opcode must be changed in order to use a different form of the addressing mode. (For example, if a conditional branch only comes in size tiny, a large-size branch could be implemented by reversing the sense of the test, and turning it into a tiny branch over a large jump. This would require changing the opcode.)

     FR_LITERAL is a variable-size array that contains the actual object bytes.  A frag consists of a fixed size piece of object data, (which may be zero bytes long), followed by a piece of object data whose size may not have been determined yet.  Other information includes the type of the frag (which controls how it is relaxed),

fr_next
     This is the next frag in the singly-linked list.  This is usually only needed by the machine-independent part of _AS__.

_fi__(0)

GNU GENERAL PUBLIC LICENSE
**************************

Version 2, June 1991

     Copyright © 1989, 1991 Free Software Foundation, Inc.
     675 Mass Ave, Cambridge, MA 02139, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

The licenses for most software are designed to take away your freedom to share and change it.  By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software---to make sure the software is free for all its users.  This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it.  (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.)  You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price.  Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have.  You must make sure that they, too, receive or can get the source code.  And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software.  If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents.  We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary.  To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

 1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License.  The ``Program'', below, refers to any such program or work, and a ``work based on the Program'' means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language.  (Hereinafter, translation is included without limitation in the term ``modification''.)  Each licensee is addressed as ``you''.

     Activities other than copying, distribution and modification are not covered by this License; they are outside its scope.  The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

 2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

     You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

 3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

      a. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

      b. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

      c. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License.  (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

     These requirements apply to the modified work as a whole.  If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works.  But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

 4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

      a. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

      b. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

      c. Accompany it with the information you received as to the offer to distribute corresponding source code.  (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for making modifications to it.  For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable.  However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

 5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License.  Any attempt otherwise to copy, modify, sublicense or distribute the Program 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.

 6. You are not required to accept this License, since you have not signed it.  However, nothing else grants you permission to modify or distribute the Program or its derivative works.  These actions are prohibited by law if you do not accept this License.  Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

 7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions.  You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

 8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License.  If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all.  For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

     It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices.  Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

 9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded.  In such case, this License incorporates the limitation as if written in the body of this License.

 10. The Free Software Foundation may publish revised and/or new versions of the General Public 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.

     Each version is given a distinguishing version number.  If the Program specifies a version number of this License which applies to it and ``any later version'', you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation.  If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

 11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission.  For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this.  Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

     NO WARRANTY

 12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

 13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

Applying These Terms to Your New Programs
=========================================

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program.  It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the ``copyright'' line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  NAME OF AUTHOR

     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License
     as published by the Free Software Foundation; either version 2
     of the License, or (at your option) any later version.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the
     Free Software Foundation, Inc., 675 Mass Ave,
     Cambridge, MA 02139, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
     type `show w'.  This is free software, and you are welcome
     to redistribute it under certain conditions; type `show c'
     for details.

The hypothetical commands show w and show c should show the appropriate parts of the General Public License.  Of course, the commands you use may be called something other than show w and show c; they could even be mouse-clicks or menu items---whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a ``copyright disclaimer'' for the program, if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright interest in
     the program `Gnomovision' (which makes passes at compilers)
     written by James Hacker.

     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs.  If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library.  If this is what you want to do, use the GNU Library General Public License instead of this License.