diff options
| author | Roland Pesch <pesch@cygnus> | 1992-01-21 22:25:37 +0000 |
|---|---|---|
| committer | Roland Pesch <pesch@cygnus> | 1992-01-21 22:25:37 +0000 |
| commit | 66b818fb6e453532b6b1125c4f4f07612389a1eb (patch) | |
| tree | b9529a5b24db860b7b107dea4cc3ac2cb24f7034 /gas | |
| parent | 5d9f0ecf62f6d8503f847bbe73bbe009d53c9e0e (diff) | |
| download | gdb-66b818fb6e453532b6b1125c4f4f07612389a1eb.zip gdb-66b818fb6e453532b6b1125c4f4f07612389a1eb.tar.gz gdb-66b818fb6e453532b6b1125c4f4f07612389a1eb.tar.bz2 | |
(1) Changes made yesterday, forgot to check in:
a) cleanups to node structure for Info file
b) .lflags (ignored) doc restored (was covered previously in
single par on .list-related directives ignored).
c) fill in page size defaults (.psize)
d) move text on H8/300 size suffixes to after opcode table, for
better page breaks
e) @alphaenumerate->@enumerate a in GPL
(2) Doc -a, -al, -as, options to enable listings and listing control
directives; removed FIXME comments re verifying listing counter use;
advanced titlepage date to Jan 92.
Diffstat (limited to 'gas')
| -rw-r--r-- | gas/doc/as.texinfo | 1556 |
1 files changed, 1302 insertions, 254 deletions
diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo index b3086d2..bb51118 100644 --- a/gas/doc/as.texinfo +++ b/gas/doc/as.texinfo @@ -1,20 +1,24 @@ -\input texinfo -@c $Id$ +_dnl__ -*-Texinfo-*- +_dnl__ Copyright (c) 1991 1992 Free Software Foundation, Inc. +_dnl__ $Id$ +\input texinfo @c -*-Texinfo-*- +@c Copyright (c) 1991 1992 Free Software Foundation, Inc. +@c %**start of header +@setfilename _AS__.info _if__(_GENERIC__) -@setfilename as.info +@settitle Using _AS__ _fi__(_GENERIC__) -_if__(_A29K__ && !_GENERIC__) -@setfilename as-29k.info -_fi__(_A29K__ && !_GENERIC__) -_if__(_H8__ && !_GENERIC__) -@setfilename h8-300.info -_fi__(_H8__ && !_GENERIC__) -_if__(_I960__ && !_GENERIC__) -@setfilename as-960.info -_fi__(_I960__ && !_GENERIC__) -_if__(_M680X0__ && !_GENERIC__) -@setfilename as-m680x0.info -_fi__(_M680X0__ && !_GENERIC__) +_if__(!_GENERIC__) +@settitle Using _AS__ (_HOST__) +_fi__(!_GENERIC__) +@setchapternewpage odd +@c @smallbook +@c @cropmarks +@c %**end of header + +@finalout +@syncodeindex ky cp + _if__(0) NOTE: this manual is marked up for preprocessing with a collection @@ -24,12 +28,12 @@ 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 suitable for formatting. See the text in "pretex.m4" -for a fuller explanation (and the macro definitions). +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) @c -@synindex ky cp @ifinfo This file documents the GNU Assembler "_AS__". @@ -59,17 +63,7 @@ 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. @end ifinfo -@iftex -@finalout -@c @smallbook -@end iftex -@setchapternewpage odd -_if__(_GENERIC__) -@settitle Using _AS__ -_fi__(_GENERIC__) -_if__(!_GENERIC__) -@settitle Using _AS__ (_HOST__) -_fi__(!_GENERIC__) + @titlepage @title Using _AS__ @subtitle The GNU Assembler @@ -77,7 +71,7 @@ _if__(!_GENERIC__) @subtitle for the _HOST__ family _fi__(!_GENERIC__) @sp 1 -@subtitle March 1991 +@subtitle January 1992 @sp 1 @sp 13 The Free Software Foundation Inc. thanks The Nice Computer @@ -144,8 +138,9 @@ _fi__(!_GENERIC__) * Symbols:: Symbols * Expressions:: Expressions * Pseudo Ops:: Assembler Directives -* Machine Dependent:: Machine Dependent Features +* _MACH_DEP__:: Machine Dependent Features * Copying:: GNU GENERAL PUBLIC LICENSE +* Index:: Index @end menu @node Overview, Invoking, Top, Top @@ -158,15 +153,17 @@ code for _HOST__ architectures. _fi__(!_GENERIC__) @end iftex -@heading Invoking @code{_AS__} - +@cindex invocation summary +@cindex option summary +@cindex summary of options Here is a brief summary of how to invoke @code{_AS__}. For details, @pxref{Invoking,,Comand-Line Options}. @c We don't use deffn and friends for the following because they seem @c to be limited to one line for the header. @smallexample - _AS__ [ -D ] [ -f ] [ -I @var{path} ] [ -k ] [ -L ] + _AS__ [ -a | -al | -as ] [ -D ] [ -f ] + [ -I @var{path} ] [ -k ] [ -L ] [ -o @var{objfile} ] [ -R ] [ -v ] [ -w ] _if__(_A29K__) @c am29k has no machine-dependent assembler options @@ -186,6 +183,9 @@ _fi__(_M680X0__) @end smallexample @table @code +@item -a | -al | -as +Turn on assembly listings; @samp{-al}, listing only, @samp{-as}, symbols +only, @samp{-a}, everything. @item -D This option is accepted only for script compatibility with calls to @@ -198,12 +198,12 @@ other assemblers; it has no effect on @code{_AS__}. Add @var{path} to the search list for @code{.include} directives @item -k -_if__((!_GENERIC__) && _DIFFTABKLUG__) +_if__((!_GENERIC__) && !_DIFFTABKLUG__) This option is accepted but has no effect on the _HOST__ family. -_fi__((!_GENERIC__) && _DIFFTABKLUG__) -_if__(_GENERIC__) +_fi__((!_GENERIC__) && !_DIFFTABKLUG__) +_if__(_GENERIC__ || _DIFFTABKLUG__) Issue warnings when difference tables altered for long displacements. -_fi__(_GENERIC__) +_fi__(_GENERIC__ || _DIFFTABKLUG__) @item -L Keep (in symbol table) local symbols, starting with @samp{L} @@ -222,13 +222,22 @@ Suppress warning messages _if__(_I960__) @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC +_if__(_GENERIC__) +(When configured for Intel 960). +_fi__(_GENERIC__) Specify which variant of the 960 architecture is the target. @item -b +_if__(_GENERIC__) +(When configured for Intel 960). +_fi__(_GENERIC__) Add code to collect statistics about branches taken. @item -norelax -Do not alter compare-and-branch instructions for long displaements; +_if__(_GENERIC__) +(When configured for Intel 960). +_fi__(_GENERIC__) +Do not alter compare-and-branch instructions for long displacements; error if necessary. _fi__(_I960__) @@ -247,7 +256,7 @@ Specify what processor in the 68000 family is the target (default 68020) _fi__(_M680X0__) @item -- | @var{files} @dots{} -Source files to assemble, or standard input +Standard input, or source files to assemble @end table @menu @@ -262,8 +271,10 @@ Source files to assemble, or standard input @node Manual, GNU Assembler, Overview, Overview @section Structure of this Manual -This document is intended to describe what you need to know to use -@code{_AS__}. We cover the syntax expected in source files, including + +@cindex manual, structure and purpose +This manual is intended to describe what you need to know to use +@sc{gnu} @code{_AS__}. We cover the syntax expected in source files, including notation for symbols, constants, and expressions; the directives that @code{_AS__} understands; and of course how to invoke @code{_AS__}. @@ -272,28 +283,36 @@ We also cover special features in the _HOST__ configuration of @code{_AS__}, including assembler directives. _fi__(!_GENERIC__) _if__(_GENERIC__) -This document also describes some of the machine-dependent features of +This manual also describes some of the machine-dependent features of various flavors of the assembler. _fi__(_GENERIC__) _if__(_INTERNALS__) -This document also describes how the assembler works internally, and +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. _fi__(_INTERNALS__) @refill +@cindex machine instructions (not covered) On the other hand, this manual is @emph{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 @emph{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 +particular architecture. +_if__(_GENERIC__) +You may want to consult the manufacturer's machine architecture manual for this information. +_fi__(_GENERIC__) +_if__(_H8__&&!_GENERIC__) +For information on the H8/300 machine instruction set, see @cite{H8/300 +Series Programming Manual} (Hitachi ADE--602--025). +_fi__(_H8__&&!_GENERIC__) @c I think this is premature---pesch@cygnus.com, 17jan1991 @ignore -Throughout this document, we assume that you are running @dfn{GNU}, +Throughout this manual, we assume that you are running @dfn{GNU}, the portable operating system from the @dfn{Free Software Foundation, Inc.}. This restricts our attention to certain kinds of computer (in particular, the kinds of computers that GNU can run on); @@ -317,9 +336,10 @@ computer-readable series of instructions. Different versions of @node GNU Assembler, Object Formats, Manual, Overview @section _AS__, the GNU Assembler + GNU @code{as} is really a family of assemblers. _if__(!_GENERIC__) -This manual describes @samp{_AS__}, a member of that family which is +This manual describes @code{_AS__}, a member of that family which is configured for the _HOST__ architectures. _fi__(!_GENERIC__) If you use (or have used) the GNU assembler on one architecture, you @@ -328,10 +348,13 @@ architecture. Each version has much in common with the others, including object file formats, most assembler directives (often called @dfn{pseudo-ops)} and assembler syntax.@refill +_if__(_GENERIC__||!_H8__) +@cindex purpose of @sc{gnu} @code{_AS__} @code{_AS__} is primarily intended to assemble the output of the GNU C compiler @code{_GCC__} for use by the linker @code{_LD__}. Nevertheless, we've tried to make @code{_AS__} assemble correctly everything that the native assembler would. +_fi__(_GENERIC__||!_H8__) _if__(_VAX__) Any exceptions are documented explicitly (@pxref{_MACH_DEP__}). _fi__(_VAX__) @@ -347,6 +370,8 @@ program in one pass of the source file. This has a subtle impact on the @node Object Formats, Command Line, GNU Assembler, Overview @section Object File Formats + +@cindex object file format 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 @@ -376,14 +401,18 @@ _fi__(!_GENERIC__) @node Command Line, Input Files, Object Formats, Overview @section Command Line +@cindex command line conventions After the program name @code{_AS__}, the command line may contain -options and file names. Options may be in any order, and may be +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. +@cindex standard input, as input file +@kindex -- @file{--} (two hyphens) by itself names the standard input file explicitly, as one of the files for @code{_AS__} to assemble. +@cindex options, command line Except for @samp{--} any command line argument that begins with a hyphen (@samp{-}) is an option. Each option changes the behavior of @code{_AS__}. No option changes the way another option works. An @@ -403,6 +432,9 @@ _AS__ -omy-object-file.o mumble.s @node Input Files, Object, Command Line, Overview @section Input Files +@cindex input +@cindex source program +@cindex files, input We use the phrase @dfn{source program}, abbreviated @dfn{source}, to describe the program input to one run of @code{_AS__}. The program may be in one or more files; how the source is partitioned into files @@ -422,7 +454,7 @@ 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 @code{_AS__} is given no file names it attempts to read one input file +If you give @code{_AS__} no file names it attempts to read one input file from the @code{_AS__} standard input, which is normally your terminal. You may have to type @key{ctl-D} to tell @code{_AS__} there is no more program to assemble. @@ -434,10 +466,13 @@ If the source is empty, @code{_AS__} will produce a small, empty object file. @subheading Filenames and Line-numbers -There are two ways of locating a line in the input file (or files) and both -are used in reporting error messages. One way refers to a line + +@cindex input file linenumbers +@cindex line numbers, in input files +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. +``logical'' file. @xref{Errors, ,Error and Warning Messages}. @dfn{Physical files} are those files named in the command line given to @code{_AS__}. @@ -450,6 +485,11 @@ source is itself synthesized from other files. @node Object, Errors, Input Files, Overview @section Output (Object) File + +@cindex object file +@cindex output file +@kindex a.out +@kindex .o Every time you run @code{_AS__} it produces an output file, which is your assembly language program translated into numbers. This file is the object file, named @code{a.out} unless you tell @code{_AS__} to @@ -460,28 +500,37 @@ capable of assembling self-contained programs directly into a runnable program. @c This may still work, but hasn't been tested. +@cindex linker +@kindex ld The object file is meant for input to the linker @code{_LD__}. It contains assembled program code, information to help @code{_LD__} integrate the assembled program into a runnable file, and (optionally) symbolic information for the debugger. -@comment link above to some info file(s) like the description of a.out. -@comment don't forget to describe GNU info as well as Unix lossage. +@c link above to some info file(s) like the description of a.out. +@c don't forget to describe GNU info as well as Unix lossage. @node Errors, , Object, Overview @section Error and Warning Messages +@cindex error messsages +@cindex warning messages +@cindex messages from @code{_AS__} @code{_AS__} may write warnings and error messages to the standard error -file (usually your terminal). This should not happen when @code{_AS__} is -run automatically by a compiler. Warnings report an assumption made so +file (usually your terminal). This should not happen when a compiler +runs @code{_AS__} automatically. Warnings report an assumption made so that @code{_AS__} could keep assembling a flawed program; errors report a grave problem that stops the assembly. +@cindex format of warning messages Warning messages have the format + @smallexample file_name:@b{NNN}:Warning Message Text @end smallexample + @noindent +@cindex line numbers, in warnings/errors (where @b{NNN} is a line number). If a logical file name has been given (@pxref{App-File,,@code{.app-file}}) it is used for the filename, otherwise the name of the current input file is used. If a logical line number was @@ -497,6 +546,7 @@ 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). @refill +@cindex format of error messages Error messages have the format @smallexample file_name:@b{NNN}:FATAL:Error Message Text @@ -507,7 +557,9 @@ because many of them aren't supposed to happen. @node Invoking, Syntax, Overview, Top @chapter Command-Line Options -This section describes command-line options available in @emph{all} + +@cindex options, all versions of @code{_AS__} +This chapter describes command-line options available in @emph{all} versions of the GNU assembler; @pxref{_MACH_DEP__}, for options specific _if__(!_GENERIC__) to the _HOST__. @@ -516,22 +568,55 @@ _if__(_GENERIC__) to particular machine architectures. _fi__(_GENERIC__) -@subsection @code{-D} +@section @code{-a}, @code{-al}, @code{-as} + +@kindex -a +@kindex -al +@kindex -as +@cindex listings, enabling +@cindex assembly listings, enabling +These options enable listing output from the assembler. @samp{-a} by +itself requests all listing output; @samp{-al} requests only the +output-program listing, and @samp{-as} requests only a symbol table +listing. + +Once you have specified one of these options, you can further control +listing output and its appearance using the directives @code{.list}, +@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and +@code{.sbttl}. + +If you do not request listing output with one of the @samp{-a} options, the +listing-control directives have no effect. + +@section @code{-D} + +@kindex -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 @code{_AS__}. -@subsection Work Faster: @code{-f} +@section Work Faster: @code{-f} + +@kindex -f +@cindex trusted compiler +@cindex faster processing (@code{-f}) @samp{-f} should only be used when assembling programs written by a (trusted) compiler. @samp{-f} stops the assembler from pre-processing -the input file(s) before assembling them. +the input file(s) before assembling them. @xref{Pre-processing, +,Pre-processing}. + @quotation @emph{Warning:} if the files actually need to be pre-processed (if they contain comments, for example), @code{_AS__} will not work correctly if @samp{-f} is used. @end quotation -@subsection @code{.include} search path: @code{-I} @var{path} +@section @code{.include} search path: @code{-I} @var{path} + +@kindex -I @var{path} +@cindex paths for @code{.include} +@cindex search path for @code{.include} +@cindex @code{include} directive search path Use this option to add a @var{path} to the list of directories @code{_AS__} will search for files specified in @code{.include} directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as @@ -540,7 +625,9 @@ working directory is always searched first; after that, @code{_AS__} searches any @samp{-I} directories in the same order as they were specified (left to right) on the command line. -@subsection Difference Tables: @code{-k} +@section Difference Tables: @code{-k} + +@kindex -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, @@ -551,13 +638,18 @@ alteration on other platforms. _fi__((!_GENERIC__) && (!_DIFFTABKLUG__)) _if__(_GENERIC__ || _DIFFTABKLUG__ ) +@cindex difference tables, warning +@cindex warning for altered difference tables @code{_AS__} sometimes alters the code emitted for directives of the form @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}. You can use the @samp{-k} option if you want a warning issued when this is done. _fi__(_GENERIC__ || _DIFFTABKLUG__ ) -@subsection Include Local Labels: @code{-L} +@section Include Local Labels: @code{-L} + +@kindex -L +@cindex local labels, retaining in output Labels beginning with @samp{L} (upper case only) are called @dfn{local labels}. @xref{Symbol Names}. Normally you don't see such labels when debugging, because they are intended for the use of programs (like @@ -569,7 +661,11 @@ This option tells @code{_AS__} to retain those @samp{L@dots{}} symbols in the object file. Usually if you do this you also tell the linker @code{_LD__} to preserve symbols whose names begin with @samp{L}. -@subsection Name the Object File: @code{-o} +@section Name the Object File: @code{-o} + +@kindex -o +@cindex naming object file +@cindex object file name There is always one object file output when you run @code{_AS__}. By default it has the name @file{a.out}. You use this option (which takes exactly one filename) to give the object file a different name. @@ -577,11 +673,13 @@ takes exactly one filename) to give the object file a different name. Whatever the object file is called, @code{_AS__} will overwrite any existing file of the same name. -@subsection Join Data and Text Sections: @code{-R} -_if__(_COFF__) -This option is only useful if you use sections named @samp{.text} and -@samp{.data}. -_fi__(_COFF__) +@section Join Data and Text Sections: @code{-R} + +@kindex -R +@cindex data and text sections, joining +@cindex text and data sections, joining +@cindex joining text and data sections +@cindex merging text and data sections @code{-R} tells @code{_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 @@ -594,12 +692,27 @@ 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 @code{_AS__}. In future, @code{-R} may work this way. -@subsection Announce Version: @code{-v} +_if__(_COFF__) +When @code{_AS__} is configured for COFF output, +this option is only useful if you use sections named @samp{.text} and +@samp{.data}. +_fi__(_COFF__) + +@section Announce Version: @code{-v} + +@kindex -v +@kindex -version +@cindex @code{_AS__} version +@cindex version of @code{_AS__} You can find out what version of as is running by including the option @samp{-v} (which you can also spell as @samp{-version}) on the command line. -@subsection Suppress Warnings: @code{-W} +@section Suppress Warnings: @code{-W} + +@kindex -W +@cindex suppressing warnings +@cindex warnings, suppressing @code{_AS__} should never give a warning or error message when assembling compiler output. But programs written by people often cause @code{_AS__} to give a warning that a particular assumption was @@ -611,6 +724,9 @@ still reported. @node Syntax, Sections, Invoking, Top @chapter Syntax + +@cindex machine-independent syntax +@cindex syntax, machine-independent This chapter describes the machine-independent syntax allowed in a source file. @code{_AS__} syntax is similar to what many other assemblers use; it is inspired in BSD 4.2 @@ -631,19 +747,23 @@ _fi__(_VAX__) @end menu @node Pre-processing, Whitespace, Syntax, Syntax -@section Pre-processing +@section Pre-Processing +@cindex preprocessing The pre-processor: @itemize @bullet +@cindex whitespace, removed by preprocessor @item 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. +@cindex comments, removed by preprocessor @item removes all comments, replacing them with a single space, or an appropriate number of newlines. +@cindex constants, converted by preprocessor @item converts character constants into the appropriate numeric values. @end itemize @@ -652,6 +772,10 @@ Excess whitespace, comments, and character constants cannot be used in the portions of the input text that are not pre-processed. +@cindex turning preprocessing on and off +@cindex preprocessing, turning on and off +@kindex #NO_APP +@kindex #APP If the first line of an input file is @code{#NO_APP} or the @samp{-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 @@ -662,6 +786,8 @@ normally does not need to be pre-processed. @node Whitespace, Comments, Pre-processing, Syntax @section Whitespace + +@cindex whitespace @dfn{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 @@ -670,6 +796,8 @@ as exactly one space. @node Comments, Symbol Intro, Whitespace, Syntax @section Comments + +@cindex comments There are two ways of rendering comments to @code{_AS__}. In both cases the comment is equivalent to one space. @@ -685,6 +813,7 @@ This means you may not nest these comments. /* This sort of comment does not nest. */ @end smallexample +@cindex line comment character Anything from the @dfn{line comment} character to the next newline is considered a comment and is ignored. The line comment character is _if__(_VAX__) @@ -711,7 +840,10 @@ will only begin a comment if it is the first non-whitespace character on a line, while the other will always begin a comment. _fi__(_GENERIC__) -To be compatible with past assemblers a special interpretation is +@kindex # +@cindex lines starting with @code{#} +@cindex logical line numbers +To be compatible with past assemblers, a special interpretation is given to lines that begin with @samp{#}. Following the @samp{#} an absolute expression (@pxref{Expressions}) is expected: this will be the logical line number of the @b{next} line. Then a string @@ -730,6 +862,9 @@ of @code{_AS__}. @node Symbol Intro, Statements, Comments, Syntax @section Symbols + +@cindex symbols +@cindex characters used in symbols A @dfn{symbol} is one or more characters chosen from the set of all letters (both upper and lower case), digits and _if__(!_H8__) @@ -747,9 +882,14 @@ 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). @xref{Symbols}. +@cindex length of symbols @node Statements, Constants, Symbol Intro, Syntax @section Statements + +@cindex statements, structure of +@cindex line separator character +@cindex statement separator character _if__(!_GENERIC__) _if__(!(_A29K__||_H8__)) A @dfn{statement} ends at a newline character (@samp{\n}) or at a @@ -779,9 +919,14 @@ statement. Newlines and separators within character constants are an exception: they don't end statements. _fi__(_GENERIC__) +@cindex newline, required at file end +@cindex EOF, newline must precede It is an error to end any statement with end-of-file: the last character of any input file should be a newline.@refill +@cindex continuing statements +@cindex multi-line statements +@cindex statement on multiple lines You may write a statement on more than one line if you put a backslash (@kbd{\}) immediately in front of any newlines within the statement. When @code{_AS__} reads a backslashed newline both @@ -791,6 +936,8 @@ source program. An empty statement is allowed, and may include whitespace. It is ignored. +@cindex instructions and directives +@cindex directives and instructions @c "key symbol" is not used elsewhere in the document; seems pedantic to @c @defn{} it in that case, as was done previously... pesch@cygnus.com, @c 13feb91. @@ -808,6 +955,8 @@ represent a different instruction in a different computer's assembly language.@refill _fi__(_GENERIC__) +@cindex @code{:} (label) +@cindex label (@code{:}) A label is a symbol immediately followed by a colon (@code{:}). Whitespace before a label or after a colon is permitted, but you may not have whitespace between a label's symbol and its colon. @xref{Labels}. @@ -820,6 +969,8 @@ another_label: # This is an empty statement. @node Constants, , Statements, Syntax @section Constants + +@cindex constants A constant is a number, written so that its value is known by inspection, without knowing any context. Like this: @smallexample @@ -837,6 +988,9 @@ inspection, without knowing any context. Like this: @node Characters, Numbers, Constants, Constants @subsection Character Constants + +@cindex character constants +@cindex constants, character There are two kinds of character constants. A @dfn{character} stands for one character in one byte and its value may be used in numeric expressions. String constants (properly called string @@ -850,6 +1004,9 @@ used in arithmetic expressions. @node Strings, Chars, Characters, Characters @subsubsection Strings + +@cindex string constants +@cindex constants, string A @dfn{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 @dfn{escape} these characters: precede them with @@ -859,44 +1016,76 @@ one backslash: the first @code{\} is an escape which tells (which prevents @code{_AS__} from recognizing the second @code{\} as an escape character). The complete list of escapes follows. +@cindex escape codes, character +@cindex character escape codes @table @kbd @c @item \a @c Mnemonic for ACKnowledge; for ASCII this is octal code 007. +@c @item \b +@cindex @code{\b} (backspace character) +@cindex backspace (@code{\b}) Mnemonic for backspace; for ASCII this is octal code 010. + @c @item \e @c Mnemonic for EOText; for ASCII this is octal code 004. +@c @item \f +@cindex @code{\f} (formfeed character) +@cindex formfeed (@code{\f}) Mnemonic for FormFeed; for ASCII this is octal code 014. + @item \n +@cindex @code{\n} (newline character) +@cindex newline (@code{\n}) Mnemonic for newline; for ASCII this is octal code 012. + @c @item \p @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}. +@c @item \r +@cindex @code{\r} (carriage return character) +@cindex carriage return (@code{\r}) Mnemonic for carriage-Return; for ASCII this is octal code 015. + @c @item \s @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with @c other assemblers. +@c @item \t +@cindex @code{\t} (tab) +@cindex tab (@code{\t}) Mnemonic for horizontal Tab; for ASCII this is octal code 011. + @c @item \v @c Mnemonic for Vertical tab; for ASCII this is octal code 013. @c @item \x @var{digit} @var{digit} @var{digit} @c A hexadecimal character code. The numeric code is 3 hexadecimal digits. +@c @item \ @var{digit} @var{digit} @var{digit} +@cindex @code{\@var{ddd}} (octal character code) +@cindex octal character code (@code{\@var{ddd}}) 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, @code{\008} has the value 010, and @code{\009} the value 011. + @item \\ +@cindex @code{\\} (@samp{\} character) +@cindex backslash (@code{\\}) Represents one @samp{\} character. + @c @item \' @c Represents one @samp{'} (accent acute) character. @c This is needed in single character literals @c (@xref{Characters,,Character Constants}.) to represent @c a @samp{'}. +@c @item \" +@cindex @code{\"} (doublequote character) +@cindex doublequote (@code{\"}) Represents one @samp{"} character. Needed in strings to represent this character, because an unescaped @samp{"} would end the string. + @item \ @var{anything-else} Any other character when escaped by @kbd{\} will give a warning, but assemble as if the @samp{\} was not present. The idea is that if @@ -914,6 +1103,10 @@ sequence. @node Chars, , Strings, Characters @subsubsection Characters + +@cindex single character constant +@cindex character, single +@cindex constant, single character 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 @@ -939,6 +1132,9 @@ that character. @code{_AS__} assumes your character code is ASCII: @node Numbers, , Characters, Constants @subsection Number Constants + +@cindex constants, number +@cindex number constants @code{_AS__} distinguishes three kinds of numbers according to how they are stored in the target machine. @emph{Integers} are numbers that would fit into an @code{int} in the C language. @emph{Bignums} are @@ -956,16 +1152,26 @@ _fi__(_I960__&&!_GENERIC__) @node Integers, Bignums, Numbers, Numbers @subsubsection Integers -@c FIXME: are binary integers in vintage as? +@cindex integers +@cindex constants, integer + +@cindex binary integers +@cindex integers, binary A binary integer is @samp{0b} or @samp{0B} followed by zero or more of the binary digits @samp{01}. +@cindex octal integers +@cindex integers, octal An octal integer is @samp{0} followed by zero or more of the octal digits (@samp{01234567}). +@cindex decimal integers +@cindex integers, decimal A decimal integer starts with a non-zero digit followed by zero or more digits (@samp{0123456789}). +@cindex hexadecimal integers +@cindex integers, hexadecimal A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}. @@ -975,6 +1181,9 @@ the prefix operator @samp{-} discussed under expressions @node Bignums, Flonums, Integers, Numbers @subsubsection Bignums + +@cindex bignums +@cindex constants, bignum A @dfn{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 @@ -987,8 +1196,13 @@ _if__(_GENERIC__||!_I960__) @node Flonums, , Bignums, Numbers _fi__(_GENERIC__||!_I960__) @subsubsection Flonums +@cindex flonums +@cindex floating point numbers +@cindex constants, floating point + +@cindex precision, floating point A @dfn{flonum} represents a floating point number. The translation is -complex: a decimal floating point number from the text is converted by +indirect: a decimal floating point number from the text is converted by @code{_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 @@ -999,9 +1213,9 @@ A flonum is written by writing (in order) @item The digit @samp{0}. @item +A letter, to tell @code{_AS__} the rest of the number is a flonum. _if__(_GENERIC__) -A letter, to tell @code{_AS__} the rest of the number is a flonum. @kbd{e} -is recommended. Case is not important. +@kbd{e} is recommended. Case is not important. @ignore @c FIXME: verify if flonum syntax really this vague for most cases (Any otherwise illegal letter @@ -1013,22 +1227,20 @@ _if__(_A29K__||_H8__) _if__(_GENERIC__) On the AMD 29K and H8/300 architectures, the letter must be: _fi__(_GENERIC__) -One of the letters @samp{DFPRSX} (in upper or lower case), to tell -@code{_AS__} the rest of the number is a flonum. +One of the letters @samp{DFPRSX} (in upper or lower case). _fi__(_A29K__||_H8__) _if__(_I960__) _if__(_GENERIC__) On the Intel 960 architecture, the letter must be: _fi__(_GENERIC__) -One of the letters @samp{DFT} (in upper or lower case), to tell -@code{_AS__} the rest of the number is a flonum. +One of the letters @samp{DFT} (in upper or lower case). _fi__(_I960__) @item An optional sign: either @samp{+} or @samp{-}. @item An optional @dfn{integer part}: zero or more decimal digits. @item -An optional @dfn{fraction part}: @samp{.} followed by zero +An optional @dfn{fractional part}: @samp{.} followed by zero or more decimal digits. @item An optional exponent, consisting of: @@ -1044,7 +1256,7 @@ One or more decimal digits. @end itemize @end itemize -At least one of @var{integer part} or @var{fraction part} must be +At least one of the integer part or the fractional part must be present. The floating point number has the usual base-10 value. @code{_AS__} does all processing using integers. Flonums are computed @@ -1057,6 +1269,9 @@ _if__(_I960__&&!_GENERIC__) @c turned on only by the i960 config of GAS. @node Bit Fields, , Flonums, Numbers @subsubsection Bit Fields + +@cindex bit fields +@cindex constants, bit field You can also define numeric constants as @dfn{bit fields}. specify two numbers separated by a colon--- @example @@ -1083,23 +1298,26 @@ _fi__(_I960__&&!_GENERIC__) @node Sections, Symbols, Syntax, Top @chapter Sections and Relocation +@cindex sections +@cindex relocation @menu * Secs Background:: Background * _LD__ Sections:: _LD__ Sections * _AS__ Sections:: _AS__ Internal Sections -_if__(!_H8__) * Sub-Sections:: Sub-Sections -_fi__(!_H8__) * bss:: bss Section @end menu @node Secs Background, _LD__ Sections, Sections, Sections @section 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. +@cindex linker, and assembler +@cindex assembler, and linker The linker @code{_LD__} reads many object files (partial programs) and combines their contents to form a runnable program. When @code{_AS__} emits an object file, the partial program is assumed to start at address @@ -1115,7 +1333,12 @@ within them. Such a rigid unit is called a @emph{section}. Assigning run-time addresses to sections is called @dfn{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, @code{_AS__} pads sections if needed to ensure they end +on a word (sixteen bit) boundary. +_fi__(_H8__) +@cindex standard @code{_AS__} sections An object file written by @code{_AS__} has at least three sections, any of which may be empty. These are named @dfn{text}, @dfn{data} and @dfn{bss} sections. @@ -1153,6 +1376,8 @@ Which section does the address refer to? What is the numeric value of Is the reference to an address ``Program-Counter relative''? @end itemize +@cindex addresses, format of +@cindex section-relative addressing In fact, every address @code{_AS__} ever uses is expressed as @display (@var{section}) + (@var{offset into section}) @@ -1167,7 +1392,7 @@ Internal Sections}). In this manual we use the notation @{@var{secname} Apart from text, data and bss sections you need to know about the @dfn{absolute} section. When @code{_LD__} mixes partial programs, -addresses in the absolute section remain unchanged. That is, address +addresses in the absolute section remain unchanged. For example, address @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by @code{_LD__}. Although two partial programs' data sections will not overlap addresses after linking, @emph{by definition} their absolute sections will overlap. @@ -1200,9 +1425,13 @@ use of @code{_AS__} and have no meaning except during assembly. @table @strong _if__(_GENERIC__||_COFF__) +@cindex named sections +@cindex sections, named @item named sections _fi__(_GENERIC__||_COFF__) _if__(_AOUT__||_BOUT__) +@cindex text section +@cindex data section @item text section @itemx data section _fi__(_AOUT__||_BOUT__) @@ -1218,6 +1447,7 @@ program is usually alterable: for example, C variables would be stored in the data section. _fi__(_AOUT__||_BOUT__) +@cindex bss section @item 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 @@ -1226,23 +1456,24 @@ 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. +@cindex absolute section @item 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 @code{_LD__} must not change when relocating. In this sense we speak of absolute addresses being ``unrelocatable'': they don't change during relocation. +@cindex undefined section @item undefined section This ``section'' is a catch-all for address references to objects not in the preceding sections. @c FIXME: ref to some other doc on obj-file formats could go here. - @end table +@cindex relocation example An idealized example of three relocatable sections follows. _if__(_COFF__) -The example uses the traditional names @samp{.text} and @samp{.data} for -two named sections. +The example uses the traditional section names @samp{.text} and @samp{.data}. _fi__(_COFF__) Memory addresses are on the horizontal axis. @@ -1272,37 +1503,31 @@ linked program: | |TTT|ttttt| |dddd|DDD|00000| @c FIXME make sure no page breaks inside figure!! @tex -{\it Partial program \#1: } - +\line{\it Partial program \#1: \hfil} \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil} -{\it Partial program \#2:} - +\line{\it Partial program \#2: \hfil} \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil} -{\it linked program: } - +\line{\it linked program: \hfil} \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil} \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil} -{\it addresses:} - +\line{\it addresses: \hfil} \line{0\dots\hfil} @end tex @c END TEXI2ROFF-KILL -_if__(!_H8__) @node _AS__ Sections, Sub-Sections, _LD__ Sections, Sections -_fi__(!_H8__) -_if__(_H8__) -@node _AS__ Sections, bss, _LD__ Sections, Sections -_fi__(_H8__) @section _AS__ Internal Sections + +@cindex internal @code{_AS__} sections +@cindex sections in messages, internal These sections are meant only for the internal use of @code{_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 @code{_AS__} @@ -1313,13 +1538,16 @@ section-relative address. @table @b @item absent +@cindex absent (internal section) An expression was expected and none was found. @item ASSEMBLER-INTERNAL-LOGIC-ERROR! +@cindex assembler internal logic error An internal assembler logic error has been found. This means there is a bug in the assembler. @item bignum/flonum +@cindex bignum/flonum (internal section) If a number can't be written as a C @code{int} constant (a bignum or a flonum, but not an integer), it is recorded as belonging to this ``section''. @code{_AS__} has to remember that a flonum or a bignum @@ -1330,6 +1558,7 @@ convenience; bignum/flonum section behaves similarly to absolute section. @item pass1 section +@cindex pass1 (internal 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 @@ -1342,12 +1571,14 @@ will abort with an error message if one is required. @end quotation @item difference section +@cindex difference (internal section) As an assist to the C compiler, expressions of the forms @display (@var{undefined symbol}) @minus{} (@var{expression}) @var{something} @minus{} (@var{undefined symbol}) (@var{undefined symbol}) @minus{} (@var{undefined symbol}) @end display + are permitted, and belong to the difference section. @code{_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 @@ -1366,14 +1597,27 @@ statements and the like. @node Sub-Sections, bss, _AS__ Sections, Sections @section Sub-Sections + +@cindex numbered subsections +@cindex grouping data +_if__(_AOUT__||_BOUT__) Assembled bytes _if__(_COFF__) conventionally _fi__(_COFF__) -fall into two sections: text and data. Because you may have groups of -text or data that you want to end up near to each other in the object -file, @code{_AS__} allows you to use @dfn{subsections} of these two -sections. Within each section, there can be numbered subsections with +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. +@code{_AS__} allows you to use @dfn{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 @@ -1390,6 +1634,11 @@ Each subsection is zero-padded up to a multiple of four bytes. (Subsections may be padded a different amount on different flavors of @code{_AS__}.) _fi__(_GENERIC__) +_if__(!_GENERIC__) +_if__(_H8__) +On the H8/300 platform, each subsection is zero-padded to a word +boundary (two bytes). +_fi__(_H8__) _if__(_I960__) @c FIXME section padding (alignment)? @c Rich Pixley says padding here depends on target obj code format; that @@ -1399,9 +1648,11 @@ _if__(_I960__) @c discussed in BFD chapter of binutils (or some such). _fi__(_I960__) _if__(_A29K__) -On the AMD 29K family, no particular padding is added to section sizes; -_AS__ forces no alignment on this platform. +On the AMD 29K family, no particular padding is added to section or +subsection sizes; _AS__ forces no alignment on this platform. _fi__(_A29K__) +_fi__(!_GENERIC__) + 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; @code{_LD__} and @@ -1410,12 +1661,23 @@ 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 @samp{.text @var{expression}} or a @samp{.data -@var{expression}} statement. @var{Expression} should be an absolute -expression. (@xref{Expressions}.) If you just say @samp{.text} -then @samp{.text 0} is assumed. Likewise @samp{.data} means -@samp{.data 0}. Assembly begins in @code{text 0}. -For instance: +into, use a numeric argument to specify it, in a @samp{.text +@var{expression}} or a @samp{.data @var{expression}} statement. +_if__(_COFF__) +_if__(_GENERIC__) +When generating COFF output, you +_fi__(_GENERIC__) +_if__(!_GENERIC__) +You +_fi__(!_GENERIC__) +can also use an extra subsection +argument with arbitrary named sections: @samp{.section @var{name}, +@var{expression}}. +_fi__(_COFF__) +@var{Expression} should be an absolute expression. +(@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0} +is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly +begins in @code{text 0}. For instance: @smallexample .text 0 # The default subsection is text 0 anyway. .ascii "This lives in the first text subsection. *" @@ -1438,13 +1700,11 @@ definition will capture its current value. The location counter of the section that statements are being assembled into is said to be the @dfn{active} location counter. -_if__(!_H8__) @node bss, , Sub-Sections, Sections -_fi__(!_H8__) -_if__(_H8__) -@node bss, , _AS__ Sections, Sections -_fi__(_H8__) @section bss Section + +@cindex bss section +@cindex common variable storage 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 @@ -1458,11 +1718,14 @@ are no bss subsections. @xref{Comm,,@code{.comm}}, @node Symbols, Expressions, Sections, Top @chapter Symbols + +@cindex 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. @quotation +@cindex debuggers, and symbol order @emph{Warning:} @code{_AS__} does not place symbols in the object file in the same order they were declared. This may break some debuggers. @end quotation @@ -1477,6 +1740,8 @@ the same order they were declared. This may break some debuggers. @node Labels, Setting Symbols, Symbols, Symbols @section Labels + +@cindex labels A @dfn{label} is written as a symbol immediately followed by a colon @samp{:}. The symbol then represents the current value of the active location counter, and is, for example, a suitable instruction @@ -1486,6 +1751,9 @@ definitions. @node Setting Symbols, Symbol Names, Labels, Symbols @section Giving Symbols Other Values + +@cindex assigning values to symbols +@cindex symbol values, assigning A symbol can be given an arbitrary value by writing a symbol, followed by an equals sign @samp{=}, followed by an expression (@pxref{Expressions}). This is equivalent to using the @code{.set} @@ -1493,6 +1761,9 @@ directive. @xref{Set,,@code{.set}}. @node Symbol Names, Dot, Setting Symbols, Symbols @section Symbol Names + +@cindex symbol names +@cindex names, symbol Symbol names begin with a letter or with one of _if__(!_H8__) @samp{_.$} @@ -1510,7 +1781,7 @@ underscores and dollar signs. _fi__(!_H8__) _if__(_H8__) _if__(_GENERIC__) -dollar signs (unless otherwise noted in @ref{_MACH_DEP}), +dollar signs (unless otherwise noted in @ref{_MACH_DEP__}), _fi__(_GENERIC__) and underscores. _fi__(_H8__) @@ -1528,6 +1799,10 @@ number of times in a program. @subheading Local Symbol Names +@cindex local symbol names +@cindex symbol names, local +@cindex temporary symbol names +@cindex symbol names, temporary 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 @samp{0} @samp{1} @@ -1583,6 +1858,10 @@ For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th @node Dot, Symbol Attributes, Symbol Names, Symbols @section The Special Dot Symbol +@cindex dot (symbol) +@cindex @code{.} (symbol) +@cindex current address +@cindex location counter The special symbol @samp{.} refers to the current address that @code{_AS__} is assembling into. Thus, the expression @samp{melvin: .long .} will cause @code{melvin} to contain its own address. @@ -1597,8 +1876,12 @@ _fi__(_A29K__) @node Symbol Attributes, , Dot, Symbols @section Symbol Attributes + +@cindex symbol attributes +@cindex attributes, symbol Every symbol has, as well as its name, the attributes ``Value'' and -``Type''. Depending on output format, symbols also have auxiliary attributes. +``Type''. Depending on output format, symbols can also have auxiliary +attributes. _if__(_INTERNALS__) The detailed definitions are in _0__<a.out.h>_1__. _fi__(_INTERNALS__) @@ -1611,12 +1894,14 @@ would want. @menu * Symbol Value:: Value * Symbol Type:: Type +_if__(_AOUT__||_BOUT__) _if__(_GENERIC__||!_BOUT__) * a.out Symbols:: Symbol Attributes: @code{a.out} _fi__(_GENERIC__||!_BOUT__) _if__(_BOUT__&&!_GENERIC__) * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out} _fi__(_BOUT__&&!_GENERIC__) +_fi__(_AOUT__||_BOUT__) _if__(_COFF__) * COFF Symbols:: Symbol Attributes for COFF _fi__(_COFF__) @@ -1624,6 +1909,9 @@ _fi__(_COFF__) @node Symbol Value, Symbol Type, Symbol Attributes, Symbol Attributes @subsection Value + +@cindex value of a symbol +@cindex symbol 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. @@ -1641,19 +1929,22 @@ 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. +_if__(!(_AOUT__||_BOUT__)) +@node Symbol Type, COFF Symbols, Symbol Value, Symbol Attributes +_fi__(!(_AOUT__||_BOUT__)) +_if__((_AOUT__||_BOUT__)) @node Symbol Type, a.out Symbols, Symbol Value, Symbol Attributes +_fi__((_AOUT__||_BOUT__)) @subsection Type + +@cindex type of a symbol +@cindex symbol 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__) -@menu -* Symbol Desc:: Descriptor -* Symbol Other:: Other -@end menu - _if__(_COFF__) @node a.out Symbols, COFF Symbols, Symbol Type, Symbol Attributes _fi__(_COFF__) @@ -1662,6 +1953,9 @@ _if__(!_COFF__) _fi__(!_COFF__) _if__(_BOUT__&&!_GENERIC__) @subsection Symbol Attributes: @code{a.out}, @code{b.out} + +@cindex @code{b.out} symbol attributes +@cindex symbol attributes, @code{b.out} These symbol attributes appear only when @code{_AS__} is configured for one of the Berkeley-descended object output formats. _fi__(_BOUT__&&!_GENERIC__) @@ -1669,6 +1963,9 @@ _if__(_GENERIC__||!_BOUT__) @subsection Symbol Attributes: @code{a.out} _fi__(_GENERIC__||!_BOUT__) +@cindex @code{a.out} symbol attributes +@cindex symbol attributes, @code{a.out} + @menu * Symbol Desc:: Descriptor * Symbol Other:: Other @@ -1676,6 +1973,8 @@ _fi__(_GENERIC__||!_BOUT__) @node Symbol Desc, Symbol Other, a.out Symbols, a.out Symbols @subsubsection Descriptor + +@cindex descriptor, of @code{a.out} symbol This is an arbitrary 16-bit value. You may establish a symbol's descriptor value by using a @code{.desc} statement (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to @@ -1683,21 +1982,36 @@ descriptor value by using a @code{.desc} statement @node Symbol Other, , Symbol Desc, a.out Symbols @subsubsection Other + +@cindex other attribute, of @code{a.out} symbol This is an arbitrary 8-bit value. It means nothing to @code{_AS__}. _fi__(_AOUT__||_BOUT__) _if__(_COFF__) +_if__(!(_AOUT__||_BOUT__)) +@node COFF Symbols, , Symbol Type, Symbol Attributes +_fi__(!(_AOUT__||_BOUT__)) +_if__(_AOUT__||_BOUT__) @node COFF Symbols, , a.out Symbols, Symbol Attributes +_fi__(_AOUT__||_BOUT__) @subsection Symbol Attributes for COFF + +@cindex COFF symbol attributes +@cindex symbol attributes, COFF + The COFF format supports a multitude of auxiliary symbol attributes; like the primary symbol attributes, they are set between @code{.def} and @code{.endef} directives. @subsubsection Primary Attributes + +@cindex primary attributes, COFF symbols The symbol name is set with @code{.def}; the value and type, respectively, with @code{.val} and @code{.type}. @subsubsection Auxiliary Attributes + +@cindex auxiliary attributes, COFF symbols The @code{_AS__} directives @code{.dim}, @code{.line}, @code{.scl}, @code{.size}, and @code{.tag} can generate auxiliary symbol table information for COFF. @@ -1705,6 +2019,10 @@ _fi__(_COFF__) @node Expressions, Pseudo Ops, Symbols, Top @chapter Expressions + +@cindex expressions +@cindex addresses +@cindex numeric values An @dfn{expression} specifies an address or numeric value. Whitespace may precede and/or follow an expression. @@ -1715,6 +2033,9 @@ Whitespace may precede and/or follow an expression. @node Empty Exprs, Integer Exprs, Expressions, Expressions @section Empty Expressions + +@cindex empty expressions +@cindex expressions, empty An empty expression has no value: it is just whitespace or null. Wherever an absolute expression is required, you may omit the expression and @code{_AS__} will assume a value of (absolute) 0. This @@ -1722,6 +2043,9 @@ is compatible with other assemblers. @node Integer Exprs, , Empty Exprs, Expressions @section Integer Expressions + +@cindex integer expressions +@cindex expressions, integer An @dfn{integer expression} is one or more @emph{arguments} delimited by @emph{operators}. @@ -1735,6 +2059,10 @@ by @emph{operators}. @node Arguments, Operators, Integer Exprs, Integer Exprs @subsection Arguments +@cindex expression arguments +@cindex arguments in expressions +@cindex operands in expressions +@cindex arithmetic operands @dfn{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 @@ -1755,19 +2083,26 @@ these 32 bits are an integer. You may write integer-manipulating instructions that act on exotic constants, compatible with other assemblers. +@cindex subexpressions Subexpressions are a left parenthesis @samp{(} followed by an integer expression, followed by a right parenthesis @samp{)}; or a prefix operator followed by an argument. @node Operators, Prefix Ops, Arguments, Integer Exprs @subsection Operators + +@cindex operators, in expressions +@cindex arithmetic functions +@cindex functions, in expressions @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix operators are followed by an argument. Infix operators appear between their arguments. Operators may be preceded and/or followed by whitespace. @node Prefix Ops, Infix Ops, Operators, Integer Exprs -@subsection Prefix Operators +@subsection Prefix Operator + +@cindex prefix operators @code{_AS__} has the following @dfn{prefix operators}. They each take one argument, which must be absolute. @@ -1792,25 +2127,34 @@ one argument, which must be absolute. @node Infix Ops, , Prefix Ops, Integer Exprs @subsection Infix Operators +@cindex infix operators +@cindex operators, permitted arguments @dfn{Infix operators} take two arguments, one on either side. Operators have precedence, but operations with equal precedence are performed left to right. Apart from @code{+} or @code{-}, both arguments must be absolute, and the result is absolute. @enumerate +@cindex operator precedence +@cindex precedence of operators @item Highest Precedence + @table @code @item * @dfn{Multiplication}. + @item / @dfn{Division}. Truncation is the same as the C operator @samp{/} + @item % @dfn{Remainder}. + @item _0__<_1__ @itemx _0__<<_1__ @dfn{Shift Left}. Same as the C operator @samp{_0__<<_1__} + @item _0__>_1__ @itemx _0__>>_1__ @dfn{Shift Right}. Same as the C operator @samp{_0__>>_1__} @@ -1818,26 +2162,39 @@ Highest Precedence @item Intermediate precedence + @table @code @item | + @dfn{Bitwise Inclusive Or}. + @item & @dfn{Bitwise And}. + @item ^ @dfn{Bitwise Exclusive Or}. + @item ! @dfn{Bitwise Or Not}. @end table @item Lowest Precedence + @table @code @item + +@cindex addition, permitted arguments +@cindex plus, permitted arguments +@cindex arguments for addition @dfn{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 @code{+} is illegal. + @item - +@cindex subtraction, permitted arguments +@cindex minus, permitted arguments +@cindex arguments for subtraction @dfn{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. @@ -1857,12 +2214,17 @@ Similarly, you can't subtract quantities from two different sections. @node Pseudo Ops, _MACH_DEP__, Expressions, Top @chapter Assembler Directives +@cindex directives, machine independent +@cindex pseudo-ops, machine independent +@cindex machine independent directives All assembler directives have names that begin with a period (@samp{.}). -The rest of the name is letters: their case does not matter. +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; @pxref{_MACH_DEP__} for -additional directives. +machine configuration for the GNU assembler. +_if__(!_H8__) +@xref{_MACH_DEP__} for additional directives. +_fi__(!_H8__) @menu * Abort:: @code{.abort} @@ -1882,11 +2244,14 @@ _fi__(_BOUT__&&!_COFF__) _if__(_COFF__||_BOUT__) * Def:: @code{.def @var{name}} _fi__(_COFF__||_BOUT__) +_if__(_AOUT__||_BOUT__) * Desc:: @code{.desc @var{symbol}, @var{abs-expression}} +_fi__(_AOUT__||_BOUT__) _if__(_COFF__||_BOUT__) * Dim:: @code{.dim} _fi__(_COFF__||_BOUT__) * Double:: @code{.double @var{flonums}} +* Eject:: @code{.eject} * Else:: @code{.else} _if__(_COFF__||_BOUT__) * Endef:: @code{.endef} @@ -1906,21 +2271,25 @@ _fi__(_GENERIC__||!_A29K__) * Include:: @code{.include "@var{file}"} * Int:: @code{.int @var{expressions}} * Lcomm:: @code{.lcomm @var{symbol} , @var{length}} +* Lflags:: @code{.lflags} _if__(_GENERIC__||!_A29K__) * Line:: @code{.line @var{line-number}} _fi__(_GENERIC__||!_A29K__) * Ln:: @code{.ln @var{line-number}} -* List:: @code{.list} and related directives +* List:: @code{.list} * Long:: @code{.long @var{expressions}} * Lsym:: @code{.lsym @var{symbol}, @var{expression}} +* Nolist:: @code{.nolist} * Octa:: @code{.octa @var{bignums}} * Org:: @code{.org @var{new-lc} , @var{fill}} +* Psize:: @code{.psize @var{lines}, @var{columns}} * Quad:: @code{.quad @var{bignums}} +* Sbttl:: @code{.sbttl "@var{subheading}"} _if__(_COFF__||_BOUT__) * Scl:: @code{.scl @var{class}} _fi__(_COFF__||_BOUT__) _if__(_COFF__) -* Section:: @code{.section @var{name}} +* Section:: @code{.section @var{name}, @var{subsection}} _fi__(_COFF__) * Set:: @code{.set @var{symbol}, @var{expression}} * Short:: @code{.short @var{expressions}} @@ -1936,6 +2305,7 @@ _if__(_COFF__||_BOUT__) * Tag:: @code{.tag @var{structname}} _fi__(_COFF__||_BOUT__) * Text:: @code{.text @var{subsection}} +* Title:: @code{.title "@var{heading}"} _if__(_COFF__||_BOUT__) * Type:: @code{.type @var{int}} * Val:: @code{.val @var{addr}} @@ -1954,6 +2324,9 @@ _if__(! (_BOUT__ || _COFF__) ) @node Abort, Align, Pseudo Ops, Pseudo Ops _fi__(! (_BOUT__ || _COFF__) ) @section @code{.abort} + +@cindex @code{abort} directive +@cindex stopping the assembly 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 @@ -1963,6 +2336,8 @@ quit also. One day @code{.abort} will not be supported. _if__(_COFF__) @node coff-ABORT, Align, Abort, Pseudo Ops @section @code{.ABORT} + +@cindex @code{ABORT} directive When producing COFF output, @code{_AS__} accepts this directive as a synonym for @samp{.abort}. _fi__(_COFF__) @@ -1971,6 +2346,8 @@ _if__(_BOUT__) _if__(!_COFF__) @node bout-ABORT, Align, Abort, Pseudo Ops @section @code{.ABORT} + +@cindex @code{ABORT} directive _fi__(!_COFF__) When producing @code{b.out} output, @code{_AS__} accepts this directive, @@ -1987,6 +2364,11 @@ _if__( _BOUT__ && (! _COFF__)) @node Align, App-File, bout-ABORT, Pseudo Ops _fi__( _BOUT__ && (! _COFF__)) @section @code{.align @var{abs-expr} , @var{abs-expr}} + +@cindex padding the location counter +@cindex advancing location counter +@cindex location counter, advancing +@cindex @code{align} directive 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 @@ -2000,6 +2382,10 @@ omitted, the padding bytes are zero. @node App-File, Ascii, Align, Pseudo Ops @section @code{.app-file @var{string}} + +@cindex logical file name +@cindex file name, logical +@cindex @code{app-file} directive @code{.app-file} _if__(!_A29K__) (which may also be spelled @samp{.file}) @@ -2014,23 +2400,35 @@ programs.@refill @node Ascii, Asciz, App-File, Pseudo Ops @section @code{.ascii "@var{string}"}@dots{} + +@cindex @code{ascii} directive +@cindex string literals @code{.ascii} expects zero or more string literals (@pxref{Strings}) separated by commas. It assembles each string (with no automatic trailing zero byte) into consecutive addresses. @node Asciz, Byte, Ascii, Pseudo Ops @section @code{.asciz "@var{string}"}@dots{} + +@cindex @code{asciz} directive +@cindex zero-terminated strings +@cindex null-terminated strings @code{.asciz} is just like @code{.ascii}, but each string is followed by a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''. @node Byte, Comm, Asciz, Pseudo Ops @section @code{.byte @var{expressions}} +@cindex @code{byte} directive +@cindex integers, one byte @code{.byte} expects zero or more expressions, separated by commas. Each expression is assembled into the next byte. @node Comm, Data, Byte, Pseudo Ops @section @code{.comm @var{symbol} , @var{length} } + +@cindex @code{comm} directive +@cindex symbol, common @code{.comm} declares a named common area in the bss section. Normally @code{_LD__} reserves memory addresses for it during linking, so no partial program defines the location of the symbol. Use @code{.comm} to tell @@ -2050,6 +2448,8 @@ _if__(! (_COFF__ || _BOUT__ || _AOUT__) ) @node Data, Double, Comm, Pseudo Ops _fi__(! (_COFF__ || _BOUT__ || _AOUT__) ) @section @code{.data @var{subsection}} + +@cindex @code{data} directive @code{.data} tells @code{_AS__} to assemble the following statements onto the end of the data subsection numbered @var{subsection} (which is an absolute expression). If @var{subsection} is omitted, it defaults @@ -2063,6 +2463,10 @@ _if__(!(_AOUT__ || _BOUT__)) @node Def, Dim, Data, Pseudo Ops _fi__(!(_AOUT__ || _BOUT__)) @section @code{.def @var{name}} + +@cindex @code{def} directive +@cindex COFF symbols, debugging +@cindex debugging COFF symbols Begin defining debugging information for a symbol @var{name}; the definition extends until the @code{.endef} directive is encountered. _if__(_BOUT__) @@ -2081,6 +2485,10 @@ _if__(!(_COFF__||_BOUT__)) @node Desc, Double, Data, Pseudo Ops _fi__(!(_COFF__||_BOUT__)) @section @code{.desc @var{symbol}, @var{abs-expression}} + +@cindex @code{desc} directive +@cindex COFF symbol descriptor +@cindex symbol descriptor, COFF This directive sets the descriptor of the symbol (@pxref{Symbol Attributes}) to the low 16 bits of an absolute expression. @@ -2100,6 +2508,10 @@ _if__(!(_AOUT__ || _BOUT__)) @node Dim, Double, Def, Pseudo Ops _fi__(!(_AOUT__ || _BOUT__)) @section @code{.dim} + +@cindex @code{dim} directive +@cindex COFF auxiliary symbol information +@cindex auxiliary symbol information, COFF This directive is generated by compilers to include auxiliary debugging information in the symbol table. It is only permitted inside @code{.def}/@code{.endef} pairs. @@ -2112,12 +2524,15 @@ _fi__(_BOUT__) _fi__(_COFF__ || _BOUT__) _if__(_COFF__||_BOUT__) -@node Double, Else, Dim, Pseudo Ops +@node Double, Eject, Dim, Pseudo Ops _fi__(_COFF__||_BOUT__) _if__(!(_COFF__||_BOUT__)) -@node Double, Else, Desc, Pseudo Ops +@node Double, Eject, Desc, Pseudo Ops _fi__(!(_COFF__||_BOUT__)) @section @code{.double @var{flonums}} + +@cindex @code{double} directive +@cindex floating point numbers (double) @code{.double} expects zero or more flonums, separated by commas. It assembles floating point numbers. _if__(_GENERIC__) @@ -2126,16 +2541,27 @@ The exact kind of floating point numbers emitted depends on how _fi__(_GENERIC__) _if__((!_GENERIC__) && _IEEEFLOAT__) On the _HOST__ family @samp{.double} emits 64-bit floating-point numbers -in IEEE format. +in @sc{ieee} format. _fi__((!_GENERIC__) && _IEEEFLOAT__) +@node Eject, Else, Double, Pseudo Ops +@section @code{.eject} + +@cindex @code{eject} directive +@cindex new page, in listings +@cindex page, in listings +@cindex listing control: new page +Force a page break at this point, when generating assembly listings. + _if__(_COFF__||_BOUT__) -@node Else, Endef, Double, Pseudo Ops +@node Else, Endef, Eject, Pseudo Ops _fi__(_COFF__||_BOUT__) _if__(!(_COFF__||_BOUT__)) -@node Else, Endif, Double, Pseudo Ops +@node Else, Endif, Eject, Pseudo Ops _fi__(!(_COFF__||_BOUT__)) @section @code{.else} + +@cindex @code{else} directive @code{.else} is part of the @code{_AS__} support for conditional assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section of code to be assembled if the condition for the preceding @code{.if} @@ -2144,6 +2570,8 @@ was false. _if__(0) @node End, Endef, Else, Pseudo Ops @section @code{.end} + +@cindex @code{end} directive 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"). @@ -2152,6 +2580,8 @@ _fi__(0) _if__(_COFF__||_BOUT__) @node Endef, Endif, Else, Pseudo Ops @section @code{.endef} + +@cindex @code{endef} directive This directive flags the end of a symbol definition begun with @code{.def}. _if__(_BOUT__) @@ -2169,6 +2599,8 @@ _if__(!(_COFF__||_BOUT__)) @node Endif, Equ, Else, Pseudo Ops _fi__(!(_COFF__||_BOUT__)) @section @code{.endif} + +@cindex @code{endif} directive @code{.endif} is part of the @code{_AS__} support for conditional assembly; it marks the end of a block of code that is only assembled conditionally. @xref{If,,@code{.if}}. @@ -2176,6 +2608,9 @@ conditionally. @xref{If,,@code{.if}}. @node Equ, Extern, Endif, Pseudo Ops @section @code{.equ @var{symbol}, @var{expression}} +@cindex @code{equ} directive +@cindex assigning values to symbols +@cindex symbols, assigning values to This directive sets the value of @var{symbol} to @var{expression}. It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}. @@ -2186,13 +2621,19 @@ _if__(_A29K__&&!_GENERIC__) @node Extern, Fill, Equ, Pseudo Ops _fi__(_A29K__&&!_GENERIC__) @section @code{.extern} + +@cindex @code{extern} directive @code{.extern} is accepted in the source program---for compatibility with other assemblers---but it is ignored. @code{_AS__} treats all undefined symbols as external. _if__(_GENERIC__||!_A29K__) @node File, Fill, Extern, Pseudo Ops -@section @code{.app-file @var{string}} +@section @code{.file @var{string}} + +@cindex @code{file} directive +@cindex logical file name +@cindex file name, logical @code{.file} (which may also be spelled @samp{.app-file}) tells @code{_AS__} that we are about to start a new logical file. @var{string} is the new file name. In general, the filename is @@ -2213,6 +2654,10 @@ _if__(_A29K__&&!_GENERIC__) @node Fill, Float, Extern, Pseudo Ops _fi__(_A29K__&&!_GENERIC__) @section @code{.fill @var{repeat} , @var{size} , @var{value}} + +@cindex @code{fill} directive +@cindex writing patterns in memory +@cindex patterns, writing in memory @var{result}, @var{size} and @var{value} are absolute expressions. This emits @var{repeat} copies of @var{size} bytes. @var{Repeat} may be zero or more. @var{Size} may be zero or more, but if it is @@ -2232,6 +2677,9 @@ assumed zero. If the first comma and following tokens are absent, @node Float, Global, Fill, Pseudo Ops @section @code{.float @var{flonums}} + +@cindex floating point numbers (single) +@cindex @code{float} directive This directive assembles zero or more flonums, separated by commas. It has the same effect as @code{.single}. _if__(_GENERIC__) @@ -2241,23 +2689,20 @@ The exact kind of floating point numbers emitted depends on how _fi__(_GENERIC__) _if__((!_GENERIC__) && _IEEEFLOAT__) On the _HOST__ family, @code{.float} emits 32-bit floating point numbers -in IEEE format. +in @sc{ieee} format. _fi__((!_GENERIC__) && _IEEEFLOAT__) @node Global, hword, Float, Pseudo Ops @section @code{.global @var{symbol}}, @code{.globl @var{symbol}} + +@cindex @code{global} directive +@cindex symbol, making visible to linker @code{.global} makes the symbol visible to @code{_LD__}. If you define @var{symbol} in your partial program, its value is made available to other partial programs that are linked with it. Otherwise, @var{symbol} will take its attributes from a symbol of the same name from another partial program it is linked with. -_if__(!_I960__) -@c FIXME BFD implications; this is different in COFF. -This is done by setting the @code{N_EXT} bit of that symbol's type byte -to 1. @xref{Symbol Attributes}. -_fi__(!_I960__) - Both spellings (@samp{.globl} and @samp{.global}) are accepted, for compatibility with other assemblers. @@ -2268,6 +2713,11 @@ _if__(!(_AOUT__||_BOUT__||_COFF__)) @node hword, If, Global, Pseudo Ops _fi__(!(_AOUT__||_BOUT__||_COFF__)) @section @code{.hword @var{expressions}} + +@cindex @code{hword} directive +@cindex integers, 16-bit +@cindex numbers, 16-bit +@cindex sixteen bit integers This expects zero or more @var{expressions}, and emits a 16 bit number for each. @@ -2285,6 +2735,8 @@ _fi__(_W16__ && !_GENERIC__ ) _if__(_AOUT__||_BOUT__||_COFF__) @node Ident, If, hword, Pseudo Ops @section @code{.ident} + +@cindex @code{ident} directive This directive is used by some assemblers to place tags in object files. @code{_AS__} simply accepts the directive for source-file compatibility with such assemblers, but does not actually emit anything @@ -2298,6 +2750,9 @@ _if__(!(_AOUT__||_BOUT__||_COFF__)) @node If, Include, hword, Pseudo Ops _fi__(!(_AOUT__||_BOUT__||_COFF__)) @section @code{.if @var{absolute expression}} + +@cindex conditional assembly +@cindex @code{if} directive @code{.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 @var{absolute expression}) is non-zero. The end of @@ -2307,17 +2762,21 @@ alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}. The following variants of @code{.if} are also supported: @table @code -@item ifdef @var{symbol} +@item .ifdef @var{symbol} +@cindex @code{ifdef} directive Assembles the following section of code if the specified @var{symbol} has been defined. _if__(0) -@item ifeqs +@item .ifeqs +@cindex @code{ifeqs} directive Not yet implemented. _fi__(0) -@item ifndef @var{symbol} +@item .ifndef @var{symbol} @itemx ifnotdef @var{symbol} +@cindex @code{ifndef} directive +@cindex @code{ifnotdef} directive Assembles the following section of code if the specified @var{symbol} has not been defined. Both spelling variants are equivalent. @@ -2329,6 +2788,10 @@ _fi__(0) @node Include, Int, If, Pseudo Ops @section @code{.include "@var{file}"} + +@cindex @code{include} directive +@cindex supporting files, including +@cindex files, including This directive provides a way to include supporting files at specified points in your source program. The code from @var{file} is assembled as if it followed the point of the @code{.include}; when the end of the @@ -2339,25 +2802,29 @@ around @var{file}. @node Int, Lcomm, Include, Pseudo Ops @section @code{.int @var{expressions}} + +@cindex @code{int} directive +_if__(_GENERIC__||!_H8__) +@cindex integers, 32-bit +_fi__(_GENERIC__||!_H8__) Expect zero or more @var{expressions}, of any section, separated by commas. For each expression, emit a -_if__(!_H8__) +_if__(_GENERIC__||!_H8__) 32-bit -_fi__(!_H8__) -_if__(_H8__) +_fi__(_GENERIC__||!_H8__) +_if__(_H8__&&!_GENERIC__) 16-bit -_fi__(_H8__) +_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. -_if__(_GENERIC__||(!_A29K__)) -@node Lcomm, Line, Int, Pseudo Ops -_fi__(_GENERIC__||(!_A29K__)) -_if__((!_GENERIC__)&& _A29K__) -@node Lcomm, Ln, Int, Pseudo Ops -_fi__((!_GENERIC__)&& _A29K__) +@node Lcomm, Lflags, Int, Pseudo Ops @section @code{.lcomm @var{symbol} , @var{length}} + +@cindex @code{lcomm} directive +@cindex local common symbols +@cindex symbols, local common Reserve @var{length} (an absolute expression) bytes for a local common denoted by @var{symbol}. The section and value of @var{symbol} are those of the new local common. The addresses are allocated in the bss @@ -2365,14 +2832,31 @@ section, so at run-time the bytes will start off zeroed. @var{Symbol} is not declared global (@pxref{Global,,@code{.global}}), so is normally not visible to @code{_LD__}. +_if__(_GENERIC__||(!_A29K__)) +@node Lflags, Line, Lcomm, Pseudo Ops +_fi__(_GENERIC__||(!_A29K__)) +_if__((!_GENERIC__)&& _A29K__) +@node Lflags, Ln, Lcomm, Pseudo Ops +_fi__((!_GENERIC__)&& _A29K__) +@section @code{.lflags} + +@cindex @code{lflags} directive (ignored) +@code{_AS__} accepts this directive, for compatibility with other +assemblers, but ignores it. + _if__(_GENERIC__ || !_A29K__) -@node Line, Ln, Lcomm, Pseudo Ops +@node Line, Ln, Lflags, Pseudo Ops @section @code{.line @var{line-number}} + +@cindex @code{line} directive _fi__(_GENERIC__ || (!_A29K__)) _if__(_A29K__ && (!_GENERIC__)) -@node Ln, List, Lcomm, Pseudo Ops +@node Ln, List, Lflags, Pseudo Ops @section @code{.ln @var{line-number}} + +@cindex @code{ln} directive _fi__(_A29K__ && (!_GENERIC__)) +@cindex logical line number _if__(_AOUT__||_BOUT__) Tell @code{_AS__} to change the logical line number. @var{line-number} must be an absolute expression. The next line will have that logical line @@ -2419,11 +2903,15 @@ _fi__(_COFF__) _if__(_AOUT__&&(_GENERIC__||!_A29K__)) @node Ln, List, Line, Pseudo Ops @section @code{.ln @var{line-number}} + +@cindex @code{ln} directive @samp{.ln} is a synonym for @samp{.line}. _fi__(_AOUT__&&(_GENERIC__||!_A29K__)) _if__(_COFF__&&!_AOUT__) @node Ln, List, Line, Pseudo Ops @section @code{.ln @var{line-number}} + +@cindex @code{ln} directive Tell @code{_AS__} to change the logical line number. @var{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 @@ -2437,17 +2925,31 @@ _fi__(_BOUT__) _fi__(_COFF__&&!_AOUT__) @node List, Long, Ln, Pseudo Ops -@section @code{.list} and related directives -@code{_AS__} ignores the directives @code{.list}, @code{.nolist}, -@code{.eject}, @code{.lflags}, @code{.title}, @code{.sbttl}; however, -they're accepted for compatibility with assemblers that use them. +@section @code{.list} + +@cindex @code{list} directive +@cindex listing control, turning on +Control (in conjunction with the @code{.nolist} directive) whether or +not assembly listings are generated. These two directives maintain an +internal counter (which is zero initially). @code{.list} increments the +counter, and @code{.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 +@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}), +the initial value of the listing counter is one. @node Long, Lsym, List, Pseudo Ops @section @code{.long @var{expressions}} + +@cindex @code{long} directive @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}. -@node Lsym, Octa, Long, Pseudo Ops +@node Lsym, Nolist, Long, Pseudo Ops @section @code{.lsym @var{symbol}, @var{expression}} + +@cindex @code{lsym} directive +@cindex symbol, not referenced in assembly @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in the hash table, ensuring it cannot be referenced by name during the rest of the assembly. This sets the attributes of the symbol to be @@ -2460,18 +2962,37 @@ the same as the expression value: @noindent The new symbol is not flagged as external. -@c FIXME: double size emitted for "octa" on i960, others? Or warn? -@node Octa, Org, Lsym, Pseudo Ops +@node Nolist, Octa, Lsym, Pseudo Ops +@section @code{.nolist} + +@cindex @code{nolist} directive +@cindex listing control, turning off +Control (in conjunction with the @code{.list} directive) whether or +not assembly listings are generated. These two directives maintain an +internal counter (which is zero initially). @code{.list} increments the +counter, and @code{.nolist} decrements it. Assembly listings are +generated whenever the counter is greater than zero. + +@node Octa, Org, Nolist, Pseudo Ops @section @code{.octa @var{bignums}} + +@c FIXME: double size emitted for "octa" on i960, others? Or warn? +@cindex @code{octa} directive +@cindex integer, 16-byte +@cindex sixteen byte integer 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 @emph{octa}-word for 16 bytes. -@node Org, Quad, Octa, Pseudo Ops +@node Org, Psize, Octa, Pseudo Ops @section @code{.org @var{new-lc} , @var{fill}} +@cindex @code{org} directive +@cindex location counter, advancing +@cindex advancing location counter +@cindex current address, advancing @code{.org} will advance the location counter of the current section to @var{new-lc}. @var{new-lc} is either an absolute expression or an expression with the same section as the current subsection. That is, @@ -2501,19 +3022,38 @@ intervening bytes are filled with @var{fill} which should be an absolute expression. If the comma and @var{fill} are omitted, @var{fill} defaults to zero. -_if__(_COFF__||_BOUT__) -@node Quad, Scl, Org, Pseudo Ops -_fi__(_COFF__||_BOUT__) -_if__(!(_COFF__||_BOUT__)) -@node Quad, Set, Org, Pseudo Ops -_fi__(!(_COFF__||_BOUT__)) +@node Psize, Quad, Org, Pseudo Ops +@section @code{.psize @var{lines} , @var{columns}} + +@cindex @code{psize} directive +@cindex listing control: paper size +@cindex paper size, for listings +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 @code{.psize}, listings will use a default line-count +of 60. You may omit the comma and @var{columns} specification; the +default width is 200 columns. + +@code{_AS__} will generate formfeeds whenever the specified number of +lines is exceeded (or whenever you explicitly request one, using +@code{.eject}). + +If you specify @var{lines} as @code{0}, no formfeeds are generated save +those explicitly specified with @code{.eject}. + +@node Quad, Sbttl, Psize, Pseudo Ops @section @code{.quad @var{bignums}} + +@cindex @code{quad} directive @code{.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.@refill +@cindex eight-byte integer +@cindex integer, 8-byte The term ``quad'' comes from contexts in which a ``word'' is two bytes; hence @emph{quad}-word for 8 bytes. @@ -2522,16 +3062,39 @@ _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.@refill +@cindex sixteen-byte integer +@cindex integer, 16-byte _fi__(_I960__&&(!_GENERIC__)) _if__(_COFF__||_BOUT__) +@node Sbttl, Scl, Quad, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Sbttl, Set, Quad, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.sbttl "@var{subheading}"} + +@cindex @code{sbttl} directive +@cindex subtitles for listings +@cindex listing control: subtitle +Use @var{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__) _if__(!_COFF__) -@node Scl, Set, Quad, Pseudo Ops +@node Scl, Set, Sbttl, Pseudo Ops _fi__(!_COFF__) _if__(_COFF__) -@node Scl, Section, Quad, Pseudo Ops +@node Scl, Section, Sbttl, Pseudo Ops _fi__(_COFF__) @section @code{.scl @var{class}} + +@cindex @code{scl} directive +@cindex symbol storage class (COFF) +@cindex COFF symbol storage class Set the storage-class value for a symbol. This directive may only be used inside a @code{.def}/@code{.endef} pair. Storage class may flag whether a symbol is static or external, or it may record further @@ -2546,8 +3109,14 @@ _fi__(_COFF__||_BOUT__) _if__(_COFF__) @node Section, Set, Scl, Pseudo Ops -@section @code{.section} @var{name} -Assemble the following code into the COFF section @var{name}. +@section @code{.section @var{name}, @var{subsection}} + +@cindex @code{section} directive +@cindex named section (COFF) +@cindex COFF named section +Assemble the following code into end of subsection numbered +@var{subsection} in the COFF named section @var{name}. If you omit +@var{subsection}, @code{_AS__} uses subsection number zero. @samp{.section .text} is equivalent to the @code{.text} directive; @samp{.section .data} is equivalent to the @code{.data} directive. @@ -2561,6 +3130,8 @@ _if__(!(_COFF__||_BOUT__)) _fi__(!(_COFF__||_BOUT__)) @section @code{.set @var{symbol}, @var{expression}} +@cindex @code{set} directive +@cindex symbol value, setting This directive sets the value of @var{symbol} to @var{expression}. This will change @var{symbol}'s value and type to conform to @var{expression}. If @var{symbol} was flagged as external, it remains @@ -2577,6 +3148,8 @@ file is the last value stored into it. @node Short, Single, Set, Pseudo Ops @section @code{.short @var{expressions}} + +@cindex @code{short} directive _if__(_GENERIC__ || _W16__) @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}. _if__(_W32__) @@ -2595,6 +3168,9 @@ _if__(!(_COFF__||_BOUT__)) @node Single, Space, Short, Pseudo Ops _fi__(!(_COFF__||_BOUT__)) @section @code{.single @var{flonums}} + +@cindex @code{single} directive +@cindex floating point numbers (single) This directive assembles zero or more flonums, separated by commas. It has the same effect as @code{.float}. _if__(_GENERIC__) @@ -2603,12 +3179,14 @@ The exact kind of floating point numbers emitted depends on how _fi__(_GENERIC__) _if__((!_GENERIC__) && _IEEEFLOAT__) On the _HOST__ family, @code{.single} emits 32-bit floating point -numbers in IEEE format. +numbers in @sc{ieee} format. _fi__((!_GENERIC__) && _IEEEFLOAT__) _if__(_COFF__||_BOUT__) @node Size, Space, Single, Pseudo Ops @section @code{.size} + +@cindex @code{size} directive This directive is generated by compilers to include auxiliary debugging information in the symbol table. It is only permitted inside @code{.def}/@code{.endef} pairs. @@ -2633,6 +3211,9 @@ _fi__(!(_COFF__||_BOUT__)) _fi__(!_H8__) _if__(_GENERIC__ || !_A29K__) @section @code{.space @var{size} , @var{fill}} + +@cindex @code{space} directive +@cindex filling memory This directive emits @var{size} bytes, each of value @var{fill}. Both @var{size} and @var{fill} are absolute expressions. If the comma and @var{fill} are omitted, @var{fill} is assumed to be zero. @@ -2640,6 +3221,8 @@ _fi__(_GENERIC__ || !_A29K__) _if__(_A29K__) @section @code{.space} + +@cindex @code{space} directive On the AMD 29K, this directive is ignored; it is accepted for compatibility with other AMD 29K assemblers. @@ -2658,6 +3241,9 @@ _if__(!(_COFF__||_BOUT__)) @node Stab, Text, Space, Pseudo Ops _fi__(!(_COFF__||_BOUT__)) @section @code{.stabd, .stabn, .stabs} + +@cindex symbolic debuggers, information for +@cindex @code{stab@var{x}} directives There are three directives that begin @samp{.stab}. All emit symbols (@pxref{Symbols}), for use by symbolic debuggers. The symbols are not entered in the @code{_AS__} hash table: they @@ -2689,6 +3275,7 @@ and you will get a half-formed symbol in your object file. This is compatible with earlier assemblers! @table @code +@cindex @code{stabd} directive @item .stabd @var{type} , @var{other} , @var{desc} The ``name'' of the symbol generated is not even an empty string. @@ -2702,11 +3289,11 @@ will be where the location counter was when the @code{.stabd} was assembled. @item .stabn @var{type} , @var{other} , @var{desc} , @var{value} - +@cindex @code{stabn} directive The name of the symbol is set to the empty string @code{""}. @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value} - +@cindex @code{stabs} directive All five fields are specified. @end table _fi__(_AOUT__||_BOUT__||_COFF__) @@ -2720,6 +3307,10 @@ _if__(_H8__) @node Tag, Text, Space, Pseudo Ops _fi__(_H8__) @section @code{.tag @var{structname}} + +@cindex COFF structure debugging +@cindex structure debugging, COFF +@cindex @code{tag} directive This directive is generated by compilers to include auxiliary debugging information in the symbol table. It is only permitted inside @code{.def}/@code{.endef} pairs. Tags are used to link structure @@ -2733,20 +3324,42 @@ _fi__(_BOUT__) _fi__(_COFF__||_BOUT__) _if__(_COFF__||_BOUT__) -@node Text, Type, Tag, Pseudo Ops +@node Text, Title, Tag, Pseudo Ops _fi__(_COFF__||_BOUT__) _if__(!(_COFF__||_BOUT__)) -@node Text, Word, Stab, Pseudo Ops +@node Text, Title, Stab, Pseudo Ops _fi__(!(_COFF__||_BOUT__)) @section @code{.text @var{subsection}} + +@cindex @code{text} directive Tells @code{_AS__} to assemble the following statements onto the end of the text subsection numbered @var{subsection}, which is an absolute expression. If @var{subsection} is omitted, subsection number zero is used. _if__(_COFF__||_BOUT__) -@node Type, Val, Text, Pseudo Ops +@node Title, Type, Text, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Title, Word, Text, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.title "@var{heading}"} + +@cindex @code{title} directive +@cindex listing control: title line +Use @var{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__) +@node Type, Val, Title, Pseudo Ops @section @code{.type @var{int}} + +@cindex COFF symbol type +@cindex symbol type, COFF +@cindex @code{type} directive This directive, permitted only within @code{.def}/@code{.endef} pairs, records the integer @var{int} as the type attribute of a symbol table entry. _if__(_BOUT__) @@ -2760,6 +3373,10 @@ _fi__(_COFF__||_BOUT__) _if__(_COFF__||_BOUT__) @node Val, Word, Type, Pseudo Ops @section @code{.val @var{addr}} + +@cindex @code{val} directive +@cindex COFF value attribute +@cindex value attribute, COFF This directive, permitted only within @code{.def}/@code{.endef} pairs, records the address @var{addr} as the value attribute of a symbol table entry. @@ -2777,6 +3394,8 @@ _if__(!(_COFF__||_BOUT__)) @node Word, Deprecated, Text, Pseudo Ops _fi__(!(_COFF__||_BOUT__)) @section @code{.word @var{expressions}} + +@cindex @code{word} directive This directive expects zero or more @var{expressions}, of any section, separated by commas. _if__((!_GENERIC__) && _W32__) @@ -2794,6 +3413,8 @@ _fi__(_GENERIC__) @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't @c happen---32-bit addressability, period; no long/short jumps. _if__(_GENERIC__ || _DIFFTABKLUG__) +@cindex difference tables altered +@cindex altered difference tables @quotation @emph{Warning: Special Treatment to support Compilers} @end quotation @@ -2836,6 +3457,9 @@ _fi__(_GENERIC__ || _DIFFTABKLUG__) @node Deprecated, , Word, Pseudo Ops @section Deprecated Directives + +@cindex deprecated directives +@cindex obsolescent directives One day these directives won't work. They are included for compatibility with older assemblers. @table @t @@ -2847,6 +3471,20 @@ They are included for compatibility with older assemblers. @node _MACH_DEP__, Copying, Pseudo Ops, Top _if__(_GENERIC__) @chapter Machine Dependent Features + +@cindex machine dependencies +The machine instruction sets are (almost by definition) different on +each machine where @code{_AS__} runs. Floating point representations +vary as well, and @code{_AS__} often supports a few additional +directives or command-line options for compatibility with other +assemblers on a particular platform. Finally, some versions of +@code{_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. + @menu _if__(_VAX__) * Vax-Dependent:: VAX Dependent Features @@ -2855,7 +3493,7 @@ _if__(_A29K__) * AMD29K-Dependent:: AMD 29K Dependent Features _fi__(_A29K__) _if__(_H8__) -* H8-300-Dependent:: AMD 29K Dependent Features +* H8/300-Dependent:: AMD 29K Dependent Features _fi__(_H8__) _if__(_I960__) * i960-Dependent:: Intel 80960 Dependent Features @@ -2877,6 +3515,8 @@ _if__(_GENERIC__) @node Vax-Dependent, AMD29K-Dependent, Machine Dependent, Machine Dependent _fi__(_GENERIC__) _CHAPSEC__(0+_GENERIC__) VAX Dependent Features + +@cindex VAX support @menu * Vax-Opts:: VAX Command-Line Options * VAX-float:: VAX Floating Point @@ -2890,6 +3530,8 @@ _CHAPSEC__(0+_GENERIC__) VAX Dependent Features @node Vax-Opts, VAX-float, Vax-Dependent, Vax-Dependent _CHAPSEC__(1+_GENERIC__) VAX Command-Line Options +@cindex command-line options ignored, VAX +@cindex VAX command-line options ignored The Vax version of @code{_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 @@ -2899,21 +3541,27 @@ people's assemblers. @item @kbd{-D} (Debug) @itemx @kbd{-S} (Symbol Table) @itemx @kbd{-T} (Token Trace) +@cindex @code{-D}, ignored on VAX +@cindex @code{-S}, ignored on VAX +@cindex @code{-T}, ignored on VAX These are obsolete options used to debug old assemblers. @item @kbd{-d} (Displacement size for JUMPs) +@cindex @code{-d}, VAX option This option expects a number following the @kbd{-d}. Like options that expect filenames, the number may immediately follow the @kbd{-d} (old standard) or constitute the whole of the command line argument that follows @kbd{-d} (GNU standard). @item @kbd{-V} (Virtualize Interpass Temporary File) +@cindex @code{-V}, redundant on VAX Some other assemblers use a temporary file. This option commanded them to keep the information in active memory rather than in a disk file. @code{_AS__} always does this, so this option is redundant. @item @kbd{-J} (JUMPify Longer Branches) +@cindex @code{-J}, ignored on VAX 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 @@ -2923,6 +3571,7 @@ assemblers would emit short and medium branches, unless told by this option to emit short and long branches. @item @kbd{-t} (Temporary File Directory) +@cindex @code{-t}, ignored on VAX Some other assemblers may use a temporary file, and this option takes a filename being the directory to site the temporary file. @code{_AS__} does not use a temporary disk file, so this @@ -2930,6 +3579,14 @@ option makes no difference. @kbd{-t} needs exactly one filename. @end table +@cindex VMS (VAX) options +@cindex options for VAX/VMS +@cindex VAX/VMS options +@cindex @code{-h} option, VAX/VMS +@cindex @code{-+} option, VAX/VMS +@cindex Vax-11 C compatibility +@cindex symbols with lowercase, VAX/VMS +@c FIXME! look into "I think" below, correct if needed, delete. The Vax version of the assembler accepts two options when compiled for VMS. They are @kbd{-h}, and @kbd{-+}. The @kbd{-h} option prevents @code{_AS__} from modifying the @@ -2943,6 +3600,9 @@ symbol so that the object file will be compatible with Vax-11 @node VAX-float, VAX-directives, Vax-Opts, Vax-Dependent _CHAPSEC__(1+_GENERIC__) VAX Floating Point + +@cindex VAX floating point +@cindex floating point, VAX 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. @@ -2954,29 +3614,39 @@ Immediate floating literals (@emph{e.g.} @samp{S`$6.9}) are rendered correctly. Again, rounding is towards zero in the boundary case. +@cindex @code{float} directive, VAX +@cindex @code{double} directive, VAX The @code{.float} directive produces @code{f} format numbers. The @code{.double} directive produces @code{d} format numbers. @node VAX-directives, VAX-opcodes, VAX-float, Vax-Dependent _CHAPSEC__(1+_GENERIC__) Vax Machine Directives + +@cindex machine directives, VAX +@cindex 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. +@cindex wide floating point directives, VAX @table @code @item .dfloat +@cindex @code{dfloat} directive, VAX This expects zero or more flonums, separated by commas, and assembles Vax @code{d} format 64-bit floating point constants. @item .ffloat +@cindex @code{ffloat} directive, VAX This expects zero or more flonums, separated by commas, and assembles Vax @code{f} format 32-bit floating point constants. @item .gfloat +@cindex @code{gfloat} directive, VAX This expects zero or more flonums, separated by commas, and assembles Vax @code{g} format 64-bit floating point constants. @item .hfloat +@cindex @code{hfloat} directive, VAX This expects zero or more flonums, separated by commas, and assembles Vax @code{h} format 128-bit floating point constants. @@ -2984,6 +3654,10 @@ assembles Vax @code{h} format 128-bit floating point constants. @node VAX-opcodes, VAX-branch, VAX-directives, Vax-Dependent _CHAPSEC__(1+_GENERIC__) VAX Opcodes + +@cindex VAX opcode mnemonics +@cindex opcode mnemonics, VAX +@cindex mnemonics for opcodes, VAX All DEC mnemonics are supported. Beware that @code{case@dots{}} instructions have exactly 3 operands. The dispatch table that follows the @code{case@dots{}} instruction should be made with @@ -2992,6 +3666,10 @@ assemblers we know of. @node VAX-branch, VAX-operands, VAX-opcodes, Vax-Dependent _CHAPSEC__(1+_GENERIC__) VAX Branch Improvement + +@cindex VAX branch improvement +@cindex branch improvement, VAX +@cindex pseudo-ops for branch, VAX 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 @@ -3097,17 +3775,28 @@ bar: @node VAX-operands, VAX-no, VAX-branch, Vax-Dependent _CHAPSEC__(1+_GENERIC__) VAX Operands + +@cindex VAX operand notation +@cindex operand notation, VAX +@cindex immediate character, VAX +@cindex VAX immediate character The immediate character is @samp{$} for Unix compatibility, not @samp{#} as DEC writes it. +@cindex indirect character, VAX +@cindex VAX indirect character The indirect character is @samp{*} for Unix compatibility, not @samp{@@} as DEC writes it. +@cindex displacement sizing character, VAX +@cindex VAX displacement sizing character The displacement sizing character is @samp{`} (an accent grave) for Unix compatibility, not @samp{^} as DEC writes it. The letter preceding @samp{`} may have either case. @samp{G} is not understood, but all other letters (@code{b i l s w}) are understood. +@cindex register names, VAX +@cindex VAX register names Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp pc}. Any case of letters will do. @@ -3126,15 +3815,21 @@ separated. @node VAX-no, , VAX-operands, Vax-Dependent _CHAPSEC__(1+_GENERIC__) Not Supported on VAX + +@cindex VAX bitfields not supported +@cindex bitfields, not supported on VAX Vax bit fields can not be assembled with @code{_AS__}. Someone can add the required code if they really need it. _fi__(_VAX__) _if__(_A29K__) _if__(_GENERIC__) -@node AMD29K-Dependent, H8-300-Dependent, Vax-Dependent, Machine Dependent +@node AMD29K-Dependent, H8/300-Dependent, Vax-Dependent, Machine Dependent _fi__(_GENERIC__) _CHAPSEC__(0+_GENERIC__) AMD 29K Dependent Features + +@cindex AMD 29K support +@cindex 29K support @menu * AMD29K Options:: Options * AMD29K Syntax:: Syntax @@ -3145,6 +3840,8 @@ _CHAPSEC__(0+_GENERIC__) AMD 29K Dependent Features @node AMD29K Options, AMD29K Syntax, AMD29K-Dependent, AMD29K-Dependent _CHAPSEC__(1+_GENERIC__) Options +@cindex AMD 29K options (none) +@cindex options for AMD29K (none) @code{_AS__} has no additional command-line options for the AMD 29K family. @@ -3157,15 +3854,27 @@ _CHAPSEC__(1+_GENERIC__) Syntax @node AMD29K-Chars, AMD29K-Regs, AMD29K Syntax, AMD29K Syntax _CHAPSEC__(2+_GENERIC__) Special Characters + +@cindex line comment character, AMD 29K +@cindex AMD 29K line comment character @samp{;} is the line comment character. +@cindex line separator, AMD 29K +@cindex AMD 29K line separator +@cindex statement separator, AMD 29K +@cindex AMD 29K statement separator @samp{@@} can be used instead of a newline to separate statements. +@cindex identifiers, AMD 29K +@cindex AMD 29K identifiers The character @samp{?} is permitted in identifiers (but may not begin an identifier). @node AMD29K-Regs, , AMD29K-Chars, AMD29K Syntax _CHAPSEC__(2+_GENERIC__) Register Names + +@cindex AMD 29K register names +@cindex register names, AMD 29K General-purpose registers are represented by predefined symbols of the form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}} (for local registers), where @var{nnn} represents a number between @@ -3184,6 +3893,10 @@ to flag the expression as a register number): number between @code{0} and @code{255}. The range [0, 127] refers to global registers, and the range [128, 255] to local registers. +@cindex special purpose registers, AMD 29K +@cindex AMD 29K special purpose registers +@cindex protected registers, AMD 29K +@cindex AMD 29K protected registers In addition, @code{_AS__} understands the following protected special-purpose register names for the AMD 29K family: @@ -3205,13 +3918,19 @@ These unprotected special-purpose register names are also recognized: @node AMD29K Floating Point, AMD29K Directives, AMD29K Syntax, AMD29K-Dependent _CHAPSEC__(1+_GENERIC__) Floating Point -The AMD 29K family uses IEEE floating-point numbers. + +@cindex floating point, AMD 29K (@sc{ieee}) +@cindex AMD 29K floating point (@sc{ieee}) +The AMD 29K family uses @sc{ieee} floating-point numbers. @node AMD29K Directives, AMD29K Opcodes, AMD29K Floating Point, AMD29K-Dependent _CHAPSEC__(1+_GENERIC__) AMD 29K Machine Directives +@cindex machine directives, AMD 29K +@cindex AMD 29K machine directives @table @code @item .block @var{size} , @var{fill} +@cindex @code{block} directive, AMD 29K This directive emits @var{size} bytes, each of value @var{fill}. Both @var{size} and @var{fill} are absolute expressions. If the comma and @var{fill} are omitted, @var{fill} is assumed to be zero. @@ -3222,10 +3941,12 @@ In other versions of the GNU assembler, this directive is called @table @code @item .cputype +@cindex @code{cputype} directive, AMD 29K This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers. @item .file +@cindex @code{file} directive, AMD 29K This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers. @@ -3235,17 +3956,21 @@ used for the directive called @code{.app-file} in the AMD 29K support. @end quotation @item .line +@cindex @code{line} directive, AMD 29K This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers. @item .reg @var{symbol}, @var{expression} +@cindex @code{reg} directive, AMD 29K @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}. @item .sect +@cindex @code{sect} directive, AMD 29K This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers. @item .use @var{section name} +@cindex @code{use} directive, AMD 29K Establishes the section and subsection for the following code; @var{section name} may be one of @code{.text}, @code{.data}, @code{.data1}, or @code{.lit}. With one of the first three @var{section @@ -3256,6 +3981,9 @@ name} options, @samp{.use} is equivalent to the machine directive @node AMD29K Opcodes, , AMD29K Directives, AMD29K-Dependent _CHAPSEC__(1+_GENERIC__) Opcodes + +@cindex AMD 29K opcodes +@cindex opcodes for AMD 29K @code{_AS__} implements all the standard AMD 29K opcodes. No additional pseudo-instructions are needed on this family. @@ -3265,39 +3993,53 @@ User's Manual}, Advanced Micro Devices, Inc. _fi__(_A29K__) _if__(_H8__) _if__(_GENERIC__) -@node H8-300-Dependent, i960-Dependent, H8-300-Dependent, Machine Dependent +@node H8/300-Dependent, i960-Dependent, AMD29K-Dependent, Machine Dependent _fi__(_GENERIC__) _CHAPSEC__(0+_GENERIC__) H8/300 Dependent Features + +@cindex H8/300 support @menu -* H8-300 Options:: Options -* H8-300 Syntax:: Syntax -* H8-300 Floating Point:: Floating Point -* H8-300 Directives:: H8/300 Machine Directives -* H8-300 Opcodes:: Opcodes +* H8/300 Options:: Options +* H8/300 Syntax:: Syntax +* H8/300 Floating Point:: Floating Point +* H8/300 Directives:: H8/300 Machine Directives +* H8/300 Opcodes:: Opcodes @end menu -@node H8-300 Options, H8-300 Syntax, H8-300-Dependent, H8-300-Dependent +@node H8/300 Options, H8/300 Syntax, H8/300-Dependent, H8/300-Dependent _CHAPSEC__(1+_GENERIC__) Options + +@cindex H8/300 options (none) +@cindex options, H8/300 (none) @code{_AS__} has no additional command-line options for the Hitachi H8/300 family. -@node H8-300 Syntax, H8-300 Floating Point, H8-300 Options, H8-300-Dependent +@node H8/300 Syntax, H8/300 Floating Point, H8/300 Options, H8/300-Dependent _CHAPSEC__(1+_GENERIC__) Syntax @menu -* H8-300-Chars:: Special Characters -* H8-300-Regs:: Register Names -* H8-300-Addressing:: Addressing Modes +* H8/300-Chars:: Special Characters +* H8/300-Regs:: Register Names +* H8/300-Addressing:: Addressing Modes @end menu -@node H8-300-Chars, H8-300-Regs, H8-300 Syntax, H8-300 Syntax +@node H8/300-Chars, H8/300-Regs, H8/300 Syntax, H8/300 Syntax _CHAPSEC__(2+_GENERIC__) Special Characters + +@cindex line comment character, H8/300 +@cindex H8/300 line comment character @samp{;} is the line comment character. +@cindex line separator, H8/300 +@cindex statement separator, H8/300 +@cindex H8/300 line separator @samp{$} can be used instead of a newline to separate statements. Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300. -@node H8-300-Regs, H8-300-Addressing, H8-300-Chars, H8-300 Syntax +@node H8/300-Regs, H8/300-Addressing, H8/300-Chars, H8/300 Syntax _CHAPSEC__(2+_GENERIC__) Register Names + +@cindex H8/300 registers +@cindex registers, H8/300 You can use predefined symbols of the form @samp{r@var{n}h} and @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit general-purpose registers. @var{n} is a digit from @samp{0} to @@ -3313,80 +4055,202 @@ The two control registers are called @code{pc} (program counter; a register). @code{r7} is used as the stack pointer, and can also be called @code{sp}. -@node H8-300-Addressing, , H8-300-Regs, H8-300 Syntax +@node H8/300-Addressing, , H8/300-Regs, H8/300 Syntax +_CHAPSEC__(2+_GENERIC__) Addressing Modes + +@cindex addressing modes, H8/300 +@cindex H8/300 addressing modes _AS__ understands the following addressing modes for the H8/300: @table @code -@c FIXME! verify metavars, descriptions in H8/300 addressing table - @item r@var{n} Register direct @item @@r@var{n} -@c MISSING METAVAR ABOVE?? Register indirect -@item @@(@var{d}:16, r@var{n}) +@item @@(@var{d}, r@var{n}) +@itemx @@(@var{d}:16, r@var{n}) Register indirect: 16-bit displacement @var{d} from register @var{n}. -@code{_AS__} understands this notation but does not require it; if you don't -specify the displacement size, @code{_AS__} supplies it from context. +(You may specify the @samp{:16} for clarity if you wish, but it is not +required and has no effect.) @item @@r@var{n}+ -@c MISSING METAVAR ABOVE?? Register indirect with post-increment @item @@-r@var{n} -@c MISSING METAVAR ABOVE?? Register indirect with pre-decrement @item @code{@@}@var{aa} @itemx @code{@@}@var{aa}:8 @itemx @code{@@}@var{aa}:16 -Absolute address @code{aa}. @code{_AS__} understands the @samp{:8} or -@samp{:16} notation (specifying 8-bit or 16-bit addresses) but does not -require it; if you don't specify the address size, @code{_AS__} -supplies it from context. +Absolute address @code{aa}. You may specify the @samp{:8} or @samp{:16} +for clarity, if you wish; but @code{_AS__} neither requires this nor +uses it---the address size required is taken from context. @item #@var{xx} @itemx #@var{xx}:8 @itemx #@var{xx}:16 -Immediate data @var{xx}. @code{_AS__} understands the @samp{:8} or -@samp{:16} notation (specifying 8-bit or 16-bit data) but does not -require it; if you don't specify the data size, @code{_AS__} -supplies it from context. +Immediate data @var{xx}. You may specify the @samp{:8} or @samp{:16} +for clarity, if you wish; but @code{_AS__} neither requires this nor +uses it---the data size required is taken from context. @item @code{@@}@code{@@}@var{aa} @itemx @code{@@}@code{@@}@var{aa}:8 -Memory indirect. - -@c FIXME are these just examples of an H8/300 addressing language? -@c ...what about: -@c @(d:8,Rn) 8-bit reg indirect? -@c @(d:16, PC) 16-bit pc-rel? -@c @#xx:8 immediate indirect? +Memory indirect. You may specify the @samp{:8} for clarity, if you +wish; but @code{_AS__} neither requires this nor uses it. @end table -@node H8-300 Floating Point, H8-300 Directives, H8-300 Syntax, H8-300-Dependent +@node H8/300 Floating Point, H8/300 Directives, H8/300 Syntax, H8/300-Dependent _CHAPSEC__(1+_GENERIC__) Floating Point -The H8/300 family uses IEEE floating-point numbers. -@node H8-300 Directives, H8-300 Opcodes, H8-300 Floating Point, H8-300-Dependent +@cindex floating point, H8/300 (@sc{ieee}) +@cindex H8/300 floating point (@sc{ieee}) +The H8/300 family uses @sc{ieee} floating-point numbers. + +@node H8/300 Directives, H8/300 Opcodes, H8/300 Floating Point, H8/300-Dependent _CHAPSEC__(1+_GENERIC__) H8/300 Machine Directives + +@cindex H8/300 machine directives (none) +@cindex machine directives, H8/300 (none) +@cindex @code{word} directive, H8/300 +@cindex @code{int} directive, H8/300 @code{_AS__} has no machine-dependent directives for the H8/300. +However, on this platform the @samp{.int} and @samp{.word} directives +generate 16-bit numbers. -@node H8-300 Opcodes, , H8-300 Directives, H8-300-Dependent +@node H8/300 Opcodes, , H8/300 Directives, H8/300-Dependent _CHAPSEC__(1+_GENERIC__) Opcodes -@code{_AS__} implements all the standard H8/300 opcodes. No -additional pseudo-instructions are needed on this family. -For information on the H8/300 machine instruction set, see @cite{H8/300 -Series Programming Manual} (Hitachi ADE--602--025). +@cindex H8/300 opcode summary +@cindex opcode summary, H8/300 +@cindex mnemonics, H8/300 +@cindex instruction summary, H8/300 +For detailed information on the H8/300 machine instruction set, see +@cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025). + +@code{_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: +@c kluge due to lack of group outside example +@page +@smallexample +@group + Rs @r{source register} + Rd @r{destination register} + imm @r{immediate data} + x:3 @r{a bit (as a number between 0 and 7)} + d:8 @r{eight bit displacement from @code{pc}} + d:16 @r{sixteen bit displacement from @code{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 +@end group +@group +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 +@end group +@end smallexample + +@cindex size suffixes, H8/300 +@cindex H8/300 size suffixes +Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov}, +@code{sub}) are defined with variants using the suffixes @samp{.b} and +@samp{.w} to specify the size of a memory operand. @code{_AS__} +supports these suffixes, but does not require them; since one of the +operands is always a register, @code{_AS__} can deduce the correct size. + +For example, since @code{r0} refers to a 16-bit register, +@example +mov r0,@@foo +@exdent is equivalent to +mov.w r0,@@foo +@end example + +If you use the size suffixes, @code{_AS__} will issue a warning if +there's a mismatch between the suffix and the register size. _fi__(_H8__) _if__(_I960__) _if__(_GENERIC__) -@node i960-Dependent, M68K-Dependent, H8-300-Dependent, Machine Dependent +@node i960-Dependent, M68K-Dependent, H8/300-Dependent, Machine Dependent _fi__(_GENERIC__) _CHAPSEC__(0+_GENERIC__) Intel 80960 Dependent Features + +@cindex i960 support @menu * Options-i960:: i960 Command-line Options * Floating Point-i960:: Floating Point @@ -3397,10 +4261,17 @@ _CHAPSEC__(0+_GENERIC__) Intel 80960 Dependent Features @c FIXME! Add Syntax sec with discussion of bitfields here, at least so @c long as they're not turned on for other machines than 960. @node Options-i960, Floating Point-i960, i960-Dependent, i960-Dependent + _CHAPSEC__(1+_GENERIC__) i960 Command-line Options + +@cindex i960 options +@cindex options, i960 @table @code @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC +@cindex i960 architecture options +@cindex architecture options, i960 +@cindex @code{-A} options, i960 Select the 80960 architecture. Instructions or features not supported by the selected architecture cause fatal errors. @@ -3416,8 +4287,10 @@ processor type may be recorded in the object file. If it is critical that the @code{_AS__} output match a specific architecture, specify that architecture explicitly. - @item -b +@cindex @code{-b} option, i960 +@cindex branch recording, i960 +@cindex i960 branch recording 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 @@ -3437,8 +4310,10 @@ The counter following a branch records the number of times that branch was @emph{not} taken; the differenc between the two counters is the number of times the branch @emph{was} taken. -A table of all such @code{Label}s is also generated, so that the -external postprocessor @samp{gbr960} (supplied by Intel) can locate all +@cindex @code{gbr960}, i960 postprocessor +@cindex branch statistics table, i960 +A table of every such @code{Label} is also generated, so that the +external postprocessor @code{gbr960} (supplied by Intel) can locate all the counters. This table is always labelled @samp{__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 @@ -3478,6 +4353,7 @@ generate these calls automatically when you give it a @samp{-b} option. For further details, see the documentation of @samp{gbr960}. @item -norelax +@cindex @code{-norelax} option, i960 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 @samp{chkbit}) and branch @@ -3492,13 +4368,20 @@ displacement size), regardless of whether you use @samp{-norelax}. @node Floating Point-i960, Directives-i960, Options-i960, i960-Dependent _CHAPSEC__(1+_GENERIC__) Floating Point -@code{_AS__} generates IEEE floating-point numbers for the directives -@samp{.float}, @samp{.double}, @samp{extended}, and @samp{.single}. + +@cindex floating point, i960 (@sc{ieee}) +@cindex i960 floating point (@sc{ieee}) +@code{_AS__} generates @sc{ieee} floating-point numbers for the directives +@samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}. @node Directives-i960, Opcodes for i960, Floating Point-i960, i960-Dependent _CHAPSEC__(1+_GENERIC__) i960 Machine Directives +@cindex machine directives, i960 +@cindex i960 machine directives + @table @code +@cindex @code{bss} directive, i960 @item .bss @var{symbol}, @var{length}, @var{align} Reserve @var{length} bytes in the bss section for a local @var{symbol}, aligned to the power of two specified by @var{align}. @var{length} and @@ -3509,11 +4392,13 @@ an alignment. @xref{Lcomm,,@code{.lcomm}}. @table @code @item .extended @var{flonums} +@cindex @code{extended} directive, i960 @code{.extended} expects zero or more flonums, separated by commas; for -each flonum, @samp{.extended} emits an IEEE extended-format (80-bit) +each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit) floating-point number. @item .leafproc @var{call-lab}, @var{bal-lab} +@cindex @code{leafproc} directive, i960 You can use the @samp{.leafproc} directive in conjunction with the optimized @code{callj} instruction to enable faster calls of leaf procedures. If a procedure is known to call no other procedures, you @@ -3533,6 +4418,7 @@ two arguments are identical, the single argument is assumed to be the @code{bal} entry point. @item .sysproc @var{name}, @var{index} +@cindex @code{sysproc} directive, i960 The @samp{.sysproc} directive defines a name for a system procedure. After you define it using @samp{.sysproc}, you can use @var{name} to refer to the system procedure identified by @var{index} when calling @@ -3544,6 +4430,9 @@ Both arguments are required; @var{index} must be between 0 and 31 @node Opcodes for i960, , Directives-i960, i960-Dependent _CHAPSEC__(1+_GENERIC__) i960 Opcodes + +@cindex opcodes, i960 +@cindex i960 opcodes All Intel 960 machine instructions are supported; @pxref{Options-i960,,i960 Command-line Options} for a discussion of selecting the instruction subset for a particular 960 @@ -3560,6 +4449,9 @@ instructions with target displacements larger than 13 bits. @node callj-i960, Compare-and-branch-i960, Opcodes for i960, Opcodes for i960 _CHAPSEC__(2+_GENERIC__) @code{callj} + +@cindex @code{callj}, i960 pseudo-opcode +@cindex i960 @code{callj} pseudo-opcode You can write @code{callj} to have the assembler or the linker determine the most appropriate form of subroutine call: @samp{call}, @samp{bal}, or @samp{calls}. If the assembly source contains @@ -3571,6 +4463,8 @@ for the linker to resolve. @node Compare-and-branch-i960, , callj-i960, Opcodes for i960 _CHAPSEC__(2+_GENERIC__) Compare-and-Branch +@cindex i960 compare and branch instructions +@cindex compare and branch instructions, i960 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 @@ -3578,6 +4472,8 @@ 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. +@cindex compare and jump expansions, i960 +@cindex i960 compare and jump expansions Whether @code{_AS__} gives an error or expands the instruction depends on two choices you can make: whether you use the @samp{-norelax} option, and whether you use a ``Compare and Branch'' instruction or a ``Compare @@ -3649,8 +4545,10 @@ _fi__(_I960__) _if__(!_I960__) @node M68K-Dependent, Sparc-Dependent, Machine Dependent, Machine Dependent _fi__(!_I960__) -_CHAPSEC__(0+_GENERIC__) M680x0 Dependent Features _fi__(_GENERIC__) +_CHAPSEC__(0+_GENERIC__) M680x0 Dependent Features + +@cindex M680x0 support @menu * M68K-Opts:: M680x0 Options * M68K-Syntax:: Syntax @@ -3661,11 +4559,15 @@ _fi__(_GENERIC__) @node M68K-Opts, M68K-Syntax, M68K-Dependent, M68K-Dependent _CHAPSEC__(1+_GENERIC__) M680x0 Options + +@cindex options, M680x0 +@cindex M680x0 options The Motorola 680x0 version of @code{_AS__} has two machine dependent options. One shortens undefined references from 32 to 16 bits, while the other is used to tell @code{_AS__} what kind of machine it is assembling for. +@cindex @code{-l} option, M680x0 You can use the @kbd{-l} option to shorten the size of references to undefined symbols. If the @kbd{-l} option is not given, references to undefined symbols will be a full long (32 bits) wide. (Since @code{_AS__} @@ -3677,6 +4579,9 @@ 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. +@cindex @code{-m68000} and related options, M680x0 +@cindex architecture options, M680x0 +@cindex M680x0 architecture options The 680x0 version of @code{_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 @@ -3688,6 +4593,10 @@ target. @node M68K-Syntax, M68K-Float, M68K-Opts, M68K-Dependent _CHAPSEC__(1+_GENERIC__) Syntax +@cindex M680x0 syntax +@cindex syntax, M680x0 +@cindex M680x0 size modifiers +@cindex size modifiers, M680x0 The 680x0 version of @code{_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 @samp{movl} rather than @@ -3703,6 +4612,8 @@ registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the Program Counter (@samp{pc}), or the zero-address relative to the program counter (@samp{zpc}). +@cindex M680x0 addressing modes +@cindex addressing modes, M680x0 The following addressing modes are understood: @table @dfn @item Immediate @@ -3756,6 +4667,10 @@ by @samp{:b}, @samp{:w}, or @samp{:l}. @node M68K-Float, M68K-Directives, M68K-Syntax, M68K-Dependent _CHAPSEC__(1+_GENERIC__) Floating Point + +@cindex floating point, M680x0 +@cindex M680x0 floating point +@c FIXME is this "not too well tested" crud STILL true? The floating point code is not too well tested, and may have subtle bugs in it. @@ -3763,10 +4678,14 @@ Packed decimal (P) format floating literals are not supported. Feel free to add the code! The floating point formats generated by directives are these. + @table @code @item .float +@cindex @code{float} directive, M680x0 @code{Single} precision floating point constants. + @item .double +@cindex @code{double} directive, M680x0 @code{Double} precision floating point constants. @end table @@ -3778,22 +4697,37 @@ hard, but it has not yet seemed necessary. @node M68K-Directives, M68K-opcodes, M68K-Float, M68K-Dependent _CHAPSEC__(1+_GENERIC__) 680x0 Machine Directives + +@cindex M680x0 directives +@cindex directives, M680x0 In order to be compatible with the Sun assembler the 680x0 assembler understands the following directives. + @table @code @item .data1 +@cindex @code{data1} directive, M680x0 This directive is identical to a @code{.data 1} directive. + @item .data2 +@cindex @code{data2} directive, M680x0 This directive is identical to a @code{.data 2} directive. + @item .even +@cindex @code{even} directive, M680x0 This directive is identical to a @code{.align 1} directive. @c Is this true? does it work??? + @item .skip +@cindex @code{skip} directive, M680x0 This directive is identical to a @code{.space} directive. @end table @node M68K-opcodes, , M68K-Directives, M68K-Dependent _CHAPSEC__(1+_GENERIC__) Opcodes + +@cindex M680x0 opcodes +@cindex opcodes, M680x0 +@cindex instruction set, M680x0 @c pesch@cygnus.com: I don't see any point in the following @c paragraph. Bugs are bugs; how does saying this @c help anyone? @@ -3811,6 +4745,10 @@ instructions. @node M68K-Branch, M68K-Chars, M68K-opcodes, M68K-opcodes _CHAPSEC__(2+_GENERIC__) Branch Improvement +@cindex pseudo-opcodes, M680x0 +@cindex M680x0 pseudo-opcodes +@cindex branch improvement, M680x0 +@cindex M680x0 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 @samp{j} for @@ -3905,6 +4843,13 @@ when it encounters @samp{fj@var{XX} foo}. @node M68K-Chars, , M68K-Branch, M68K-opcodes _CHAPSEC__(2+_GENERIC__) Special Characters + +@cindex special characters, M680x0 +@cindex M680x0 immediate character +@cindex immediate character, M680x0 +@cindex M680x0 line comment character +@cindex line comment character, M680x0 +@cindex comments, M680x0 The immediate character is @samp{#} for Sun compatibility. The line-comment character is @samp{|}. If a @samp{#} appears at the beginning of a line, it is treated as a comment unless it looks like @@ -3927,7 +4872,7 @@ I don't know anything about the 32x32 syntax assembled by one) and the possible syntaxes should write this section. @subsection Floating Point -The 32x32 uses IEEE floating point numbers, but @code{_AS__} will only +The 32x32 uses @sc{ieee} floating point numbers, but @code{_AS__} will only create single or double precision values. I don't know if the 32x32 understands extended precision numbers. @@ -3969,6 +4914,8 @@ _if__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__) _fi__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__) _fi__(_GENERIC__) _CHAPSEC__(0+_GENERIC__) SPARC Dependent Features + +@cindex SPARC support @menu * Sparc-Opts:: Options * Sparc-Float:: Floating Point @@ -3977,6 +4924,9 @@ _CHAPSEC__(0+_GENERIC__) SPARC Dependent Features @node Sparc-Opts, Sparc-Float, Sparc-Dependent, Sparc-Dependent _CHAPSEC__(1+_GENERIC__) Options + +@cindex options for SPARC (none) +@cindex SPARC options (none) The Sparc has no machine dependent options. @ignore @@ -3988,47 +4938,55 @@ will have to write this section. @node Sparc-Float, Sparc-Directives, Sparc-Opts, Sparc-Dependent _CHAPSEC__(1+_GENERIC__) Floating Point + +@cindex floating point, SPARC (@sc{ieee}) +@cindex SPARC floating point (@sc{ieee}) The Sparc uses @sc{ieee} floating-point numbers. @node Sparc-Directives, , Sparc-Float, Sparc-Dependent _CHAPSEC__(1+_GENERIC__) Sparc Machine Directives + +@cindex SPARC machine directives +@cindex machine directives, SPARC The Sparc version of @code{_AS__} supports the following additional machine directives: @table @code @item .common +@cindex @code{common} directive, SPARC This must be followed by a symbol name, a positive number, and @code{"bss"}. This behaves somewhat like @code{.comm}, but the syntax is different. -@item .global -This is functionally identical to @code{.globl}. -@c FIXME: is this still really SPARC specific? (vintage/devo) - @item .half +@cindex @code{half} directive, SPARC This is functionally identical to @code{.short}. @item .proc +@cindex @code{proc} directive, SPARC This directive is ignored. Any text following it on the same line is also ignored. @item .reserve +@cindex @code{reserve} directive, SPARC This must be followed by a symbol name, a positive number, and @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the syntax is different. @item .seg +@cindex @code{seg} directive, SPARC This must be followed by @code{"text"}, @code{"data"}, or @code{"data1"}. It behaves like @code{.text}, @code{.data}, or @code{.data 1}. @item .skip +@cindex @code{skip} directive, SPARC This is functionally identical to the @code{.space} directive. @item .word +@cindex @code{word} directive, SPARC On the Sparc, the .word directive produces 32 bit values, instead of the 16 bit values it produces on many other machines. - @end table _fi__(_SPARC__) @@ -4039,6 +4997,8 @@ _if__(_GENERIC__) _fi__(_GENERIC__) _CHAPSEC__(0+_GENERIC__) 80386 Dependent Features +@cindex i386 support +@cindex i80306 support @menu * i386-Options:: Options * i386-Syntax:: AT&T Syntax versus Intel Syntax @@ -4053,17 +5013,31 @@ _CHAPSEC__(0+_GENERIC__) 80386 Dependent Features @node i386-Options, i386-Syntax, i386-Dependent, i386-Dependent _CHAPSEC__(1+_GENERIC__) Options + +@cindex options for i386 (none) +@cindex i386 options (none) The 80386 has no machine dependent options. @node i386-Syntax, i386-Opcodes, i386-Options, i386-Dependent _CHAPSEC__(1+_GENERIC__) AT&T Syntax versus Intel Syntax + +@cindex i386 syntax compatibility +@cindex syntax compatibility, i386 In order to maintain compatibility with the output of @code{_GCC__}, @code{_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: + @itemize @bullet @item +@cindex immediate operands, i386 +@cindex i386 immediate operands +@cindex register operands, i386 +@cindex i386 register operands +@cindex jump/call operands, i386 +@cindex i386 jump/call operands +@cindex operand delimiters, i386 AT&T immediate operands are preceded by @samp{$}; Intel immediate operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}). AT&T register operands are preceded by @samp{%}; Intel register operands @@ -4071,12 +5045,17 @@ are undelimited. AT&T absolute (as opposed to PC relative) jump/call operands are prefixed by @samp{*}; they are undelimited in Intel syntax. @item +@cindex i386 source, destination operands +@cindex source, destination operands; i386 AT&T and Intel syntax use the opposite order for source and destination operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The @samp{source, dest} convention is maintained for compatibility with previous Unix assemblers. @item +@cindex opcode suffixes, i386 +@cindex sizes operands, i386 +@cindex i386 size suffixes In AT&T syntax the size of memory operands is determined from the last character of the opcode name. Opcode suffixes of @samp{b}, @samp{w}, and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit) @@ -4086,6 +5065,8 @@ operands (@emph{not} the opcodes themselves) with @samp{byte ptr}, ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax. @item +@cindex return instructions, i386 +@cindex i386 jump, call, return Immediate form long jumps and calls are @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the Intel syntax is @@ -4095,12 +5076,17 @@ is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is @samp{ret far @var{stack-adjust}}. @item +@cindex sections, i386 +@cindex i386 sections The AT&T assembler does not provide support for multiple section programs. Unix style systems expect all programs to be single sections. @end itemize @node i386-Opcodes, i386-Regs, i386-Syntax, i386-Dependent _CHAPSEC__(1+_GENERIC__) Opcode Naming + +@cindex i386 opcode naming +@cindex opcode naming, i386 Opcode names are suffixed with one character modifiers which specify the size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify byte, word, and long operands. If no suffix is specified by an @@ -4126,28 +5112,42 @@ the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word), and @samp{wl} (from word to long). -The Intel syntax conversion instructions +@cindex conversion instructions, i386 +@cindex i386 conversion instructions +The Intel-syntax conversion instructions + @itemize @bullet @item @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax}, + @item @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax}, + @item @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax}, + @item @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax}, @end itemize + +@noindent are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in AT&T naming. @code{_AS__} accepts either naming for these instructions. +@cindex jump instructions, i386 +@cindex call instructions, i386 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel convention. @node i386-Regs, i386-prefixes, i386-Opcodes, i386-Dependent _CHAPSEC__(1+_GENERIC__) Register Naming + +@cindex i386 registers +@cindex registers, i386 Register operands are always prefixes with @samp{%}. The 80386 registers consist of + @itemize @bullet @item the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx}, @@ -4188,6 +5188,10 @@ the 8 floating point register stack @samp{%st} or equivalently @node i386-prefixes, i386-Memory, i386-Regs, i386-Dependent _CHAPSEC__(1+_GENERIC__) Opcode Prefixes + +@cindex i386 opcode prefixes +@cindex opcode prefixes, i386 +@cindex prefixes, i386 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 @@ -4202,43 +5206,59 @@ example, the @samp{scas} (scan string) instruction is repeated with: @end smallexample Here is a list of opcode prefixes: + @itemize @bullet @item +@cindex section override prefixes, i386 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es}, @samp{fs}, @samp{gs}. These are automatically added by specifying using the @var{section}:@var{memory-operand} form for memory references. @item +@cindex size prefixes, i386 Operand/Address size prefixes @samp{data16} and @samp{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). @item +@cindex bus lock prefixes, i386 +@cindex inhibiting interrupts, i386 The bus lock prefix @samp{lock} inhibits interrupts during execution of the instruction it precedes. (This is only valid with certain instructions; see a 80386 manual for details). @item +@cindex coprocessor wait, i386 The wait for coprocessor prefix @samp{wait} waits for the coprocessor to complete the current instruction. This should never be needed for the 80386/80387 combination. @item +@cindex repeat prefixes, i386 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added to string instructions to make them repeat @samp{%ecx} times. @end itemize @node i386-Memory, i386-jumps, i386-prefixes, i386-Dependent _CHAPSEC__(1+_GENERIC__) Memory References + +@cindex i386 memory references +@cindex memory references, i386 An Intel syntax indirect memory reference of the form + @smallexample @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}] @end smallexample + +@noindent is translated into the AT&T syntax + @smallexample @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale}) @end smallexample + +@noindent where @var{base} and @var{index} are the optional 32-bit base and index registers, @var{disp} is the optional displacement, and @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index} @@ -4254,8 +5274,8 @@ 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: -@table @asis +@table @asis @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]} @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is missing, and the default section is used (@samp{%ss} for addressing with @@ -4274,7 +5294,6 @@ Note that @var{base} and @var{index} are both missing, but there is only @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo} This selects the contents of the variable @samp{foo} with section register @var{section} being @samp{%gs}. - @end table Absolute (as opposed to PC relative) call and jump operands must be @@ -4287,6 +5306,9 @@ respectively). @node i386-jumps, i386-Float, i386-Memory, i386-Dependent _CHAPSEC__(1+_GENERIC__) Handling of Jump Instructions + +@cindex jump optimization, i386 +@cindex i386 jump optimization 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 @@ -4310,6 +5332,9 @@ cx_nonzero: @node i386-Float, i386-Notes, i386-jumps, i386-Dependent _CHAPSEC__(1+_GENERIC__) Floating Point + +@cindex i386 floating point +@cindex floating point, i386 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), @@ -4320,6 +5345,10 @@ types. Constructors build these data types into memory. @itemize @bullet @item +@cindex @code{float} directive, i386 +@cindex @code{single} directive, i386 +@cindex @code{double} directive, i386 +@cindex @code{tfloat} directive, i386 Floating point constructors are @samp{.float} or @samp{.single}, @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats. These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}. @@ -4328,6 +5357,10 @@ this format via the @samp{fldt} (load temporary real to stack top) and @samp{fstpt} (store temporary real and pop stack) instructions. @item +@cindex @code{word} directive, i386 +@cindex @code{long} directive, i386 +@cindex @code{int} directive, i386 +@cindex @code{quad} directive, i386 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q} @@ -4339,6 +5372,8 @@ only present in the @samp{fildq} (load quad integer to stack top) and Register to register operations do not require opcode suffixes, so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}. +@cindex i386 @code{fwait} instruction +@cindex @code{fwait instruction}, i386 Since the 80387 automatically synchronizes with the 80386 @samp{fwait} instructions are almost never needed (this is not the case for the 80286/80287 and 8086/8087 combinations). Therefore, @code{_AS__} suppresses @@ -4350,6 +5385,10 @@ instructions are made equivalent to @samp{f@dots{}} instructions. If @node i386-Notes, , i386-Float, i386-Dependent _CHAPSEC__(1+_GENERIC__) Notes + +@cindex i386 @code{mul}, @code{imul} instructions +@cindex @code{mul} instruction, i386 +@cindex @code{imul} instruction, i386 There is some trickery concerning the @samp{mul} and @samp{imul} instructions that deserves mention. The 16-, 32-, and 64-bit expanding multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5 @@ -5283,8 +6322,12 @@ usually only needed by the machine-independent part of @end table _fi__(0) -@node Copying, , Machine Dependent, Top +@node Copying, Index, _MACH_DEP__, Top @unnumbered GNU GENERAL PUBLIC LICENSE + +@cindex license +@cindex GPL +@cindex copying @code{_AS__} @center Version 2, June 1991 @display @@ -5389,7 +6432,7 @@ 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: -@alphaenumerate +@enumerate a @item You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. @@ -5411,7 +6454,7 @@ 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.) -@end alphaenumerate +@end enumerate These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, @@ -5438,7 +6481,7 @@ 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: -@alphaenumerate +@enumerate a @item Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections @@ -5458,7 +6501,7 @@ 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.) -@end alphaenumerate +@end enumerate The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source @@ -5677,6 +6720,11 @@ 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. +@node Index, , Copying, Top +@unnumbered Index + +@printindex cp + @summarycontents @contents @bye |