diff options
Diffstat (limited to 'gnu/usr.bin/as/doc/as.texinfo')
| -rw-r--r-- | gnu/usr.bin/as/doc/as.texinfo | 6730 |
1 files changed, 0 insertions, 6730 deletions
diff --git a/gnu/usr.bin/as/doc/as.texinfo b/gnu/usr.bin/as/doc/as.texinfo deleted file mode 100644 index c9e0f575fa33..000000000000 --- a/gnu/usr.bin/as/doc/as.texinfo +++ /dev/null @@ -1,6730 +0,0 @@ -_dnl__ -*-Texinfo-*- -_dnl__ Copyright (c) 1991 1992 Free Software Foundation, Inc. -_dnl__ $Id: as.texinfo,v 1.1 1993/10/02 21:00:15 pk Exp $ -\input texinfo @c -*-Texinfo-*- -@c Copyright (c) 1991 1992 Free Software Foundation, Inc. -@c %**start of header -@setfilename _AS__.info -_if__(_GENERIC__) -@settitle Using _AS__ -_fi__(_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 -of m4 macros called "pretex.m4". - -THIS IS THE FULL SOURCE. The full source needs to be run through m4 -before either tex- or info- formatting: for example, - m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo -will produce (assuming your path finds either GNU or SysV m4; Berkeley -won't do) a file, configured for the M680x0 version of GAS, suitable for -formatting. See the text in "pretex.m4" for a fuller explanation (and -the macro definitions). - -_fi__(0) -@c -@ifinfo -This file documents the GNU Assembler "_AS__". - -Copyright (C) 1991 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through Tex and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included exactly as -in the original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this -one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' may be -included in a translation approved by the Free Software Foundation -instead of in the original English. -@end ifinfo - -@titlepage -@title Using _AS__ -@subtitle The GNU Assembler -_if__(!_GENERIC__) -@subtitle for the _HOST__ family -_fi__(!_GENERIC__) -@sp 1 -@subtitle January 1992 -@sp 1 -@sp 13 -The Free Software Foundation Inc. thanks The Nice Computer -Company of Australia for loaning Dean Elsner to write the -first (Vax) version of @code{as} for Project GNU. -The proprietors, management and staff of TNCCA thank FSF for -distracting the boss while they got some work -done. -@sp 3 -@author Dean Elsner, Jay Fenlason & friends -@c edited by: pesch@cygnus.com -@page -@tex -\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision: 1.1 $} % For use in headers, footers too -{\parskip=0pt -\hfill \manvers\par -\hfill \TeX{}info \texinfoversion\par -} -%"boxit" macro for figures: -%Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3) -\gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt - \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil -#2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline -\gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box -@end tex - -Edited by Roland Pesch for Cygnus Support. - -@vskip 0pt plus 1filll -Copyright @copyright{} 1991 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included exactly as -in the original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this -one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' may be -included in a translation approved by the Free Software Foundation -instead of in the original English. -@end titlepage -@page -@node Top, Overview, (dir), (dir) -@ifinfo -This file is a user guide to the GNU assembler @code{_AS__}. -_if__(!_GENERIC__) -This version of the file describes @code{_AS__} configured to generate -code for _HOST__ architectures. -_fi__(!_GENERIC__) -@end ifinfo -@menu -* Overview:: Overview -* Invoking:: Command-Line Options -* Syntax:: Syntax -* Sections:: Sections and Relocation -* Symbols:: Symbols -* Expressions:: Expressions -* Pseudo Ops:: Assembler Directives -* _MACH_DEP__:: Machine Dependent Features -* Copying:: GNU GENERAL PUBLIC LICENSE -* Index:: Index -@end menu - -@node Overview, Invoking, Top, Top -@chapter Overview -@iftex -This manual is a user guide to the GNU assembler @code{_AS__}. -_if__(!_GENERIC__) -This version of the manual describes @code{_AS__} configured to generate -code for _HOST__ architectures. -_fi__(!_GENERIC__) -@end iftex - -@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__ [ -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 -_fi__(_A29K__) -_if__(_H8__) -@c h8/300 has no machine-dependent assembler options -_fi__(_H8__) -_if__(_I960__) -@c see md_parse_option in i960.c - [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ] - [ -b ] [ -norelax ] -_fi__(_I960__) -_if__(_M680X0__) - [ -l ] [ -mc68000 | -mc68010 | -mc68020 ] -_fi__(_M680X0__) - [ -- | @var{files} @dots{} ] -@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 -other assemblers; it has no effect on @code{_AS__}. - -@item -f -``fast''---skip preprocessing (assume source is compiler output) - -@item -I @var{path} -Add @var{path} to the search list for @code{.include} directives - -@item -k -_if__((!_GENERIC__) && !_DIFFTABKLUG__) -This option is accepted but has no effect on the _HOST__ family. -_fi__((!_GENERIC__) && !_DIFFTABKLUG__) -_if__(_GENERIC__ || _DIFFTABKLUG__) -Issue warnings when difference tables altered for long displacements. -_fi__(_GENERIC__ || _DIFFTABKLUG__) - -@item -L -Keep (in symbol table) local symbols, starting with @samp{L} - -@item -o @var{objfile} -Name the object-file output from @code{_AS__} - -@item -R -Fold data section into text section - -@item -v -Announce @code{as} version - -@item -W -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 -_if__(_GENERIC__) -(When configured for Intel 960). -_fi__(_GENERIC__) -Do not alter compare-and-branch instructions for long displacements; -error if necessary. -_fi__(_I960__) - -_if__(_M680X0__) -@item -l -_if__(_GENERIC__) -(When configured for Motorola 68000). -_fi__(_GENERIC__) -Shorten references to undefined symbols, to one word instead of two - -@item -mc68000 | -mc68010 | -mc68020 -_if__(_GENERIC__) -(When configured for Motorola 68000). -_fi__(_GENERIC__) -Specify what processor in the 68000 family is the target (default 68020) -_fi__(_M680X0__) - -@item -- | @var{files} @dots{} -Standard input, or source files to assemble -@end table - -@menu -* Manual:: Structure of this Manual -* GNU Assembler:: _AS__, the GNU Assembler -* Object Formats:: Object File Formats -* Command Line:: Command Line -* Input Files:: Input Files -* Object:: Output (Object) File -* Errors:: Error and Warning Messages -@end menu - -@node Manual, GNU Assembler, Overview, Overview -@section Structure of this Manual - -@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__}. - -_if__(!_GENERIC__) -We also cover special features in the _HOST__ -configuration of @code{_AS__}, including assembler directives. -_fi__(!_GENERIC__) -_if__(_GENERIC__) -This manual also describes some of the machine-dependent features of -various flavors of the assembler. -_fi__(_GENERIC__) -_if__(_INTERNALS__) -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. -_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 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); -once this assumption is granted examples and definitions need less -qualification. - -@code{_AS__} is part of a team of programs that turn a high-level -human-readable series of instructions into a low-level -computer-readable series of instructions. Different versions of -@code{_AS__} are used for different kinds of computer. -@end ignore - -@c There used to be a section "Terminology" here, which defined -@c "contents", "byte", "word", and "long". Defining "word" to any -@c particular size is confusing when the .word directive may generate 16 -@c bits on one machine and 32 bits on another; in general, for the user -@c version of this manual, none of these terms seem essential to define. -@c They were used very little even in the former draft of the manual; -@c this draft makes an effort to avoid them (except in names of -@c directives). - -@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 @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 -should find a fairly similar environment when you use it on another -architecture. Each version has much in common with the others, -including object file formats, most assembler directives (often called -@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__) -_if__(_GENERIC__||_M680X0__) -This doesn't mean @code{_AS__} always uses the same syntax as another -assembler for the same architecture; for example, we know of several -incompatible versions of 680x0 assembly language syntax. -_fi__(_GENERIC__||_M680X0__) - -Unlike older assemblers, @code{_AS__} is designed to assemble a source -program in one pass of the source file. This has a subtle impact on the -@kbd{.org} directive (@pxref{Org,,@code{.org}}). - -@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 -are typically different in different file formats. @xref{Symbol -Attributes,,Symbol Attributes}. -_if__(!_GENERIC__) -_if__(!(_I960__||_A29K__)) -_if__(_AOUT__ && (!_COFF__) && (!_ELF__)) -On the _HOST__, @code{_AS__} is configured to produce @code{a.out} format object -files.@refill -_fi__(_AOUT__ && (!_COFF__) && (!_ELF__)) -_if__((!_AOUT__) && _COFF__ && (!_ELF__)) -On the _HOST__, @code{_AS__} is configured to produce COFF format object -files.@refill -_fi__((!_AOUT__) && _COFF__ && (!_ELF__)) -_fi__(!(_I960__||_A29K__)) -_if__(_A29K__) -On the _HOST__, @code{_AS__} can be configured to produce either -@code{a.out} or COFF format object files. -_fi__(_A29K__) -_if__(_I960__) -On the _HOST__, @code{_AS__} can be configured to produce either @code{b.out} or COFF -format object files. -_fi__(_I960__) -_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 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 -option is a @samp{-} followed by one or more letters; the case of -the letter is important. All options are optional. - -Some options expect exactly one file name to follow them. The file -name may either immediately follow the option's letter (compatible -with older assemblers) or it may be the next command argument (GNU -standard). These two command lines are equivalent: - -@smallexample -_AS__ -o my-object-file.o mumble.s -_AS__ -omy-object-file.o mumble.s -@end smallexample - -@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 -doesn't change the meaning of the source. - -@c I added "con" prefix to "catenation" just to prove I can overcome my -@c APL training... pesch@cygnus.com -The source program is a concatenation of the text in all the files, in the -order specified. - -Each time you run @code{_AS__} it assembles exactly one source -program. The source program is made up of one or more files. -(The standard input is also a file.) - -You give @code{_AS__} a command line that has zero or more input file -names. The input files are read (from left file name to right). A -command line argument (in any position) that has no special meaning -is taken to be an input file name. - -If you give @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. - -Use @samp{--} if you need to explicitly name the standard input file -in your command line. - -If the source is empty, @code{_AS__} will produce a small, empty object -file. - -@subheading Filenames and Line-numbers - -@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. @xref{Errors, ,Error and Warning Messages}. - -@dfn{Physical files} are those files named in the command line given -to @code{_AS__}. - -@dfn{Logical files} are simply names declared explicitly by assembler -directives; they bear no relation to physical files. Logical file names -help error messages reflect the original source file, when @code{_AS__} -source is itself synthesized from other files. -@xref{App-File,,@code{.app-file}}. - -@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 -give it another name by using the @code{-o} option. Conventionally, -object file names end with @file{.o}. The default name of -@file{a.out} is used for historical reasons: older assemblers were -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. - -@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 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 -given -_if__(!_A29K__) -(@pxref{Line,,@code{.line}}) -_fi__(!_A29K__) -_if__(_A29K__) -(@pxref{Ln,,@code{.ln}}) -_fi__(_A29K__) -then it is used to calculate the number printed, -otherwise the actual line in the current source file is printed. The -message text is intended to be self explanatory (in the grand Unix -tradition). @refill - -@cindex format of error messages -Error messages have the format -@smallexample -file_name:@b{NNN}:FATAL:Error Message Text -@end smallexample -The file name and line number are derived as for warning -messages. The actual message text may be rather less explanatory -because many of them aren't supposed to happen. - -@node Invoking, Syntax, Overview, Top -@chapter Command-Line Options - -@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__. -_fi__(!_GENERIC__) -_if__(_GENERIC__) -to particular machine architectures. -_fi__(_GENERIC__) - -@section Enable Listings: @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__}. - -@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. @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 - -@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 -many times as necessary to include a variety of paths. The current -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. - -@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, -where it can be used to warn when the assembler alters the machine code -generated for @samp{.word} directives in difference tables. The _HOST__ -family does not have the addressing limitations that sometimes lead to this -alteration on other platforms. -_fi__((!_GENERIC__) && (!_DIFFTABKLUG__)) - -_if__(_GENERIC__ || _DIFFTABKLUG__ ) -@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__ ) - -@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 -compilers) that compose assembler programs, not for your notice. -Normally both @code{_AS__} and @code{_LD__} discard such labels, so you don't -normally debug with them. - -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}. - -@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. - -Whatever the object file is called, @code{_AS__} will overwrite any -existing file of the same name. - -@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 -section parts are relocated differently. The data section part of -your object file is zero bytes long because all it bytes are -appended to the text section. (@xref{Sections,,Sections and Relocation}.) - -When you specify @code{-R} it would be possible to generate shorter -address displacements (because we don't have to cross between text and -data section). We refrain from doing this simply for compatibility with -older versions of @code{_AS__}. In future, @code{-R} may work this way. - -_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. - -@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 -made. All such warnings are directed to the standard error file. -If you use this option, no warnings are issued. This option only -affects the warning messages: it does not change any particular of how -@code{_AS__} assembles your file. Errors, which stop the assembly, are -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 -_if__(!_VAX__) -assembler. @refill -_fi__(!_VAX__) -_if__(_VAX__) -assembler, except that @code{_AS__} does not assemble Vax bit-fields. -_fi__(_VAX__) - -@menu -* Pre-processing:: Pre-processing -* Whitespace:: Whitespace -* Comments:: Comments -* Symbol Intro:: Symbols -* Statements:: Statements -* Constants:: Constants -@end menu - -@node Pre-processing, Whitespace, Syntax, Syntax -@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 - -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 -that says @code{#APP} before the text that should be pre-processed, and -putting a line that says @code{#NO_APP} after them. This feature is -mainly intend to support @code{asm} statements in compilers whose output -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 -(@pxref{Characters,,Character Constants}), any whitespace means the same -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. - -Anything from @samp{/*} through the next @samp{*/} is a comment. -This means you may not nest these comments. - -@smallexample -/* - The only way to include a newline ('\n') in a comment - is to use this sort of comment. -*/ - -/* This sort of comment does not nest. */ -@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__) -@samp{#} on the Vax; -_fi__(_VAX__) -_if__(_I960__) -@samp{#} on the i960; -_fi__(_I960__) -_if__(_M680X0__) -@samp{|} on the 680x0; -_fi__(_M680X0__) -_if__(_A29K__) -@samp{;} for the AMD 29K family; -_fi__(_A29K__) -_if__(_H8__) -@samp{;} for the _HOST__ family; -_fi__(_H8__) -@pxref{_MACH_DEP__}. @refill -@c FIXME: fill in SPARC line comment char - -_if__(_GENERIC__) -On some machines there are two different line comment characters. One -will only begin a comment if it is the first non-whitespace character on -a line, while the other will always begin a comment. -_fi__(_GENERIC__) - -@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 -(@xref{Strings}.) is allowed: if present it is a new logical file -name. The rest of the line, if any, should be whitespace. - -If the first non-whitespace characters on the line are not numeric, -the line is ignored. (Just like a comment.) -@smallexample - # This is an ordinary comment. -# 42-6 "new_file_name" # New logical file name - # This is logical line # 36. -@end smallexample -This feature is deprecated, and may disappear from future versions -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__) -the three characters @samp{_.$} -_fi__(!_H8__) -_if__(_H8__) -the two characters @samp{_.} -_if__(_GENERIC__) -On most machines, you can also use @code{$} in symbol names; exceptions -are noted in @ref{_MACH_DEP__}. -_fi__(_GENERIC__) -_fi__(_H8__) -No symbol may begin with a digit. Case is significant. -There is no length limit: all characters are significant. Symbols are -delimited by characters not in that set, or by the beginning of a file -(since the source program must end with a newline, the end of a file is -not a possible symbol delimiter). @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 -semicolon (@samp{;}). The newline or semicolon is considered part of -the preceding statement. Newlines and semicolons within character -constants are an exception: they don't end statements. -_fi__(!(_A29K__||_H8__)) -_if__(_A29K__) -A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at'' -sign (@samp{@@}). The newline or at sign is considered part of the -preceding statement. Newlines and at signs within character constants -are an exception: they don't end statements. -_fi__(_A29K__) -_if__(_H8__) -A @dfn{statement} ends at a newline character (@samp{\n}) or a dollar -sign (@samp{$}). The newline or dollar sign is considered part of the -preceding statement. Newlines and dollar signs within character constants -are an exception: they don't end statements. -_fi__(_H8__) -_fi__(!_GENERIC__) -_if__(_GENERIC__) -A @dfn{statement} ends at a newline character (@samp{\n}) or line -separator character. (The line separator is usually @samp{;}, unless -this conflicts with the comment character; @pxref{_MACH_DEP__}.) The -newline or separator character is considered part of the preceding -statement. Newlines and separators within character constants are an -exception: they don't end statements. -_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 -characters are ignored. You can even put backslashed newlines in -the middle of symbol names without changing the meaning of your -source program. - -An empty statement is allowed, and may include whitespace. It is ignored. - -@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. -A statement begins with zero or more labels, optionally followed by a -key symbol which determines what kind of statement it is. The key -symbol determines the syntax of the rest of the statement. If the -symbol begins with a dot @samp{.} then the statement is an assembler -directive: typically valid for any computer. If the symbol begins with -a letter the statement is an assembly language @dfn{instruction}: it -will assemble into a machine language instruction. -_if__(_GENERIC__) -Different versions of @code{_AS__} for different computers will -recognize different instructions. In fact, the same symbol may -represent a different instruction in a different computer's assembly -language.@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}. - -@smallexample -label: .directive followed by something -another_label: # This is an empty statement. - instruction operand_1, operand_2, @dots{} -@end smallexample - -@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 -.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value. -.ascii "Ring the bell\7" # A string constant. -.octa 0x123456789abcdef0123456789ABCDEF0 # A bignum. -.float 0f-314159265358979323846264338327\ -95028841971.693993751E-40 # - pi, a flonum. -@end smallexample - -@menu -* Characters:: Character Constants -* Numbers:: Number Constants -@end menu - -@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 -@emph{literals}) are potentially many bytes and their values may not be -used in arithmetic expressions. - -@menu -* Strings:: Strings -* Chars:: Characters -@end menu - -@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 -a backslash @samp{\} character. For example @samp{\\} represents -one backslash: the first @code{\} is an escape which tells -@code{_AS__} to interpret the second character literally as a backslash -(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 -you used an escape sequence you clearly didn't want the literal -interpretation of the following character. However @code{_AS__} has no -other interpretation, so @code{_AS__} knows it is giving you the wrong -code and warns you of the fact. -@end table - -Which characters are escapable, and what those escapes represent, -varies widely among assemblers. The current set is what we think -the BSD 4.2 assembler recognizes, and is a subset of what most C -compilers recognize. If you are in doubt, don't use an escape -sequence. - -@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 -must write @kbd{'\\} where the first @code{\} escapes the second -@code{\}. As you can see, the quote is an acute accent, not a -grave accent. A newline -_if__(!_GENERIC__) -_if__(!(_A29K__||_H8__)) -(or semicolon @samp{;}) -_fi__(!(_A29K__||_H8__)) -_if__(_A29K__) -(or at sign @samp{@@}) -_fi__(_A29K__) -_if__(_H8__) -(or dollar sign @samp{$}) -_fi__(_H8__) -_fi__(!_GENERIC__) -immediately following an acute accent is taken as a literal character -and does not count as the end of a statement. The value of a character -constant in a numeric expression is the machine's byte-wide code for -that character. @code{_AS__} assumes your character code is ASCII: -@kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill - -@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 -integers, but they are stored in more than 32 bits. @emph{Flonums} -are floating point numbers, described below. - -@menu -* Integers:: Integers -* Bignums:: Bignums -* Flonums:: Flonums -_if__(_I960__&&!_GENERIC__) -* Bit Fields:: Bit Fields -_fi__(_I960__&&!_GENERIC__) -@end menu - -@node Integers, Bignums, Numbers, Numbers -@subsubsection Integers -@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}. - -Integers have the usual values. To denote a negative integer, use -the prefix operator @samp{-} discussed under expressions -(@pxref{Prefix Ops,,Prefix Operators}). - -@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 -integers are permitted while bignums are not. - -_if__(_I960__&&!_GENERIC__) -@node Flonums, Bit Fields, Bignums, Numbers -_fi__(_I960__&&!_GENERIC__) -_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 -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 -portion of @code{_AS__} specialized to that computer. - -A flonum is written by writing (in order) -@itemize @bullet -@item -The digit @samp{0}. -@item -A letter, to tell @code{_AS__} the rest of the number is a flonum. -_if__(_GENERIC__) -@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 -will work here, but that might be changed. Vax BSD 4.2 assembler seems -to allow any of @samp{defghDEFGH}.) -@end ignore -_fi__(_GENERIC__) -_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). -_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). -_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{fractional part}: @samp{.} followed by zero -or more decimal digits. -@item -An optional exponent, consisting of: -@itemize @bullet -@item -An @samp{E} or @samp{e}. -@c I can't find a config where "EXP_CHARS" is other than 'eE', but in -@c principle this can perfectly well be different on different targets. -@item -Optional sign: either @samp{+} or @samp{-}. -@item -One or more decimal digits. -@end itemize -@end itemize - -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 -independently of any floating point hardware in the computer running -@code{_AS__}. - -_if__(_I960__&&!_GENERIC__) -@c Bit fields are written as a general facility but are also controlled -@c by a conditional-compilation flag---which is as of now (21mar91) -@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 -@var{mask}:@var{value} -@end example -@noindent -the first will act as a mask; @code{_AS__} will bitwise-and it with the -second value. - -The resulting number is then packed -_if__(_GENERIC__) -@c this conditional paren in case bit fields turned on elsewhere than 960 -(in host-dependent byte order) -_fi__(_GENERIC__) -into a field whose width depends on which assembler directive has the -bit-field as its argument. Overflow (a result from the bitwise and -requiring more binary digits to represent) is not an error; instead, -more constants are generated, of the specified width, beginning with the -least significant digits.@refill - -The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long}, -@code{.short}, and @code{.word} accept bit-field arguments. -_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 -* Sub-Sections:: Sub-Sections -* 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 -0. @code{_LD__} will assign the final addresses the partial program -occupies, so that different partial programs don't overlap. This is -actually an over-simplification, but it will suffice to explain how -@code{_AS__} uses sections. - -@code{_LD__} moves blocks of bytes of your program to their run-time -addresses. These blocks slide to their run-time addresses as rigid -units; their length does not change and neither does the order of bytes -within them. Such a rigid unit is called a @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. - -_if__(_COFF__) -_if__(_GENERIC__) -When it generates COFF output, -_fi__(_GENERIC__) -@code{_AS__} can also generate whatever other named sections you specify -using the @samp{.section} directive (@pxref{Section,,@code{.section}}). -If you don't use any directives that place output in the @samp{.text} -or @samp{.data} sections, these sections will still exist, but will be empty. -_fi__(_COFF__) - -Within the object file, the text section starts at address @code{0}, the -data section follows, and the bss section follows the data section. - -To let @code{_LD__} know which data will change when the sections are -relocated, and how to change that data, @code{_AS__} also writes to the -object file details of the relocation needed. To perform relocation -@code{_LD__} must know, each time an address in the object -file is mentioned: -@itemize @bullet -@item -Where in the object file is the beginning of this reference to -an address? -@item -How long (in bytes) is this reference? -@item -Which section does the address refer to? What is the numeric value of -@display -(@var{address}) @minus{} (@var{start-address of section})? -@end display -@item -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}) -@end display -@noindent -Further, every expression @code{_AS__} computes is of this section-relative -nature. @dfn{Absolute expression} means an expression with section -``absolute'' (@pxref{_LD__ Sections}). A @dfn{pass1 expression} means -an expression with section ``pass1'' (@pxref{_AS__ Sections,,_AS__ -Internal Sections}). In this manual we use the notation @{@var{secname} -@var{N}@} to mean ``offset @var{N} into section @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. 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. -Address @code{@{absolute@ 239@}} in one partial program will always be the same -address when the program is running as address @code{@{absolute@ 239@}} in any -other partial program. - -The idea of sections is extended to the @dfn{undefined} section. Any -address whose section is unknown at assembly time is by definition -rendered @{undefined @var{U}@}---where @var{U} will be filled in later. -Since numbers are always defined, the only way to generate an undefined -address is to mention an undefined symbol. A reference to a named -common block would be such a symbol: its value is unknown at assembly -time so it has section @emph{undefined}. - -By analogy the word @emph{section} is used to describe groups of sections in -the linked program. @code{_LD__} puts all partial programs' text -sections in contiguous addresses in the linked program. It is -customary to refer to the @emph{text section} of a program, meaning all -the addresses of all partial program's text sections. Likewise for -data and bss sections. - -Some sections are manipulated by @code{_LD__}; others are invented for -use of @code{_AS__} and have no meaning except during assembly. - -@node _LD__ Sections, _AS__ Sections, Secs Background, Sections -@section _LD__ Sections -@code{_LD__} deals with just four kinds of sections, summarized below. - -@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__) -These sections hold your program. @code{_AS__} and @code{_LD__} treat them as -separate but equal sections. Anything you can say of one section is -true another. -_if__(_AOUT__||_BOUT__) -When the program is running, however, it is -customary for the text section to be unalterable. The -text section is often shared among processes: it will contain -instructions, constants and the like. The data section of a running -program is usually alterable: for example, C variables would be stored -in the data section. -_fi__(_AOUT__||_BOUT__) - -@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 -each partial program's bss section is important, but because it starts -out containing zeroed bytes there is no need to store explicit zero -bytes in the object file. The bss section was invented to eliminate -those explicit zeros from object files. - -@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 section names @samp{.text} and @samp{.data}. -_fi__(_COFF__) -Memory addresses are on the horizontal axis. - -@c TEXI2ROFF-KILL -@ifinfo -@c END TEXI2ROFF-KILL -@smallexample - +-----+----+--+ -partial program # 1: |ttttt|dddd|00| - +-----+----+--+ - - text data bss - seg. seg. seg. - - +---+---+---+ -partial program # 2: |TTT|DDD|000| - +---+---+---+ - - +--+---+-----+--+----+---+-----+~~ -linked program: | |TTT|ttttt| |dddd|DDD|00000| - +--+---+-----+--+----+---+-----+~~ - - addresses: 0 @dots{} -@end smallexample -@c TEXI2ROFF-KILL -@end ifinfo -@c FIXME make sure no page breaks inside figure!! -@tex - -\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} - -\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} - -\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} - -\line{\it addresses: \hfil} -\line{0\dots\hfil} - -@end tex -@c END TEXI2ROFF-KILL - -@node _AS__ Sections, Sub-Sections, _LD__ Sections, Sections -@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__} -warning messages, so it might be helpful to have an idea of their -meanings to @code{_AS__}. These sections are used to permit the -value of every expression in your assembly language program to be a -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 -does not fit into 32 bits, and cannot be an argument (@pxref{Arguments}) -in an expression: this is done by making a flonum or bignum be in a -separate internal section. This is purely for internal @code{_AS__} -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 -in a way that defies the one-pass (section + offset in section) assembly -process. No compiler need emit such an expression. - -@quotation -@emph{Warning:} the second pass is currently not implemented. @code{_AS__} -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 -in the expression then the expression assumes a new section. The -intention is to permit statements like -@samp{.word label - base_of_table} -to be assembled in one pass where both @code{label} and -@code{base_of_table} are undefined. This is useful for compiling C and -Algol switch statements, Pascal case statements, FORTRAN computed goto -statements and the like. -@c FIXME item debug -@c FIXME item transfer[t] vector preload -@c FIXME item transfer[t] vector postload -@c FIXME item register -@end table - -@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. -_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 -constants in the text section, but might not want to have them -interspersed with the program being assembled. In this case, the -compiler could issue a @samp{.text 0} before each section of code being -output, and a @samp{.text 1} before each group of constants being output. - -Subsections are optional. If you don't use subsections, everything -will be stored in subsection number zero. - -_if__(_GENERIC__) -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 -@c doesn't seem particularly useful to say without further elaboration, -@c so for now I say nothing about it. If this is a generic BFD issue, -@c these paragraphs might need to vanish from this manual, and be -@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 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 -other programs that manipulate object files will see no trace of them. -They just see all your text subsections as a text section, and all your -data subsections as a data section. - -To specify which subsection you want subsequent statements assembled -into, use a numeric argument to specify it, in a @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. *" -.text 1 -.ascii "But this lives in the second text subsection." -.data 0 -.ascii "This lives in the data section," -.ascii "in the first data subsection." -.text 0 -.ascii "This lives in the first text section," -.ascii "immediately following the asterisk (*)." -@end smallexample - -Each section has a @dfn{location counter} incremented by one for every -byte assembled into that section. Because subsections are merely a -convenience restricted to @code{_AS__} there is no concept of a subsection -location counter. There is no way to directly manipulate a location -counter---but the @code{.align} directive will change it, and any label -definition will capture its current value. The location counter of the -section that statements are being assembled into is said to be the -@dfn{active} location counter. - -@node bss, , Sub-Sections, Sections -@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 -your program starts running, all the contents of the bss -section are zeroed bytes. - -Addresses in the bss section are allocated with special directives; you -may not assemble anything directly into the bss section. Hence there -are no bss subsections. @xref{Comm,,@code{.comm}}, -@pxref{Lcomm,,@code{.lcomm}}. - -@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 - -@menu -* Labels:: Labels -* Setting Symbols:: Giving Symbols Other Values -* Symbol Names:: Symbol Names -* Dot:: The Special Dot Symbol -* Symbol Attributes:: Symbol Attributes -@end menu - -@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 -operand. You are warned if you use the same symbol to represent two -different locations: the first definition overrides any other -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} -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{_.$} -_fi__(!_H8__) -_if__(_H8__) -@samp{_.} -_if__(_GENERIC__) -(On most machines, you can also use @code{$} in symbol names; exceptions -are noted in @ref{_MACH_DEP__}.) -_fi__(_GENERIC__) -_fi__(_H8__) -That character may be followed by any string of digits, letters, -_if__(!_H8__) -underscores and dollar signs. -_fi__(!_H8__) -_if__(_H8__) -_if__(_GENERIC__) -dollar signs (unless otherwise noted in @ref{_MACH_DEP__}), -_fi__(_GENERIC__) -and underscores. -_fi__(_H8__) -Case of letters is significant: -@code{foo} is a different symbol name than @code{Foo}. - -_if__(_A29K__) -For the AMD 29K family, @samp{?} is also allowed in the -body of a symbol name, though not at its beginning. -_fi__(_A29K__) - -Each symbol has exactly one name. Each name in an assembly language -program refers to exactly one symbol. You may use that symbol name any -number of times in a program. - -@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} -@dots{} @samp{9}. To define a local symbol, write a label of the form -@samp{@b{N}:} (where @b{N} represents any digit). To refer to the most -recent previous definition of that symbol write @samp{@b{N}b}, using the -same digit as when you defined the label. To refer to the next -definition of a local label, write @samp{@b{N}f}---where @b{N} gives you -a choice of 10 forward references. The @samp{b} stands for -``backwards'' and the @samp{f} stands for ``forwards''. - -Local symbols are not emitted by the current GNU C compiler. - -There is no restriction on how you can use these labels, but -remember that at any point in the assembly you can refer to at most -10 prior local labels and to at most 10 forward local labels. - -Local symbol names are only a notation device. They are immediately -transformed into more conventional symbol names before the assembler -uses them. The symbol names stored in the symbol table, appearing in -error messages and optionally emitted to the object file have these -parts: - -@table @code -@item L -All local labels begin with @samp{L}. Normally both @code{_AS__} and -@code{_LD__} forget symbols that start with @samp{L}. These labels are -used for symbols you are never intended to see. If you give the -@samp{-L} option then @code{_AS__} will retain these symbols in the -object file. If you also instruct @code{_LD__} to retain these symbols, -you may use them in debugging. - -@item @var{digit} -If the label is written @samp{0:} then the digit is @samp{0}. -If the label is written @samp{1:} then the digit is @samp{1}. -And so on up through @samp{9:}. - -@item @ctrl{A} -This unusual character is included so you don't accidentally invent -a symbol of the same name. The character has ASCII value -@samp{\001}. - -@item @emph{ordinal number} -This is a serial number to keep the labels distinct. The first -@samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the -number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:} -through @samp{9:}. -@end table - -For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th -@code{3:} is named @code{L3@ctrl{A}44}. - -@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. -Assigning a value to @code{.} is treated the same as a @code{.org} -directive. Thus, the expression @samp{.=.+4} is the same as saying -_if__(!_A29K__) -@samp{.space 4}. -_fi__(!_A29K__) -_if__(_A29K__) -@samp{.block 4}. -_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 can also have auxiliary -attributes. -_if__(_INTERNALS__) -The detailed definitions are in _0__<a.out.h>_1__. -_fi__(_INTERNALS__) - -If you use a symbol without defining it, @code{_AS__} assumes zero for -all these attributes, and probably won't warn you. This makes the -symbol an externally defined symbol, which is generally what you -would want. - -@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__) -@end menu - -@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. -Naturally for text, data and bss sections the value of a symbol changes -as @code{_LD__} changes section base addresses during linking. Absolute -symbols' values do not change during linking: that is why they are -called absolute. - -The value of an undefined symbol is treated in a special way. If it is -0 then the symbol is not defined in this assembler source program, and -@code{_LD__} will try to determine its value from other programs it is -linked with. You make this kind of symbol simply by mentioning a symbol -name without defining it. A non-zero value represents a @code{.comm} -common declaration. The value is how much common storage to reserve, in -bytes (addresses). The symbol refers to the first address of the -allocated storage. - -_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__) -_if__(_COFF__) -@node a.out Symbols, COFF Symbols, Symbol Type, Symbol Attributes -_fi__(_COFF__) -_if__(!_COFF__) -@node a.out Symbols, , Symbol Type, Symbol Attributes -_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__) -_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 -@end menu - -@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 -@code{_AS__}. - -@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. -_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. - -@menu -* Empty Exprs:: Empty Expressions -* Integer Exprs:: Integer Expressions -@end menu - -@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 -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}. - -@menu -* Arguments:: Arguments -* Operators:: Operators -* Prefix Ops:: Prefix Operators -* Infix Ops:: Infix Operators -@end menu - -@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 -the machine language, we use the term ``argument'' to refer to parts of -expressions only, reserving the word ``operand'' to refer only to machine -instruction operands. - -Symbols are evaluated to yield @{@var{section} @var{NNN}@} where -@var{section} is one of text, data, bss, absolute, -or undefined. @var{NNN} is a signed, 2's complement 32 bit -integer. - -Numbers are usually integers. - -A number can be a flonum or bignum. In this case, you are warned -that only the low order 32 bits are used, and @code{_AS__} pretends -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 Operator - -@cindex prefix operators -@code{_AS__} has the following @dfn{prefix operators}. They each take -one argument, which must be absolute. - -@c the tex/end tex stuff surrounding this small table is meant to make -@c it align, on the printed page, with the similar table in the next -@c section (which is inside an enumerate). -@tex -\global\advance\leftskip by \itemindent -@end tex - -@table @code -@item - -@dfn{Negation}. Two's complement negation. -@item ~ -@dfn{Complementation}. Bitwise not. -@end table - -@tex -\global\advance\leftskip by -\itemindent -@end tex - -@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__} -@end table - -@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. -If either argument is undefined the result is difference section. -If both arguments are in the same section, the result is absolute---provided -that section is one of text, data or bss. -Otherwise subtraction is illegal. -@end table -@end enumerate - -The sense of the rule for addition is that it's only meaningful to add -the @emph{offsets} in an address; you can only have a defined section in -one of the two arguments. - -Similarly, you can't subtract quantities from two different sections. - -@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, usually in lower case. - -This chapter discusses directives present regardless of the target -machine configuration for the GNU assembler. -_if__(!_H8__) -@xref{_MACH_DEP__} for additional directives. -_fi__(!_H8__) - -@menu -* Abort:: @code{.abort} -_if__(_COFF__) -* coff-ABORT:: @code{.ABORT} -_fi__(_COFF__) -_if__(_BOUT__&&!_COFF__) -* bout-ABORT:: @code{.ABORT} -_fi__(_BOUT__&&!_COFF__) -* Align:: @code{.align @var{abs-expr} , @var{abs-expr}} -* App-File:: @code{.app-file @var{string}} -* Ascii:: @code{.ascii "@var{string}"}@dots{} -* Asciz:: @code{.asciz "@var{string}"}@dots{} -* Byte:: @code{.byte @var{expressions}} -* Comm:: @code{.comm @var{symbol} , @var{length} } -* Data:: @code{.data @var{subsection}} -_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} -_fi__(_COFF__||_BOUT__) -* Endif:: @code{.endif} -* Equ:: @code{.equ @var{symbol}, @var{expression}} -* Extern:: @code{.extern} -_if__(_GENERIC__||!_A29K__) -* File:: @code{.file @var{string}} -_fi__(_GENERIC__||!_A29K__) -* Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}} -* Float:: @code{.float @var{flonums}} -* Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}} -* hword:: @code{.hword @var{expressions}} -* Ident:: @code{.ident} -* If:: @code{.if @var{absolute expression}} -* 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} -* 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}, @var{subsection}} -_fi__(_COFF__) -* Set:: @code{.set @var{symbol}, @var{expression}} -* Short:: @code{.short @var{expressions}} -* Single:: @code{.single @var{flonums}} -_if__(_COFF__||_BOUT__) -* Size:: @code{.size} -_fi__(_COFF__||_BOUT__) -* Space:: @code{.space @var{size} , @var{fill}} -_if__(_GENERIC__||!_H8__) -* Stab:: @code{.stabd, .stabn, .stabs} -_fi__(_GENERIC__||!_H8__) -_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}} -_fi__(_COFF__||_BOUT__) -* Word:: @code{.word @var{expressions}} -* Deprecated:: Deprecated Directives -@end menu - -_if__(_COFF__) -@node Abort, coff-ABORT, Pseudo Ops, Pseudo Ops -_fi__(_COFF__) -_if__((!_COFF__) && _BOUT__) -@node Abort, bout-ABORT, Pseudo Ops, Pseudo Ops -_fi__((!_COFF__) && _BOUT__) -_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 -of the source quit, it could use this directive tells @code{_AS__} to -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__) - -_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, -but ignores it. -_fi__(_BOUT__) - -_if__( ! (_COFF__ || _BOUT__) ) -@node Align, App-File, Abort, Pseudo Ops -_fi__( ! (_COFF__ || _BOUT__) ) -_if__( _COFF__) -@node Align, App-File, coff-ABORT, Pseudo Ops -_fi__( _COFF__) -_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 -advancement. For example @samp{.align 3} will advance the location -counter until it a multiple of 8. If the location counter is already a -multiple of 8, no change is needed. - -The second expression (also absolute) gives the value to be stored in -the padding bytes. It (and the comma) may be omitted. If it is -omitted, the padding bytes are zero. - -@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}) -_fi__(!_A29K__) -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 recognized whether or not it is surrounded by quotes @samp{"}; -but if you wish to specify an empty file name is permitted, -you must give the quotes--@code{""}. This statement may go away in -future: it is only recognized to be compatible with old @code{_AS__} -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 -@code{_LD__} that it must be at least @var{length} bytes long. @code{_LD__} -will allocate space for each @code{.comm} symbol that is at least as -long as the longest @code{.comm} request in any of the partial programs -linked. @var{length} is an absolute expression. - -_if__(_COFF__ || _BOUT__) -@node Data, Def, Comm, Pseudo Ops -_fi__(_COFF__ || _BOUT__) -_if__(!(_COFF__ || _BOUT__) && _AOUT__) -@node Data, Desc, Comm, Pseudo Ops -_fi__(!(_COFF__ || _BOUT__) && _AOUT__) -_if__(! (_COFF__ || _BOUT__ || _AOUT__) ) -@c Well, this *might* happen... -@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 -to zero. - -_if__(_COFF__ || _BOUT__) -_if__(_AOUT__ || _BOUT__) -@node Def, Desc, Data, Pseudo Ops -_fi__(_AOUT__ || _BOUT__) -_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__) - -This directive is only observed when @code{_AS__} is configured for COFF -format output; when producing @code{b.out}, @samp{.def} is recognized, -but ignored. -_fi__(_BOUT__) -_fi__(_COFF__ || _BOUT__) - -_if__(_AOUT__||_BOUT__) -_if__(_COFF__||_BOUT__) -@node Desc, Dim, Def, Pseudo Ops -_fi__(_COFF__||_BOUT__) -_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. - -_if__(_COFF__) -The @samp{.desc} directive is not available when @code{_AS__} is -configured for COFF output; it is only for @code{a.out} or @code{b.out} -object format. For the sake of compatibility, @code{_AS__} will accept -it, but produce no output, when configured for COFF. -_fi__(_COFF__) -_fi__(_AOUT__||_BOUT__) - -_if__(_COFF__ || _BOUT__) -_if__(_AOUT__ || _BOUT__) -@node Dim, Double, Desc, Pseudo Ops -_fi__(_AOUT__ || _BOUT__) -_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. -_if__(_BOUT__) - -@samp{.dim} is only meaningful when generating COFF format output; when -@code{_AS__} is generating @code{b.out}, it accepts this directive but -ignores it. -_fi__(_BOUT__) -_fi__(_COFF__ || _BOUT__) - -_if__(_COFF__||_BOUT__) -@node Double, Eject, Dim, Pseudo Ops -_fi__(_COFF__||_BOUT__) -_if__(!(_COFF__||_BOUT__)) -@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__) -The exact kind of floating point numbers emitted depends on how -@code{_AS__} is configured. @xref{_MACH_DEP__}. -_fi__(_GENERIC__) -_if__((!_GENERIC__) && _IEEEFLOAT__) -On the _HOST__ family @samp{.double} emits 64-bit floating-point numbers -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, Eject, Pseudo Ops -_fi__(_COFF__||_BOUT__) -_if__(!(_COFF__||_BOUT__)) -@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} -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"). -_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__) - -@samp{.endef} is only meaningful when generating COFF format output; if -@code{_AS__} is configured to generate @code{b.out}, it accepts this -directive but ignores it. -_fi__(_BOUT__) -_fi__(_COFF__||_BOUT__) - -_if__(_COFF__||_BOUT__) -@node Endif, Equ, Endef, Pseudo Ops -_fi__(_COFF__||_BOUT__) -_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}}. - -@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}}. - -_if__(_GENERIC__||!_A29K__) -@node Extern, File, Equ, Pseudo Ops -_fi__(_GENERIC__||!_A29K__) -_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{.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 -recognized whether or not it is surrounded by quotes @samp{"}; but if -you wish to specify an empty file name, you must give the -quotes--@code{""}. This statement may go away in future: it is only -recognized to be compatible with old @code{_AS__} programs. -_if__(_A29K__) -In some configurations of @code{_AS__}, @code{.file} has already been -removed to avoid conflicts with other assemblers. @xref{_MACH_DEP__}. -_fi__(_A29K__) -_fi__(_GENERIC__||!_A29K__) - -_if__(_GENERIC__||!_A29K__) -@node Fill, Float, File, Pseudo Ops -_fi__(_GENERIC__||!_A29K__) -_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 -more than 8, then it is deemed to have the value 8, compatible with -other people's assemblers. The contents of each @var{repeat} bytes -is taken from an 8-byte number. The highest order 4 bytes are -zero. The lowest order 4 bytes are @var{value} rendered in the -byte-order of an integer on the computer @code{_AS__} is assembling for. -Each @var{size} bytes in a repetition is taken from the lowest order -@var{size} bytes of this number. Again, this bizarre behavior is -compatible with other people's assemblers. - -@var{size} and @var{value} are optional. -If the second comma and @var{value} are absent, @var{value} is -assumed zero. If the first comma and following tokens are absent, -@var{size} is assumed to be 1. - -@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__) -The exact kind of floating point numbers emitted depends on how -@code{_AS__} is configured. -@xref{_MACH_DEP__}. -_fi__(_GENERIC__) -_if__((!_GENERIC__) && _IEEEFLOAT__) -On the _HOST__ family, @code{.float} emits 32-bit floating point numbers -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. - -Both spellings (@samp{.globl} and @samp{.global}) are accepted, for -compatibility with other assemblers. - -_if__(_AOUT__||_BOUT__||_COFF__) -@node hword, Ident, Global, Pseudo Ops -_fi__(_AOUT__||_BOUT__||_COFF__) -_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. - -_if__(_GENERIC__) -This directive is a synonym for @samp{.short}; depending on the target -architecture, it may also be a synonym for @samp{.word}. -_fi__(_GENERIC__) -_if__( _W32__ && !_GENERIC__ ) -This directive is a synonym for @samp{.short}. -_fi__( _W32__ && !_GENERIC__ ) -_if__(_W16__ && !_GENERIC__ ) -This directive is a synonym for both @samp{.short} and @samp{.word}. -_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 -for it. -_fi__(_AOUT__||_BOUT__||_COFF__) - -_if__(_AOUT__||_BOUT__||_COFF__) -@node If, Include, Ident, Pseudo Ops -_fi__(_AOUT__||_BOUT__||_COFF__) -_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 -the conditional section of code must be marked by @code{.endif} -(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the -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} -@cindex @code{ifdef} directive -Assembles the following section of code if the specified @var{symbol} -has been defined. - -_if__(0) -@item .ifeqs -@cindex @code{ifeqs} directive -Not yet implemented. -_fi__(0) - -@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. - -_if__(0) -@item ifnes -Not yet implemented. -_fi__(0) -@end table - -@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 -included file is reached, assembly of the original file continues. You -can control the search paths used with the @samp{-I} command-line option -(@pxref{Invoking,,Command-Line Options}). Quotation marks are required -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__(_GENERIC__||!_H8__) -32-bit -_fi__(_GENERIC__||!_H8__) -_if__(_H8__&&!_GENERIC__) -16-bit -_fi__(_H8__&&!_GENERIC__) -number that will, at run -time, be the value of that expression. The byte order of the -expression depends on what kind of computer will run the program. - -@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 -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, Lflags, Pseudo Ops -@section @code{.line @var{line-number}} - -@cindex @code{line} directive -_fi__(_GENERIC__ || (!_A29K__)) -_if__(_A29K__ && (!_GENERIC__)) -@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 -number. So any other statements on the current line (after a statement -separator -_if__(_GENERIC__) -character) -_fi__(_GENERIC__) -_if__(!_GENERIC__) -_if__(! (_A29K__||_H8__) ) -character @code{;}) -_fi__(! (_A29K__||_H8__) ) -_if__(_A29K__) -character @samp{@@}) -_fi__(_A29K__) -_if__(_H8__) -character @samp{$}) -_fi__(_H8__) -_fi__(!_GENERIC__) -will be reported as on logical line number -@var{line-number} @minus{} 1. -One day this directive will be unsupported: it is used only -for compatibility with existing assembler programs. @refill - -_if__(_GENERIC__ && _A29K__) -@emph{Warning:} In the AMD29K configuration of _AS__, this command is -only available with the name @code{.ln}, rather than as either -@code{.line} or @code{.ln}. -_fi__(_GENERIC__ && _A29K__) -_fi__(_AOUT__||_BOUT__) -_if__(_COFF__) - -Even though this is a directive associated with the @code{a.out} or -@code{b.out} object-code formats, @code{_AS__} will still recognize it -when producing COFF output, and will treat @samp{.line} as though it -were the COFF @samp{.ln} @emph{if} it is found outside a -@code{.def}/@code{.endef} pair. - -Inside a @code{.def}, @samp{.line} is, instead, one of the directives -used by compilers to generate auxiliary symbol information for -debugging. -_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 -statement separator character @code{;}) will be reported as on logical -line number @var{line-number} @minus{} 1. -_if__(_BOUT__) - -This directive is accepted, but ignored, when @code{_AS__} is configured for -@code{b.out}; its effect is only associated with COFF output format. -_fi__(_BOUT__) -_fi__(_COFF__&&!_AOUT__) - -@node List, Long, Ln, Pseudo Ops -@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, 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 -the same as the expression value: -@smallexample -@var{other} = @var{descriptor} = 0 -@var{type} = @r{(section of @var{expression})} -@var{value} = @var{expression} -@end smallexample -@noindent -The new symbol is not flagged as external. - -@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, 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, -you can't use @code{.org} to cross sections: if @var{new-lc} has the -wrong section, the @code{.org} directive is ignored. To be compatible -with former assemblers, if the section of @var{new-lc} is absolute, -@code{_AS__} will issue a warning, then pretend the section of @var{new-lc} -is the same as the current subsection. - -@code{.org} may only increase the location counter, or leave it -unchanged; you cannot use @code{.org} to move the location counter -backwards. - -@c double negative used below "not undefined" because this is a specific -@c reference to "undefined" (as SEG_UNKNOWN is called in this manual) -@c section. pesch@cygnus.com 18feb91 -Because @code{_AS__} tries to assemble programs in one pass @var{new-lc} -may not be undefined. If you really detest this restriction we eagerly await -a chance to share your improved assembler. - -Beware that the origin is relative to the start of the section, not -to the start of the subsection. This is compatible with other -people's assemblers. - -When the location counter (of the current subsection) is advanced, the -intervening bytes are filled with @var{fill} which should be an -absolute expression. If the comma and @var{fill} are omitted, -@var{fill} defaults to zero. - -@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. -_fi__(_GENERIC__||(!_I960__)) -_if__(_I960__&&(!_GENERIC__)) -a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a -warning message; and just takes the lowest order 16 bytes of the -bignum.@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, Sbttl, Pseudo Ops -_fi__(!_COFF__) -_if__(_COFF__) -@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 -symbolic debugging information. -_if__(_BOUT__) - -The @samp{.scl} directive is primarily associated with COFF output; when -configured to generate @code{b.out} output format, @code{_AS__} will -accept this directive but ignore it. -_fi__(_BOUT__) -_fi__(_COFF__||_BOUT__) - -_if__(_COFF__) -@node Section, Set, Scl, Pseudo Ops -@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. - -@node Set, Short, Section, Pseudo Ops -_fi__(_COFF__) -_if__(_BOUT__&&!_COFF__) -@node Set, Short, Scl, Pseudo Ops -_fi__(_BOUT__&&!_COFF__) -_if__(!(_COFF__||_BOUT__)) -@node Set, Short, Quad, Pseudo Ops -_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 -flagged. (@xref{Symbol Attributes}.) - -You may @code{.set} a symbol many times in the same assembly. -If the expression's section is unknowable during pass 1, a second -pass over the source program will be forced. The second pass is -currently not implemented. @code{_AS__} will abort with an error -message if one is required. - -If you @code{.set} a global symbol, the value stored in the object -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__) -In some configurations, however, @code{.short} and @code{.word} generate -numbers of different lengths; @pxref{_MACH_DEP__}. -_fi__(_W32__) -_fi__(_GENERIC__|| _W16__) -_if__((!_GENERIC__) && _W32__) -This expects zero or more @var{expressions}, and emits -a 16 bit number for each. -_fi__((!_GENERIC__) && _W32__) -_if__(_COFF__||_BOUT__) -@node Single, Size, Short, Pseudo Ops -_fi__(_COFF__||_BOUT__) -_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__) -The exact kind of floating point numbers emitted depends on how -@code{_AS__} is configured. @xref{_MACH_DEP__}. -_fi__(_GENERIC__) -_if__((!_GENERIC__) && _IEEEFLOAT__) -On the _HOST__ family, @code{.single} emits 32-bit floating point -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. -_if__(_BOUT__) - -@samp{.size} is only meaningful when generating COFF format output; when -@code{_AS__} is generating @code{b.out}, it accepts this directive but -ignores it. -_fi__(_BOUT__) -_fi__(_COFF__||_BOUT__) - -_if__(_H8__&&!_GENERIC__) -@node Space, Tag, Size, Pseudo Ops -_fi__(_H8__&&!_GENERIC__) -_if__(_GENERIC__||!_H8__) -_if__(_COFF__||_BOUT__) -@node Space, Stab, Size, Pseudo Ops -_fi__(_COFF__||_BOUT__) -_if__(!(_COFF__||_BOUT__)) -@node Space, Stab, Single, Pseudo Ops -_fi__(!(_COFF__||_BOUT__)) -_fi__(_GENERIC__||!_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. -_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. - -@quotation -@emph{Warning:} In other versions of the GNU assembler, the directive -@code{.space} has the effect of @code{.block} @xref{_MACH_DEP__}. -@end quotation -_fi__(_A29K__) - -_if__(_GENERIC__||!_H8__) -_if__(_AOUT__||_BOUT__||_COFF__) -_if__(_COFF__||_BOUT__) -@node Stab, Tag, Space, Pseudo Ops -_fi__(_COFF__||_BOUT__) -_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 -cannot be referenced elsewhere in the source file. -Up to five fields are required: -@table @var -@item string -This is the symbol's name. It may contain any character except @samp{\000}, -so is more general than ordinary symbol names. Some debuggers used to -code arbitrarily complex structures into symbol names using this field. -@item type -An absolute expression. The symbol's type is set to the low 8 -bits of this expression. -Any bit pattern is permitted, but @code{_LD__} and debuggers will choke on -silly bit patterns. -@item other -An absolute expression. -The symbol's ``other'' attribute is set to the low 8 bits of this expression. -@item desc -An absolute expression. -The symbol's descriptor is set to the low 16 bits of this expression. -@item value -An absolute expression which becomes the symbol's value. -@end table - -If a warning is detected while reading a @code{.stabd}, @code{.stabn}, -or @code{.stabs} statement, the symbol has probably already been created -and you will get a half-formed symbol in your object file. This is -compatible with earlier assemblers! - -@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. -It is a null pointer, for compatibility. Older assemblers used a -null pointer so they didn't waste space in object files with empty -strings. - -The symbol's value is set to the location counter, -relocatably. When your program is linked, the value of this symbol -will be where the location counter was when the @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__) -_fi__(_GENERIC__||!_H8__) - -_if__(_COFF__||_BOUT__) -_if__(_GENERIC__||!_H8__) -@node Tag, Text, Stab, Pseudo Ops -_fi__(_GENERIC__||!_H8__) -_if__(_H8__&&!_GENERIC__) -@node Tag, Text, Space, Pseudo Ops -_fi__(_H8__&&!_GENERIC__) -@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 -definitions in the symbol table with instances of those structures. -_if__(_BOUT__) - -@samp{.tag} is only used when generating COFF format output; when -@code{_AS__} is generating @code{b.out}, it accepts this directive but -ignores it. -_fi__(_BOUT__) -_fi__(_COFF__||_BOUT__) - -_if__(_COFF__||_BOUT__) -@node Text, Title, Tag, Pseudo Ops -_fi__(_COFF__||_BOUT__) -_if__(!(_COFF__||_BOUT__)) -@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 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__) - -@samp{.type} is associated only with COFF format output; when -@code{_AS__} is configured for @code{b.out} output, it accepts this -directive but ignores it. -_fi__(_BOUT__) -_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. -_if__(_BOUT__) - -@samp{.val} is used only for COFF output; when @code{_AS__} is -configured for @code{b.out}, it accepts this directive but ignores it. -_fi__(_BOUT__) -_fi__(_COFF__||_BOUT__) - -_if__(_COFF__||_BOUT__) -@node Word, Deprecated, Val, Pseudo Ops -_fi__(_COFF__||_BOUT__) -_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__) -For each expression, @code{_AS__} emits a 32-bit number. -_fi__((!_GENERIC__) && _W32__) -_if__((!_GENERIC__) && _W16__) -For each expression, @code{_AS__} emits a 16-bit number. -_fi__((!_GENERIC__) && _W16__) - -_if__(_GENERIC__) -The size of the number emitted, and its byte order, -depends on what kind of computer will run the program. -_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 - -_if__(_GENERIC__) -Machines with a 32-bit address space, but that do less than 32-bit -addressing, require the following special treatment. If the machine of -interest to you does 32-bit addressing (or doesn't require it; -@pxref{_MACH_DEP__}), you can ignore this issue. - -_fi__(_GENERIC__) -In order to assemble compiler output into something that will work, -@code{_AS__} will occasionlly do strange things to @samp{.word} directives. -Directives of the form @samp{.word sym1-sym2} are often emitted by -compilers as part of jump tables. Therefore, when @code{_AS__} assembles a -directive of the form @samp{.word sym1-sym2}, and the difference between -@code{sym1} and @code{sym2} does not fit in 16 bits, @code{_AS__} will -create a @dfn{secondary jump table}, immediately before the next label. -This secondary jump table will be preceded by a short-jump to the -first byte after the secondary table. This short-jump prevents the flow -of control from accidentally falling into the new table. Inside the -table will be a long-jump to @code{sym2}. The original @samp{.word} -will contain @code{sym1} minus the address of the long-jump to -@code{sym2}. - -If there were several occurrences of @samp{.word sym1-sym2} before the -secondary jump table, all of them will be adjusted. If there was a -@samp{.word sym3-sym4}, that also did not fit in sixteen bits, a -long-jump to @code{sym4} will be included in the secondary jump table, -and the @code{.word} directives will be adjusted to contain @code{sym3} -minus the address of the long-jump to @code{sym4}; and so on, for as many -entries in the original jump table as necessary. - -_if__(_INTERNALS__) -@emph{This feature may be disabled by compiling @code{_AS__} with the -@samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse -assembly language programmers. -_fi__(_INTERNALS__) -_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 -@item .abort -@item .app-file -@item .line -@end table - -@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 -_fi__(_VAX__) -_if__(_A29K__) -* AMD29K-Dependent:: AMD 29K Dependent Features -_fi__(_A29K__) -_if__(_H8__) -* H8/300-Dependent:: AMD 29K Dependent Features -_fi__(_H8__) -_if__(_I960__) -* i960-Dependent:: Intel 80960 Dependent Features -_fi__(_I960__) -_if__(_M680X0__) -* M68K-Dependent:: M680x0 Dependent Features -_fi__(_M680X0__) -_if__(_SPARC__) -* Sparc-Dependent:: SPARC Dependent Features -_fi__(_SPARC__) -_if__(_I80386__) -* i386-Dependent:: 80386 Dependent Features -_fi__(_I80386__) -@end menu - -_fi__(_GENERIC__) -_if__(_VAX__) -_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 -* VAX-directives:: Vax Machine Directives -* VAX-opcodes:: VAX Opcodes -* VAX-branch:: VAX Branch Improvement -* VAX-operands:: VAX Operands -* VAX-no:: Not Supported on VAX -@end menu - -@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 -people's assemblers. - -@table @asis -@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 -can branch anywhere in virtual memory. Often there are 3 -flavors of branch: short, medium and long. Some other -assemblers would emit short and medium branches, unless told by -this option to emit short and long branches. - -@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 -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 -symbol-table entries for symbols that contain lowercase -characters (I think). The @kbd{-+} option causes @code{_AS__} to -print warning messages if the FILENAME part of the object file, -or any symbol name is larger than 31 characters. The @kbd{-+} -option also insertes some code following the @samp{_main} -symbol so that the object file will be compatible with Vax-11 -"C". - -@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. - -@code{D}, @code{F}, @code{G} and @code{H} floating point formats -are understood. - -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. - -@end table - -@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 -@code{.word} statements. This is compatible with all unix -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 -substituting @samp{j} for @samp{b} at the start of a DEC mnemonic. -This feature is included both for compatibility and to help -compilers. If you don't need this feature, don't use these -opcodes. Here are the mnemonics, and the code they can expand into. - -@table @code -@item jbsb -@samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}. -@table @asis -@item (byte displacement) -@kbd{bsbb @dots{}} -@item (word displacement) -@kbd{bsbw @dots{}} -@item (long displacement) -@kbd{jsb @dots{}} -@end table -@item jbr -@itemx jr -Unconditional branch. -@table @asis -@item (byte displacement) -@kbd{brb @dots{}} -@item (word displacement) -@kbd{brw @dots{}} -@item (long displacement) -@kbd{jmp @dots{}} -@end table -@item j@var{COND} -@var{COND} may be any one of the conditional branches -@code{neq nequ eql eqlu gtr geq lss gtru lequ vc vs gequ cc lssu cs}. -@var{COND} may also be one of the bit tests -@code{bs bc bss bcs bsc bcc bssi bcci lbs lbc}. -@var{NOTCOND} is the opposite condition to @var{COND}. -@table @asis -@item (byte displacement) -@kbd{b@var{COND} @dots{}} -@item (word displacement) -@kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:} -@item (long displacement) -@kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:} -@end table -@item jacb@var{X} -@var{X} may be one of @code{b d f g h l w}. -@table @asis -@item (word displacement) -@kbd{@var{OPCODE} @dots{}} -@item (long displacement) -@example -@var{OPCODE} @dots{}, foo ; -brb bar ; -foo: jmp @dots{} ; -bar: -@end example -@end table -@item jaob@var{YYY} -@var{YYY} may be one of @code{lss leq}. -@item jsob@var{ZZZ} -@var{ZZZ} may be one of @code{geq gtr}. -@table @asis -@item (byte displacement) -@kbd{@var{OPCODE} @dots{}} -@item (word displacement) -@example -@var{OPCODE} @dots{}, foo ; -brb bar ; -foo: brw @var{destination} ; -bar: -@end example -@item (long displacement) -@example -@var{OPCODE} @dots{}, foo ; -brb bar ; -foo: jmp @var{destination} ; -bar: -@end example -@end table -@item aobleq -@itemx aoblss -@itemx sobgeq -@itemx sobgtr -@table @asis -@item (byte displacement) -@kbd{@var{OPCODE} @dots{}} -@item (word displacement) -@example -@var{OPCODE} @dots{}, foo ; -brb bar ; -foo: brw @var{destination} ; -bar: -@end example -@item (long displacement) -@example -@var{OPCODE} @dots{}, foo ; -brb bar ; -foo: jmp @var{destination} ; -bar: -@end example -@end table -@end table - -@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. - -For instance -@smallexample -tstb *w`$4(r5) -@end smallexample - -Any expression is permitted in an operand. Operands are comma -separated. - -@c There is some bug to do with recognizing expressions -@c in operands, but I forget what it is. It is -@c a syntax clash because () is used as an address mode -@c and to encapsulate sub-expressions. - -@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 -_fi__(_GENERIC__) -_CHAPSEC__(0+_GENERIC__) AMD 29K Dependent Features - -@cindex AMD 29K support -@cindex 29K support -@menu -* AMD29K Options:: Options -* AMD29K Syntax:: Syntax -* AMD29K Floating Point:: Floating Point -* AMD29K Directives:: AMD 29K Machine Directives -* AMD29K Opcodes:: Opcodes -@end menu - -@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. - -@node AMD29K Syntax, AMD29K Floating Point, AMD29K Options, AMD29K-Dependent -_CHAPSEC__(1+_GENERIC__) Syntax -@menu -* AMD29K-Chars:: Special Characters -* AMD29K-Regs:: Register Names -@end menu - -@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 -@code{0} and @code{127}, written with no leading zeros. The leading -letters may be in either upper or lower case; for example, @samp{gr13} -and @samp{LR7} are both valid register names. - -You may also refer to general-purpose registers by specifying the -register number as the result of an expression (prefixed with @samp{%%} -to flag the expression as a register number): -@smallexample -%%@var{expression} -@end smallexample -@noindent ----where @var{expression} must be an absolute expression evaluating to a -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: - -@smallexample - vab chd pc0 - ops chc pc1 - cps rbp pc2 - cfg tmc mmu - cha tmr lru -@end smallexample - -These unprotected special-purpose register names are also recognized: -@smallexample - ipc alu fpe - ipa bp inte - ipb fc fps - q cr exop -@end smallexample - -@node AMD29K Floating Point, AMD29K Directives, AMD29K Syntax, AMD29K-Dependent -_CHAPSEC__(1+_GENERIC__) Floating Point - -@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. - -In other versions of the GNU assembler, this directive is called -@samp{.space}. -@end table - -@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. - -@quotation -@emph{Warning:} in other versions of the GNU assembler, @code{.file} is -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 -name} options, @samp{.use} is equivalent to the machine directive -@var{section name}; the remaining case, @samp{.use .lit}, is the same as -@samp{.data 200}. -@end table - -@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. - -For information on the 29K machine instruction set, see @cite{Am29000 -User's Manual}, Advanced Micro Devices, Inc. - -_fi__(_A29K__) -_if__(_H8__) -_if__(_GENERIC__) -@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 -@end menu - -@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 -_CHAPSEC__(1+_GENERIC__) Syntax -@menu -* 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 -_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 -_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 -@samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid -register names. - -You can also use the eight predefined symbols @samp{r@var{n}} to refer -to the H8/300 registers as 16-bit registers (you must use this form for -addressing). - -The two control registers are called @code{pc} (program counter; a -16-bit register) and @code{ccr} (condition code register; an 8-bit -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 -_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 -@item r@var{n} -Register direct - -@item @@r@var{n} -Register indirect - -@item @@(@var{d}, r@var{n}) -@itemx @@(@var{d}:16, r@var{n}) -Register indirect: 16-bit displacement @var{d} from register @var{n}. -(You may specify the @samp{:16} for clarity if you wish, but it is not -required and has no effect.) - -@item @@r@var{n}+ -Register indirect with post-increment - -@item @@-r@var{n} -Register indirect with pre-decrement - -@item @code{@@}@var{aa} -@itemx @code{@@}@var{aa}:8 -@itemx @code{@@}@var{aa}:16 -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}. 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. 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 -_CHAPSEC__(1+_GENERIC__) Floating Point - -@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 -_CHAPSEC__(1+_GENERIC__) Opcodes - -@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 -_fi__(_GENERIC__) -_CHAPSEC__(0+_GENERIC__) Intel 80960 Dependent Features - -@cindex i960 support -@menu -* Options-i960:: i960 Command-line Options -* Floating Point-i960:: Floating Point -* Directives-i960:: i960 Machine Directives -* Opcodes for i960:: i960 Opcodes -@end menu - -@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. - -@samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to -@samp{-AMC}. Synonyms are provided for compatibility with other tools. - -If none of these options is specified, @code{_AS__} will generate code for any -instruction or feature that is supported by @emph{some} version of the -960 (even if this means mixing architectures!). In principle, -@code{_AS__} will attempt to deduce the minimal sufficient processor -type if none is specified; depending on the object code format, the -processor type may be recorded in the object file. If it is critical -that the @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 -architectures.) If @var{BR} represents a conditional branch instruction, -the following represents the code generated by the assembler when -@samp{-b} is specified: - -@smallexample - call @var{increment routine} - .word 0 # pre-counter -Label: @var{BR} - call @var{increment routine} - .word 0 # post-counter -@end smallexample - -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. - -@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 -header. The first word, initialized to 0, is used in maintaining linked -lists of branch tables. The second word is a count of the number of -entries in the table, which follow immediately: each is a word, pointing -to one of the labels illustrated above. - -@c TEXI2ROFF-KILL -@ifinfo -@c END TEXI2ROFF-KILL -@example - +------------+------------+------------+ ... +------------+ - | | | | | | - | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N | - | | | | | | - +------------+------------+------------+ ... +------------+ - - __BRANCH_TABLE__ layout -@end example -@c TEXI2ROFF-KILL -@end ifinfo -@tex -\vskip 1pc -\line{\leftskip=0pt\hskip\tableindent -\boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt -*BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil} -\centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout} -@end tex -@c END TEXI2ROFF-KILL - -The first word of the header is used to locate multiple branch tables, -since each object file may contain one. Normally the links are -maintained with a call to an initialization routine, placed at the -beginning of each function in the file. The GNU C compiler will -generate these calls automatically when you give it a @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 -instructions. You can use the @samp{-norelax} option to specify that -@code{_AS__} should generate errors instead, if the target displacement -is larger than 13 bits. - -This option does not affect the Compare-and-Jump instructions; the code -emitted for them is @emph{always} adjusted when necessary (depending on -displacement size), regardless of whether you use @samp{-norelax}. -@end table - -@node Floating Point-i960, Directives-i960, Options-i960, i960-Dependent -_CHAPSEC__(1+_GENERIC__) Floating Point - -@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 -@var{align} must be positive absolute expressions. This directive -differs from @samp{.lcomm} only in that it permits you to specify -an alignment. @xref{Lcomm,,@code{.lcomm}}. -@end table - -@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 @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 -may define an entry point that skips procedure prolog code (and that does -not depend on system-supplied saved context), and declare it as the -@var{bal-lab} using @samp{.leafproc}. If the procedure also has an -entry point that goes through the normal prolog, you can specify that -entry point as @var{call-lab}. - -A @samp{.leafproc} declaration is meant for use in conjunction with the -optimized call instruction @samp{callj}; the directive records the data -needed later to choose between converting the @samp{callj} into a -@code{bal} or a @code{call}. - -@var{call-lab} is optional; if only one argument is present, or if the -two arguments are identical, the single argument is assumed to be the -@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 -procedures with the optimized call instruction @samp{callj}. - -Both arguments are required; @var{index} must be between 0 and 31 -(inclusive). -@end table - -@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 -architecture.@refill - -Some opcodes are processed beyond simply emitting a single corresponding -instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump -instructions with target displacements larger than 13 bits. - -@menu -* callj-i960:: @code{callj} -* Compare-and-branch-i960:: Compare-and-Branch -@end menu - -@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 -enough information---a @samp{.leafproc} or @samp{.sysproc} directive -defining the operand---then @code{_AS__} will translate the -@code{callj}; if not, it will simply emit the @code{callj}, leaving it -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 -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 -and Jump'' instruction. The ``Jump'' instructions are @emph{always} -expanded if necessary; the ``Branch'' instructions are expanded when -necessary @emph{unless} you specify @code{-norelax}---in which case -@code{_AS__} gives an error instead. - -These are the Compare-and-Branch instructions, their ``Jump'' variants, -and the instruction pairs they may expand into: - -@c TEXI2ROFF-KILL -@ifinfo -@c END TEXI2ROFF-KILL -@example - Compare and - Branch Jump Expanded to - ------ ------ ------------ - bbc chkbit; bno - bbs chkbit; bo - cmpibe cmpije cmpi; be - cmpibg cmpijg cmpi; bg - cmpibge cmpijge cmpi; bge - cmpibl cmpijl cmpi; bl - cmpible cmpijle cmpi; ble - cmpibno cmpijno cmpi; bno - cmpibne cmpijne cmpi; bne - cmpibo cmpijo cmpi; bo - cmpobe cmpoje cmpo; be - cmpobg cmpojg cmpo; bg - cmpobge cmpojge cmpo; bge - cmpobl cmpojl cmpo; bl - cmpoble cmpojle cmpo; ble - cmpobne cmpojne cmpo; bne -@end example -@c TEXI2ROFF-KILL -@end ifinfo -@tex -\hskip\tableindent -\halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr -\omit{\hfil\it Compare and\hfil}\span\omit&\cr -{\it Branch}&{\it Jump}&{\it Expanded to}\cr - bbc& & chkbit; bno\cr - bbs& & chkbit; bo\cr - cmpibe& cmpije& cmpi; be\cr - cmpibg& cmpijg& cmpi; bg\cr - cmpibge& cmpijge& cmpi; bge\cr - cmpibl& cmpijl& cmpi; bl\cr - cmpible& cmpijle& cmpi; ble\cr - cmpibno& cmpijno& cmpi; bno\cr - cmpibne& cmpijne& cmpi; bne\cr - cmpibo& cmpijo& cmpi; bo\cr - cmpobe& cmpoje& cmpo; be\cr - cmpobg& cmpojg& cmpo; bg\cr - cmpobge& cmpojge& cmpo; bge\cr - cmpobl& cmpojl& cmpo; bl\cr - cmpoble& cmpojle& cmpo; ble\cr - cmpobne& cmpojne& cmpo; bne\cr} -@end tex -@c END TEXI2ROFF-KILL -_fi__(_I960__) - -_if__(_M680X0__) -_if__(_GENERIC__) -@c FIXME! node conds are only sufficient for m68k alone, all, and vintage -_if__(_I960__) -@node M68K-Dependent, Sparc-Dependent, i960-Dependent, Machine Dependent -_fi__(_I960__) -_if__(!_I960__) -@node M68K-Dependent, Sparc-Dependent, Machine Dependent, Machine Dependent -_fi__(!_I960__) -_fi__(_GENERIC__) -_CHAPSEC__(0+_GENERIC__) M680x0 Dependent Features - -@cindex M680x0 support -@menu -* M68K-Opts:: M680x0 Options -* M68K-Syntax:: Syntax -* M68K-Float:: Floating Point -* M68K-Directives:: 680x0 Machine Directives -* M68K-opcodes:: Opcodes -@end menu - -@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__} -cannot know where these symbols will end up, @code{_AS__} can only allocate -space for the linker to fill in later. Since @code{_AS__} doesn't know how -far away these symbols will be, it allocates as much space as it can.) -If this option is given, the references will only be one word wide (16 -bits). This may be useful if you want the object file to be as small as -possible, and you know that the relevant symbols will be less than 17 -bits away. - -@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 -MC68000 or MC68010 microprocessors. You can give @code{_AS__} the options -@samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010}, -@samp{-m68020}, and @samp{-mc68020} to tell it what processor is the -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 -@samp{move.l}. - -_if__(_INTERNALS__) -If @code{_AS__} is compiled with SUN_ASM_SYNTAX defined, it will also allow -Sun-style local labels of the form @samp{1$} through @samp{$9}. -_fi__(_INTERNALS__) - -In the following table @dfn{apc} stands for any of the address -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 -@samp{#@var{digits}} - -@item Data Register -@samp{d0} through @samp{d7} - -@item Address Register -@samp{a0} through @samp{a7} - -@item Address Register Indirect -@samp{a0@@} through @samp{a7@@} - -@item Address Register Postincrement -@samp{a0@@+} through @samp{a7@@+} - -@item Address Register Predecrement -@samp{a0@@-} through @samp{a7@@-} - -@item Indirect Plus Offset -@samp{@var{apc}@@(@var{digits})} - -@item Index -@samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})} - -or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})} - -@item Postindex -@samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})} - -or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})} - -@item Preindex -@samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})} - -or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})} - -@item Memory Indirect -@samp{@var{apc}@@(@var{digits})@@(@var{digits})} - -@item Absolute -@samp{@var{symbol}}, or @samp{@var{digits}} -@ignore -@c pesch@cygnus.com: gnu, rich concur the following needs careful -@c research before documenting. - , or either of the above followed -by @samp{:b}, @samp{:w}, or @samp{:l}. -@end ignore -@end table - -@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. - -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 - -There is no directive to produce regions of memory holding -extended precision numbers, however they can be used as -immediate operands to floating-point instructions. Adding a -directive to create extended precision numbers would not be -hard, but it has not yet seemed necessary. - -@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? -@ignore -Danger: Several bugs have been found in the opcode table (and -fixed). More bugs may exist. Be careful when using obscure -instructions. -@end ignore - -@menu -* M68K-Branch:: Branch Improvement -* M68K-Chars:: Special Characters -@end menu - -@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 -@samp{b} at the start of a Motorola mnemonic. - -The following table summarizes the pseudo-operations. A @code{*} flags -cases that are more fully described after the table: - -@smallexample - Displacement - +--------------------------------------------------------- - | 68020 68000/10 -Pseudo-Op |BYTE WORD LONG LONG non-PC relative - +--------------------------------------------------------- - jbsr |bsrs bsr bsrl jsr jsr - jra |bras bra bral jmp jmp -* jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp -* dbXX |dbXX dbXX dbXX; bra; jmpl -* fjXX |fbXXw fbXXw fbXXl fbNXw;jmp - -XX: condition -NX: negative of condition XX - -@end smallexample -@center @code{*}---see full description below - -@table @code -@item jbsr -@itemx jra -These are the simplest jump pseudo-operations; they always map to one -particular machine instruction, depending on the displacement to the -branch target. - -@item j@var{XX} -Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations, -where @var{XX} is a conditional branch or condition-code test. The full -list of pseudo-ops in this family is: -@smallexample - jhi jls jcc jcs jne jeq jvc - jvs jpl jmi jge jlt jgt jle -@end smallexample - -For the cases of non-PC relative displacements and long displacements on -the 68000 or 68010, @code{_AS__} will issue a longer code fragment in terms of -@var{NX}, the opposite condition to @var{XX}: -@smallexample - j@var{XX} foo -@end smallexample -gives -@smallexample - b@var{NX}s oof - jmp foo - oof: -@end smallexample - -@item db@var{XX} -The full family of pseudo-operations covered here is -@smallexample - dbhi dbls dbcc dbcs dbne dbeq dbvc - dbvs dbpl dbmi dbge dblt dbgt dble - dbf dbra dbt -@end smallexample - -Other than for word and byte displacements, when the source reads -@samp{db@var{XX} foo}, @code{_AS__} will emit -@smallexample - db@var{XX} oo1 - bra oo2 - oo1:jmpl foo - oo2: -@end smallexample - -@item fj@var{XX} -This family includes -@smallexample - fjne fjeq fjge fjlt fjgt fjle fjf - fjt fjgl fjgle fjnge fjngl fjngle fjngt - fjnle fjnlt fjoge fjogl fjogt fjole fjolt - fjor fjseq fjsf fjsne fjst fjueq fjuge - fjugt fjule fjult fjun -@end smallexample - -For branch targets that are not PC relative, @code{_AS__} emits -@smallexample - fb@var{NX} oof - jmp foo - oof: -@end smallexample -when it encounters @samp{fj@var{XX} foo}. - -@end table - -@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 -@samp{# line file}, in which case it is treated normally. - -_fi__(_M680X0__) -_if__(0) -@c pesch@cygnus.com: conditionalize on something other than 0 when filled in. -@section 32x32 -@section Options -The 32x32 version of @code{_AS__} accepts a @kbd{-m32032} option to -specify thiat it is compiling for a 32032 processor, or a -@kbd{-m32532} to specify that it is compiling for a 32532 option. -The default (if neither is specified) is chosen when the assembler -is compiled. - -@subsection Syntax -I don't know anything about the 32x32 syntax assembled by -@code{_AS__}. Someone who undersands the processor (I've never seen -one) and the possible syntaxes should write this section. - -@subsection Floating Point -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. - -@subsection 32x32 Machine Directives -The 32x32 has no machine dependent directives. - -_fi__(0) -_if__(_SPARC__) -_if__(_GENERIC__) -_if__(_I80386__&&_M680X0__) -@node Sparc-Dependent, i386-Dependent, M68K-Dependent, Machine Dependent -_fi__(_I80386__&&_M680X0__) -_if__(_I80386__&&_I960__&&!_M680X0__) -@node Sparc-Dependent, i386-Dependent, i960-Dependent, Machine Dependent -_fi__(_I80386__&&_I960__&&!_M680X0__) -_if__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__) -@node Sparc-Dependent, i386-Dependent, AMD29K-Dependent, Machine Dependent -_fi__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__) -_if__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__) -@node Sparc-Dependent, i386-Dependent, Vax-Dependent, Machine Dependent -_fi__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__) -_if__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__) -@node Sparc-Dependent, i386-Dependent, Machine Dependent, Machine Dependent -_fi__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__) -_if__((!_I80386__)&&_M680X0__) -@node Sparc-Dependent, , M68K-Dependent, Machine Dependent -_fi__((!_I80386__)&&_M680X0__) -_if__((!_I80386__)&&_I960__&&!_M680X0__) -@node Sparc-Dependent, , i960-Dependent, Machine Dependent -_fi__((!_I80386__)&&_I960__&&!_M680X0__) -_if__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__) -@node Sparc-Dependent, , AMD29K-Dependent, Machine Dependent -_fi__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__) -_if__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__) -@node Sparc-Dependent, , Vax-Dependent, Machine Dependent -_fi__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__) -_if__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__) -@node Sparc-Dependent, , Machine Dependent, Machine Dependent -_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 -* Sparc-Directives:: Sparc Machine Directives -@end menu - -@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 -@c FIXME: (sparc) Fill in "syntax" section! -@c subsection syntax -I don't know anything about Sparc syntax. Someone who does -will have to write this section. -@end ignore - -@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 .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__) -_if__(_I80386__) -_if__(_GENERIC__) -@c FIXME! Conditionalize for all combinations in this section -@node i386-Dependent, , Sparc-Dependent, Machine Dependent -_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 -* i386-Opcodes:: Opcode Naming -* i386-Regs:: Register Naming -* i386-prefixes:: Opcode Prefixes -* i386-Memory:: Memory References -* i386-jumps:: Handling of Jump Instructions -* i386-Float:: Floating Point -* i386-Notes:: Notes -@end menu - -@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 -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) -memory references. Intel syntax accomplishes this by prefixes memory -operands (@emph{not} the opcodes themselves) with @samp{byte ptr}, -@samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte -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 -@samp{call/jmp far @var{section}:@var{offset}}. Also, the far return -instruction -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 -instruction and it contains no memory operands then @code{_AS__} tries to -fill in the missing suffix based on the destination register operand -(the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent -to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to -@samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix -assembler which assumes that a missing opcode suffix implies long -operand size. (This incompatibility does not affect compiler output -since compilers always explicitly specify the opcode suffix.) - -Almost all opcodes have the same names in AT&T and Intel format. There -are a few exceptions. The sign extend and zero extend instructions need -two sizes to specify them. They need a size to sign/zero extend -@emph{from} and a size to zero extend @emph{to}. This is accomplished -by using two opcode suffixes in AT&T syntax. Base names for sign extend -and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T -syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode -suffixes are tacked on to this base name, the @emph{from} suffix before -the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for -``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes, -thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word), -and @samp{wl} (from word to long). - -@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}, -@samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the -frame pointer), and @samp{%esp} (the stack pointer). - -@item -the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx}, -@samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}. - -@item -the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh}, -@samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These -are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx}, -@samp{%cx}, and @samp{%dx}) - -@item -the 6 section registers @samp{%cs} (code section), @samp{%ds} -(data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs}, -and @samp{%gs}. - -@item -the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and -@samp{%cr3}. - -@item -the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2}, -@samp{%db3}, @samp{%db6}, and @samp{%db7}. - -@item -the 2 test registers @samp{%tr6} and @samp{%tr7}. - -@item -the 8 floating point register stack @samp{%st} or equivalently -@samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)}, -@samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}. -@end itemize - -@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 -operands are specified in an instruction by prefixing what would -normally be 32-bit operands with a ``operand size'' opcode prefix). -Opcode prefixes are usually given as single-line instructions with no -operands, and must directly precede the instruction they act upon. For -example, the @samp{scas} (scan string) instruction is repeated with: -@smallexample - repne - scas -@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} -to calculate the address of the operand. If no @var{scale} is -specified, @var{scale} is taken to be 1. @var{section} specifies the -optional section register for the memory operand, and may override the -default section register (see a 80386 manual for section register -defaults). Note that section overrides in AT&T syntax @emph{must} have -be preceded by a @samp{%}. If you specify a section override which -coincides with the default section register, @code{_AS__} will @emph{not} -output any section register override prefixes to assemble the given -instruction. Thus, section overrides can be specified to emphasize which -section register is used for a given memory operand. - -Here are some examples of Intel and AT&T style memory references: - -@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 -@samp{%ebp} as the base register). @var{index}, @var{scale} are both missing. - -@item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]} -@var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is -@samp{foo}. All other fields are missing. The section register here -defaults to @samp{%ds}. - -@item AT&T: @samp{foo(,1)}; Intel @samp{[foo]} -This uses the value pointed to by @samp{foo} as a memory operand. -Note that @var{base} and @var{index} are both missing, but there is only -@emph{one} @samp{,}. This is a syntactic exception. - -@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 -prefixed with @samp{*}. If no @samp{*} is specified, @code{_AS__} will -always choose PC relative addressing for jump/call labels. - -Any instruction that has a memory operand @emph{must} specify its size (byte, -word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l}, -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 -is insufficient a long (32-bit) displacement is used. We do not support -word (16-bit) displacement jumps (i.e. prefixing the jump instruction -with the @samp{addr16} opcode prefix), since the 80386 insists upon masking -@samp{%eip} to 16 bits after the word displacement is added. - -Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz}, -@samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in -byte displacements, so that it is possible that use of these -instructions (@code{_GCC__} does not use them) will cause the assembler to -print an error message (and generate incorrect code). The AT&T 80386 -assembler tries to get around this problem by expanding @samp{jcxz foo} to -@smallexample - jcxz cx_zero - jmp cx_nonzero -cx_zero: jmp foo -cx_nonzero: -@end smallexample - -@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), -double (64-bit), and extended (80-bit) precision floating point. -Each supported type has an opcode suffix and a constructor -associated with it. Opcode suffixes specify operand's data -types. Constructors build these data types into memory. - -@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}. -@samp{t} stands for temporary real, and that the 80387 only supports -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} -(quad). As with the temporary real format the 64-bit @samp{q} format is -only present in the @samp{fildq} (load quad integer to stack top) and -@samp{fistpq} (store quad integer and pop stack) instructions. -@end itemize - -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 -the @samp{fwait} instruction whenever it is implicitly selected by one -of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and -@samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}} -instructions are made equivalent to @samp{f@dots{}} instructions. If -@samp{fwait} is desired it must be explicitly coded. - -@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 -for @samp{imul}) can be output only in the one operand form. Thus, -@samp{imul %ebx, %eax} does @emph{not} select the expanding multiply; -the expanding multiply would clobber the @samp{%edx} register, and this -would confuse @code{_GCC__} output. Use @samp{imul %ebx} to get the -64-bit product in @samp{%edx:%eax}. - -We have added a two operand form of @samp{imul} when the first operand -is an immediate mode expression and the second operand is a register. -This is just a shorthand, so that, multiplying @samp{%eax} by 69, for -example, can be done with @samp{imul $69, %eax} rather than @samp{imul -$69, %eax, %eax}. - -_fi__(_I80386__) -_if__(0) -@c pesch@cygnus.com: we ignore the following chapters, since internals are -@c changing rapidly. These may need to be moved to another -@c book anyhow, if we adopt the model of user/modifier -@c books. -@node Maintenance, Retargeting, _MACH_DEP__, Top -@chapter Maintaining the Assembler -[[this chapter is still being built]] - -@section Design -We had these goals, in descending priority: -@table @b -@item Accuracy. -For every program composed by a compiler, @code{_AS__} should emit -``correct'' code. This leaves some latitude in choosing addressing -modes, order of @code{relocation_info} structures in the object -file, @emph{etc}. - -@item Speed, for usual case. -By far the most common use of @code{_AS__} will be assembling compiler -emissions. - -@item Upward compatibility for existing assembler code. -Well @dots{} we don't support Vax bit fields but everything else -seems to be upward compatible. - -@item Readability. -The code should be maintainable with few surprises. (JF: ha!) - -@end table - -We assumed that disk I/O was slow and expensive while memory was -fast and access to memory was cheap. We expect the in-memory data -structures to be less than 10 times the size of the emitted object -file. (Contrast this with the C compiler where in-memory structures -might be 100 times object file size!) -This suggests: -@itemize @bullet -@item -Try to read the source file from disk only one time. For other -reasons, we keep large chunks of the source file in memory during -assembly so this is not a problem. Also the assembly algorithm -should only scan the source text once if the compiler composed the -text according to a few simple rules. -@item -Emit the object code bytes only once. Don't store values and then -backpatch later. -@item -Build the object file in memory and do direct writes to disk of -large buffers. -@end itemize - -RMS suggested a one-pass algorithm which seems to work well. By not -parsing text during a second pass considerable time is saved on -large programs (@emph{e.g.} the sort of C program @code{yacc} would -emit). - -It happened that the data structures needed to emit relocation -information to the object file were neatly subsumed into the data -structures that do backpatching of addresses after pass 1. - -Many of the functions began life as re-usable modules, loosely -connected. RMS changed this to gain speed. For example, input -parsing routines which used to work on pre-sanitized strings now -must parse raw data. Hence they have to import knowledge of the -assemblers' comment conventions @emph{etc}. - -@section Deprecated Feature(?)s -We have stopped supporting some features: -@itemize @bullet -@item -@code{.org} statements must have @b{defined} expressions. -@item -Vax Bit fields (@kbd{:} operator) are entirely unsupported. -@end itemize - -It might be a good idea to not support these features in a future release: -@itemize @bullet -@item -@kbd{#} should begin a comment, even in column 1. -@item -Why support the logical line & file concept any more? -@item -Subsections are a good candidate for flushing. -Depends on which compilers need them I guess. -@end itemize - -@section Bugs, Ideas, Further Work -Clearly the major improvement is DON'T USE A TEXT-READING -ASSEMBLER for the back end of a compiler. It is much faster to -interpret binary gobbledygook from a compiler's tables than to -ask the compiler to write out human-readable code just so the -assembler can parse it back to binary. - -Assuming you use @code{_AS__} for human written programs: here are -some ideas: -@itemize @bullet -@item -Document (here) @code{APP}. -@item -Take advantage of knowing no spaces except after opcode -to speed up @code{_AS__}. (Modify @code{app.c} to flush useless spaces: -only keep space/tabs at begin of line or between 2 -symbols.) -@item -Put pointers in this documentation to @file{a.out} documentation. -@item -Split the assembler into parts so it can gobble direct binary -from @emph{e.g.} @code{cc}. It is silly for@code{cc} to compose text -just so @code{_AS__} can parse it back to binary. -@item -Rewrite hash functions: I want a more modular, faster library. -@item -Clean up LOTS of code. -@item -Include all the non-@file{.c} files in the maintenance chapter. -@item -Document flonums. -@item -Implement flonum short literals. -@item -Change all talk of expression operands to expression quantities, -or perhaps to expression arguments. -@item -Implement pass 2. -@item -Whenever a @code{.text} or @code{.data} statement is seen, we close -of the current frag with an imaginary @code{.fill 0}. This is -because we only have one obstack for frags, and we can't grow new -frags for a new subsection, then go back to the old subsection and -append bytes to the old frag. All this nonsense goes away if we -give each subsection its own obstack. It makes code simpler in -about 10 places, but nobody has bothered to do it because C compiler -output rarely changes subsections (compared to ending frags with -relaxable addresses, which is common). -@end itemize - -@section Sources -@c The following files in the @file{_AS__} directory -@c are symbolic links to other files, of -@c the same name, in a different directory. -@c @itemize @bullet -@c @item -@c @file{atof_generic.c} -@c @item -@c @file{atof_vax.c} -@c @item -@c @file{flonum_const.c} -@c @item -@c @file{flonum_copy.c} -@c @item -@c @file{flonum_get.c} -@c @item -@c @file{flonum_multip.c} -@c @item -@c @file{flonum_normal.c} -@c @item -@c @file{flonum_print.c} -@c @end itemize - -Here is a list of the source files in the @file{_AS__} directory. - -@table @file -@item app.c -This contains the pre-processing phase, which deletes comments, -handles whitespace, etc. This was recently re-written, since app -used to be a separate program, but RMS wanted it to be inline. - -@item append.c -This is a subroutine to append a string to another string returning a -pointer just after the last @code{char} appended. (JF: All these -little routines should probably all be put in one file.) - -@item as.c -Here you will find the main program of the assembler @code{_AS__}. - -@item expr.c -This is a branch office of @file{read.c}. This understands -expressions, arguments. Inside @code{_AS__}, arguments are called -(expression) @emph{operands}. This is confusing, because we also talk -(elsewhere) about instruction @emph{operands}. Also, expression -operands are called @emph{quantities} explicitly to avoid confusion -with instruction operands. What a mess. - -@item frags.c -This implements the @b{frag} concept. Without frags, finding the -right size for branch instructions would be a lot harder. - -@item hash.c -This contains the symbol table, opcode table @emph{etc.} hashing -functions. - -@item hex_value.c -This is a table of values of digits, for use in atoi() type -functions. Could probably be flushed by using calls to strtol(), or -something similar. - -@item input-file.c -This contains Operating system dependent source file reading -routines. Since error messages often say where we are in reading -the source file, they live here too. Since @code{_AS__} is intended to -run under GNU and Unix only, this might be worth flushing. Anyway, -almost all C compilers support stdio. - -@item input-scrub.c -This deals with calling the pre-processor (if needed) and feeding the -chunks back to the rest of the assembler the right way. - -@item messages.c -This contains operating system independent parts of fatal and -warning message reporting. See @file{append.c} above. - -@item output-file.c -This contains operating system dependent functions that write an -object file for @code{_AS__}. See @file{input-file.c} above. - -@item read.c -This implements all the directives of @code{_AS__}. This also deals -with passing input lines to the machine dependent part of the -assembler. - -@item strstr.c -This is a C library function that isn't in most C libraries yet. -See @file{append.c} above. - -@item subsegs.c -This implements subsections. - -@item symbols.c -This implements symbols. - -@item write.c -This contains the code to perform relaxation, and to write out -the object file. It is mostly operating system independent, but -different OSes have different object file formats in any case. - -@item xmalloc.c -This implements @code{malloc()} or bust. See @file{append.c} above. - -@item xrealloc.c -This implements @code{realloc()} or bust. See @file{append.c} above. - -@item atof-generic.c -The following files were taken from a machine-independent subroutine -library for manipulating floating point numbers and very large -integers. - -@file{atof-generic.c} turns a string into a flonum internal format -floating-point number. - -@item flonum-const.c -This contains some potentially useful floating point numbers in -flonum format. - -@item flonum-copy.c -This copies a flonum. - -@item flonum-multip.c -This multiplies two flonums together. - -@item bignum-copy.c -This copies a bignum. - -@end table - -Here is a table of all the machine-specific files (this includes -both source and header files). Typically, there is a -@var{machine}.c file, a @var{machine}-opcode.h file, and an -atof-@var{machine}.c file. The @var{machine}-opcode.h file should -be identical to the one used by GDB (which uses it for disassembly.) - -@table @file - -@item atof-ieee.c -This contains code to turn a flonum into a ieee literal constant. -This is used by tye 680x0, 32x32, sparc, and i386 versions of @code{_AS__}. - -@item i386-opcode.h -This is the opcode-table for the i386 version of the assembler. - -@item i386.c -This contains all the code for the i386 version of the assembler. - -@item i386.h -This defines constants and macros used by the i386 version of the assembler. - -@item m-generic.h -generic 68020 header file. To be linked to m68k.h on a -non-sun3, non-hpux system. - -@item m-sun2.h -68010 header file for Sun2 workstations. Not well tested. To be linked -to m68k.h on a sun2. (See also @samp{-DSUN_ASM_SYNTAX} in the -@file{Makefile}.) - -@item m-sun3.h -68020 header file for Sun3 workstations. To be linked to m68k.h before -compiling on a Sun3 system. (See also @samp{-DSUN_ASM_SYNTAX} in the -@file{Makefile}.) - -@item m-hpux.h -68020 header file for a HPUX (system 5?) box. Which box, which -version of HPUX, etc? I don't know. - -@item m68k.h -A hard- or symbolic- link to one of @file{m-generic.h}, -@file{m-hpux.h} or @file{m-sun3.h} depending on which kind of -680x0 you are assembling for. (See also @samp{-DSUN_ASM_SYNTAX} in the -@file{Makefile}.) - -@item m68k-opcode.h -Opcode table for 68020. This is now a link to the opcode table -in the @code{GDB} source directory. - -@item m68k.c -All the mc680x0 code, in one huge, slow-to-compile file. - -@item ns32k.c -This contains the code for the ns32032/ns32532 version of the -assembler. - -@item ns32k-opcode.h -This contains the opcode table for the ns32032/ns32532 version -of the assembler. - -@item vax-inst.h -Vax specific file for describing Vax operands and other Vax-ish things. - -@item vax-opcode.h -Vax opcode table. - -@item vax.c -Vax specific parts of @code{_AS__}. Also includes the former files -@file{vax-ins-parse.c}, @file{vax-reg-parse.c} and @file{vip-op.c}. - -@item atof-vax.c -Turns a flonum into a Vax constant. - -@item vms.c -This file contains the special code needed to put out a VMS -style object file for the Vax. - -@end table - -Here is a list of the header files in the source directory. -(Warning: This section may not be very accurate. I didn't -write the header files; I just report them.) Also note that I -think many of these header files could be cleaned up or -eliminated. - -@table @file - -@item a.out.h -This describes the structures used to create the binary header data -inside the object file. Perhaps we should use the one in -@file{/usr/include}? - -@item as.h -This defines all the globally useful things, and pulls in _0__<stdio.h>_1__ -and _0__<assert.h>_1__. - -@item bignum.h -This defines macros useful for dealing with bignums. - -@item expr.h -Structure and macros for dealing with expression() - -@item flonum.h -This defines the structure for dealing with floating point -numbers. It #includes @file{bignum.h}. - -@item frags.h -This contains macro for appending a byte to the current frag. - -@item hash.h -Structures and function definitions for the hashing functions. - -@item input-file.h -Function headers for the input-file.c functions. - -@item md.h -structures and function headers for things defined in the -machine dependent part of the assembler. - -@item obstack.h -This is the GNU systemwide include file for manipulating obstacks. -Since nobody is running under real GNU yet, we include this file. - -@item read.h -Macros and function headers for reading in source files. - -@item struct-symbol.h -Structure definition and macros for dealing with the _AS__ -internal form of a symbol. - -@item subsegs.h -structure definition for dealing with the numbered subsections -of the text and data sections. - -@item symbols.h -Macros and function headers for dealing with symbols. - -@item write.h -Structure for doing section fixups. -@end table - -@comment ~subsection Test Directory -@comment (Note: The test directory seems to have disappeared somewhere -@comment along the line. If you want it, you'll probably have to find a -@comment REALLY OLD dump tape~dots{}) -@comment -@comment The ~file{test/} directory is used for regression testing. -@comment After you modify ~@code{_AS__}, you can get a quick go/nogo -@comment confidence test by running the new ~@code{_AS__} over the source -@comment files in this directory. You use a shell script ~file{test/do}. -@comment -@comment The tests in this suite are evolving. They are not comprehensive. -@comment They have, however, caught hundreds of bugs early in the debugging -@comment cycle of ~@code{_AS__}. Most test statements in this suite were naturally -@comment selected: they were used to demonstrate actual ~@code{_AS__} bugs rather -@comment than being written ~i{a prioi}. -@comment -@comment Another testing suggestion: over 30 bugs have been found simply by -@comment running examples from this manual through ~@code{_AS__}. -@comment Some examples in this manual are selected -@comment to distinguish boundary conditions; they are good for testing ~@code{_AS__}. -@comment -@comment ~subsubsection Regression Testing -@comment Each regression test involves assembling a file and comparing the -@comment actual output of ~@code{_AS__} to ``known good'' output files. Both -@comment the object file and the error/warning message file (stderr) are -@comment inspected. Optionally the ~@code{_AS__} exit status may be checked. -@comment Discrepencies are reported. Each discrepency means either that -@comment you broke some part of ~@code{_AS__} or that the ``known good'' files -@comment are now out of date and should be changed to reflect the new -@comment definition of ``good''. -@comment -@comment Each regression test lives in its own directory, in a tree -@comment rooted in the directory ~file{test/}. Each such directory -@comment has a name ending in ~file{.ret}, where `ret' stands for -@comment REgression Test. The ~file{.ret} ending allows ~code{find -@comment (1)} to find all regression tests in the tree, without -@comment needing to list them explicitly. -@comment -@comment Any ~file{.ret} directory must contain a file called -@comment ~file{input} which is the source file to assemble. During -@comment testing an object file ~file{output} is created, as well as -@comment a file ~file{stdouterr} which contains the output to both -@comment stderr and stderr. If there is a file ~file{output.good} in -@comment the directory, and if ~file{output} contains exactly the -@comment same data as ~file{output.good}, the file ~file{output} is -@comment deleted. Likewise ~file{stdouterr} is removed if it exactly -@comment matches a file ~file{stdouterr.good}. If file -@comment ~file{status.good} is present, containing a decimal number -@comment before a newline, the exit status of ~@code{_AS__} is compared -@comment to this number. If the status numbers are not equal, a file -@comment ~file{status} is written to the directory, containing the -@comment actual status as a decimal number followed by newline. -@comment -@comment Should any of the ~file{*.good} files fail to match their corresponding -@comment actual files, this is noted by a 1-line message on the screen during -@comment the regression test, and you can use ~@code{find (1)} to find any -@comment files named ~file{status}, ~file {output} or ~file{stdouterr}. -@comment -@node Retargeting, Copying, Maintenance, Top -@chapter Teaching the Assembler about a New Machine - -This chapter describes the steps required in order to make the -assembler work with another machine's assembly language. This -chapter is not complete, and only describes the steps in the -broadest terms. You should look at the source for the -currently supported machine in order to discover some of the -details that aren't mentioned here. - -You should create a new file called @file{@var{machine}.c}, and -add the appropriate lines to the file @file{Makefile} so that -you can compile your new version of the assembler. This should -be straighforward; simply add lines similar to the ones there -for the four current versions of the assembler. - -If you want to be compatible with GDB, (and the current -machine-dependent versions of the assembler), you should create -a file called @file{@var{machine}-opcode.h} which should -contain all the information about the names of the machine -instructions, their opcodes, and what addressing modes they -support. If you do this right, the assembler and GDB can share -this file, and you'll only have to write it once. Note that -while you're writing @code{_AS__}, you may want to use an -independent program (if you have access to one), to make sure -that @code{_AS__} is emitting the correct bytes. Since @code{_AS__} -and @code{GDB} share the opcode table, an incorrect opcode -table entry may make invalid bytes look OK when you disassemble -them with @code{GDB}. - -@section Functions You will Have to Write - -Your file @file{@var{machine}.c} should contain definitions for -the following functions and variables. It will need to include -some header files in order to use some of the structures -defined in the machine-independent part of the assembler. The -needed header files are mentioned in the descriptions of the -functions that will need them. - -@table @code - -@item long omagic; -This long integer holds the value to place at the beginning of -the @file{a.out} file. It is usually @samp{OMAGIC}, except on -machines that store additional information in the magic-number. - -@item char comment_chars[]; -This character array holds the values of the characters that -start a comment anywhere in a line. Comments are stripped off -automatically by the machine independent part of the -assembler. Note that the @samp{/*} will always start a -comment, and that only @samp{*/} will end a comment started by -@samp{*/}. - -@item char line_comment_chars[]; -This character array holds the values of the chars that start a -comment only if they are the first (non-whitespace) character -on a line. If the character @samp{#} does not appear in this -list, you may get unexpected results. (Various -machine-independent parts of the assembler treat the comments -@samp{#APP} and @samp{#NO_APP} specially, and assume that lines -that start with @samp{#} are comments.) - -@item char EXP_CHARS[]; -This character array holds the letters that can separate the -mantissa and the exponent of a floating point number. Typical -values are @samp{e} and @samp{E}. - -@item char FLT_CHARS[]; -This character array holds the letters that--when they appear -immediately after a leading zero--indicate that a number is a -floating-point number. (Sort of how 0x indicates that a -hexadecimal number follows.) - -@item pseudo_typeS md_pseudo_table[]; -(@var{pseudo_typeS} is defined in @file{md.h}) -This array contains a list of the machine_dependent directives -the assembler must support. It contains the name of each -pseudo op (Without the leading @samp{.}), a pointer to a -function to be called when that directive is encountered, and -an integer argument to be passed to that function. - -@item void md_begin(void) -This function is called as part of the assembler's -initialization. It should do any initialization required by -any of your other routines. - -@item int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR) -This routine is called once for each option on the command line -that the machine-independent part of @code{_AS__} does not -understand. This function should return non-zero if the option -pointed to by @var{optionPTR} is a valid option. If it is not -a valid option, this routine should return zero. The variables -@var{argcPTR} and @var{argvPTR} are provided in case the option -requires a filename or something similar as an argument. If -the option is multi-character, @var{optionPTR} should be -advanced past the end of the option, otherwise every letter in -the option will be treated as a separate single-character -option. - -@item void md_assemble(char *string) -This routine is called for every machine-dependent -non-directive line in the source file. It does all the real -work involved in reading the opcode, parsing the operands, -etc. @var{string} is a pointer to a null-terminated string, -that comprises the input line, with all excess whitespace and -comments removed. - -@item void md_number_to_chars(char *outputPTR,long value,int nbytes) -This routine is called to turn a C long int, short int, or char -into the series of bytes that represents that number on the -target machine. @var{outputPTR} points to an array where the -result should be stored; @var{value} is the value to store; and -@var{nbytes} is the number of bytes in 'value' that should be -stored. - -@item void md_number_to_imm(char *outputPTR,long value,int nbytes) -This routine is called to turn a C long int, short int, or char -into the series of bytes that represent an immediate value on -the target machine. It is identical to the function @code{md_number_to_chars}, -except on NS32K machines.@refill - -@item void md_number_to_disp(char *outputPTR,long value,int nbytes) -This routine is called to turn a C long int, short int, or char -into the series of bytes that represent an displacement value on -the target machine. It is identical to the function @code{md_number_to_chars}, -except on NS32K machines.@refill - -@item void md_number_to_field(char *outputPTR,long value,int nbytes) -This routine is identical to @code{md_number_to_chars}, -except on NS32K machines. - -@item void md_ri_to_chars(struct relocation_info *riPTR,ri) -(@code{struct relocation_info} is defined in @file{a.out.h}) -This routine emits the relocation info in @var{ri} -in the appropriate bit-pattern for the target machine. -The result should be stored in the location pointed -to by @var{riPTR}. This routine may be a no-op unless you are -attempting to do cross-assembly. - -@item char *md_atof(char type,char *outputPTR,int *sizePTR) -This routine turns a series of digits into the appropriate -internal representation for a floating-point number. -@var{type} is a character from @var{FLT_CHARS[]} that describes -what kind of floating point number is wanted; @var{outputPTR} -is a pointer to an array that the result should be stored in; -and @var{sizePTR} is a pointer to an integer where the size (in -bytes) of the result should be stored. This routine should -return an error message, or an empty string (not (char *)0) for -success. - -@item int md_short_jump_size; -This variable holds the (maximum) size in bytes of a short (16 -bit or so) jump created by @code{md_create_short_jump()}. This -variable is used as part of the broken-word feature, and isn't -needed if the assembler is compiled with -@samp{-DWORKING_DOT_WORD}. - -@item int md_long_jump_size; -This variable holds the (maximum) size in bytes of a long (32 -bit or so) jump created by @code{md_create_long_jump()}. This -variable is used as part of the broken-word feature, and isn't -needed if the assembler is compiled with -@samp{-DWORKING_DOT_WORD}. - -@item void md_create_short_jump(char *resultPTR,long from_addr, -@code{long to_addr,fragS *frag,symbolS *to_symbol)} -This function emits a jump from @var{from_addr} to @var{to_addr} in -the array of bytes pointed to by @var{resultPTR}. If this creates a -type of jump that must be relocated, this function should call -@code{fix_new()} with @var{frag} and @var{to_symbol}. The jump -emitted by this function may be smaller than @var{md_short_jump_size}, -but it must never create a larger one. -(If it creates a smaller jump, the extra bytes of memory will not be -used.) This function is used as part of the broken-word feature, -and isn't needed if the assembler is compiled with -@samp{-DWORKING_DOT_WORD}.@refill - -@item void md_create_long_jump(char *ptr,long from_addr, -@code{long to_addr,fragS *frag,symbolS *to_symbol)} -This function is similar to the previous function, -@code{md_create_short_jump()}, except that it creates a long -jump instead of a short one. This function is used as part of -the broken-word feature, and isn't needed if the assembler is -compiled with @samp{-DWORKING_DOT_WORD}. - -@item int md_estimate_size_before_relax(fragS *fragPTR,int segment_type) -This function does the initial setting up for relaxation. This -includes forcing references to still-undefined symbols to the -appropriate addressing modes. - -@item relax_typeS md_relax_table[]; -(relax_typeS is defined in md.h) -This array describes the various machine dependent states a -frag may be in before relaxation. You will need one group of -entries for each type of addressing mode you intend to relax. - -@item void md_convert_frag(fragS *fragPTR) -(@var{fragS} is defined in @file{as.h}) -This routine does the required cleanup after relaxation. -Relaxation has changed the type of the frag to a type that can -reach its destination. This function should adjust the opcode -of the frag to use the appropriate addressing mode. -@var{fragPTR} points to the frag to clean up. - -@item void md_end(void) -This function is called just before the assembler exits. It -need not free up memory unless the operating system doesn't do -it automatically on exit. (In which case you'll also have to -track down all the other places where the assembler allocates -space but never frees it.) - -@end table - -@section External Variables You will Need to Use - -You will need to refer to or change the following external variables -from within the machine-dependent part of the assembler. - -@table @code -@item extern char flagseen[]; -This array holds non-zero values in locations corresponding to -the options that were on the command line. Thus, if the -assembler was called with @samp{-W}, @var{flagseen['W']} would -be non-zero. - -@item extern fragS *frag_now; -This pointer points to the current frag--the frag that bytes -are currently being added to. If nothing else, you will need -to pass it as an argument to various machine-independent -functions. It is maintained automatically by the -frag-manipulating functions; you should never have to change it -yourself. - -@item extern LITTLENUM_TYPE generic_bignum[]; -(@var{LITTLENUM_TYPE} is defined in @file{bignum.h}. -This is where @dfn{bignums}--numbers larger than 32 bits--are -returned when they are encountered in an expression. You will -need to use this if you need to implement directives (or -anything else) that must deal with these large numbers. -@code{Bignums} are of @code{segT} @code{SEG_BIG} (defined in -@file{as.h}, and have a positive @code{X_add_number}. The -@code{X_add_number} of a @code{bignum} is the number of -@code{LITTLENUMS} in @var{generic_bignum} that the number takes -up. - -@item extern FLONUM_TYPE generic_floating_point_number; -(@var{FLONUM_TYPE} is defined in @file{flonum.h}. -The is where @dfn{flonums}--floating-point numbers within -expressions--are returned. @code{Flonums} are of @code{segT} -@code{SEG_BIG}, and have a negative @code{X_add_number}. -@code{Flonums} are returned in a generic format. You will have -to write a routine to turn this generic format into the -appropriate floating-point format for your machine. - -@item extern int need_pass_2; -If this variable is non-zero, the assembler has encountered an -expression that cannot be assembled in a single pass. Since -the second pass isn't implemented, this flag means that the -assembler is punting, and is only looking for additional syntax -errors. (Or something like that.) - -@item extern segT now_seg; -This variable holds the value of the section the assembler is -currently assembling into. - -@end table - -@section External functions will you need - -You will find the following external functions useful (or -indispensable) when you're writing the machine-dependent part -of the assembler. - -@table @code - -@item char *frag_more(int bytes) -This function allocates @var{bytes} more bytes in the current -frag (or starts a new frag, if it can't expand the current frag -any more.) for you to store some object-file bytes in. It -returns a pointer to the bytes, ready for you to store data in. - -@item void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel) -This function stores a relocation fixup to be acted on later. -@var{frag} points to the frag the relocation belongs in; -@var{where} is the location within the frag where the relocation begins; -@var{size} is the size of the relocation, and is usually 1 (a single byte), - 2 (sixteen bits), or 4 (a longword). -The value @var{add_symbol} @minus{} @var{sub_symbol} + @var{offset}, is added to the byte(s) -at _0__@var{frag->literal[where]}_1__. If @var{pcrel} is non-zero, the address of the -location is subtracted from the result. A relocation entry is also added -to the @file{a.out} file. @var{add_symbol}, @var{sub_symbol}, and/or -@var{offset} may be NULL.@refill - -@item char *frag_var(relax_stateT type, int max_chars, int var, -@code{relax_substateT subtype, symbolS *symbol, char *opcode)} -This function creates a machine-dependent frag of type @var{type} -(usually @code{rs_machine_dependent}). -@var{max_chars} is the maximum size in bytes that the frag may grow by; -@var{var} is the current size of the variable end of the frag; -@var{subtype} is the sub-type of the frag. The sub-type is used to index into -@var{md_relax_table[]} during @code{relaxation}. -@var{symbol} is the symbol whose value should be used to when relax-ing this frag. -@var{opcode} points into a byte whose value may have to be modified if the -addressing mode used by this frag changes. It typically points into the -@var{fr_literal[]} of the previous frag, and is used to point to a location -that @code{md_convert_frag()}, may have to change.@refill - -@item void frag_wane(fragS *fragPTR) -This function is useful from within @code{md_convert_frag}. It -changes a frag to type rs_fill, and sets the variable-sized -piece of the frag to zero. The frag will never change in size -again. - -@item segT expression(expressionS *retval) -(@var{segT} is defined in @file{as.h}; @var{expressionS} is defined in @file{expr.h}) -This function parses the string pointed to by the external char -pointer @var{input_line_pointer}, and returns the section-type -of the expression. It also stores the results in the -@var{expressionS} pointed to by @var{retval}. -@var{input_line_pointer} is advanced to point past the end of -the expression. (@var{input_line_pointer} is used by other -parts of the assembler. If you modify it, be sure to restore -it to its original value.) - -@item as_warn(char *message,@dots{}) -If warning messages are disabled, this function does nothing. -Otherwise, it prints out the current file name, and the current -line number, then uses @code{fprintf} to print the -@var{message} and any arguments it was passed. - -@item as_bad(char *message,@dots{}) -This function should be called when @code{_AS__} encounters -conditions that are bad enough that @code{_AS__} should not -produce an object file, but should continue reading input and -printing warning and bad error messages. - -@item as_fatal(char *message,@dots{}) -This function prints out the current file name and line number, -prints the word @samp{FATAL:}, then uses @code{fprintf} to -print the @var{message} and any arguments it was passed. Then -the assembler exits. This function should only be used for -serious, unrecoverable errors. - -@item void float_const(int float_type) -This function reads floating-point constants from the current -input line, and calls @code{md_atof} to assemble them. It is -useful as the function to call for the directives -@samp{.single}, @samp{.double}, @samp{.float}, etc. -@var{float_type} must be a character from @var{FLT_CHARS}. - -@item void demand_empty_rest_of_line(void); -This function can be used by machine-dependent directives to -make sure the rest of the input line is empty. It prints a -warning message if there are additional characters on the line. - -@item long int get_absolute_expression(void) -This function can be used by machine-dependent directives to -read an absolute number from the current input line. It -returns the result. If it isn't given an absolute expression, -it prints a warning message and returns zero. - -@end table - - -@section The concept of Frags - -This assembler works to optimize the size of certain addressing -modes. (e.g. branch instructions) This means the size of many -pieces of object code cannot be determined until after assembly -is finished. (This means that the addresses of symbols cannot be -determined until assembly is finished.) In order to do this, -@code{_AS__} stores the output bytes as @dfn{frags}. - -Here is the definition of a frag (from @file{as.h}) -@smallexample -struct frag -@{ - long int fr_fix; - long int fr_var; - relax_stateT fr_type; - relax_substateT fr_substate; - unsigned long fr_address; - long int fr_offset; - struct symbol *fr_symbol; - char *fr_opcode; - struct frag *fr_next; - char fr_literal[]; -@} -@end smallexample - -@table @var -@item fr_fix -is the size of the fixed-size piece of the frag. - -@item fr_var -is the maximum (?) size of the variable-sized piece of the frag. - -@item fr_type -is the type of the frag. -Current types are: -rs_fill -rs_align -rs_org -rs_machine_dependent - -@item fr_substate -This stores the type of machine-dependent frag this is. (what -kind of addressing mode is being used, and what size is being -tried/will fit/etc. - -@item fr_address -@var{fr_address} is only valid after relaxation is finished. -Before relaxation, the only way to store an address is (pointer -to frag containing the address) plus (offset into the frag). - -@item fr_offset -This contains a number, whose meaning depends on the type of -the frag. -for machine_dependent frags, this contains the offset from -fr_symbol that the frag wants to go to. Thus, for branch -instructions it is usually zero. (unless the instruction was -@samp{jba foo+12} or something like that.) - -@item fr_symbol -for machine_dependent frags, this points to the symbol the frag -needs to reach. - -@item fr_opcode -This points to the location in the frag (or in a previous frag) -of the opcode for the instruction that caused this to be a frag. -@var{fr_opcode} is needed if the actual opcode must be changed -in order to use a different form of the addressing mode. -(For example, if a conditional branch only comes in size tiny, -a large-size branch could be implemented by reversing the sense -of the test, and turning it into a tiny branch over a large jump. -This would require changing the opcode.) - -@var{fr_literal} is a variable-size array that contains the -actual object bytes. A frag consists of a fixed size piece of -object data, (which may be zero bytes long), followed by a -piece of object data whose size may not have been determined -yet. Other information includes the type of the frag (which -controls how it is relaxed), - -@item fr_next -This is the next frag in the singly-linked list. This is -usually only needed by the machine-independent part of -@code{_AS__}. - -@end table -_fi__(0) - -@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 -Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. -675 Mass Ave, Cambridge, MA 02139, USA - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@unnumberedsec Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software---to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - -@iftex -@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -@end iftex -@ifinfo -@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -@end ifinfo - -@enumerate -@item -This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The ``Program'', below, -refers to any such program or work, and a ``work based on the Program'' -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term ``modification''.) Each licensee is addressed as ``you''. - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - -@item -You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - -@item -You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - -@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. - -@item -You must cause any work that you distribute or publish, that in -whole or in part contains or is derived from the Program or any -part thereof, to be licensed as a whole at no charge to all third -parties under the terms of this License. - -@item -If the modified program normally reads commands interactively -when run, you must cause it, when started running for such -interactive use in the most ordinary way, to print or display an -announcement including an appropriate copyright notice and a -notice that there is no warranty (or else, saying that you provide -a warranty) and that users may redistribute the program under -these conditions, and telling the user how to view a copy of this -License. (Exception: if the Program itself is interactive but -does not normally print such an announcement, your work based on -the Program is not required to print an announcement.) -@end enumerate - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - -@item -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: - -@enumerate a -@item -Accompany it with the complete corresponding machine-readable -source code, which must be distributed under the terms of Sections -1 and 2 above on a medium customarily used for software interchange; or, - -@item -Accompany it with a written offer, valid for at least three -years, to give any third party, for a charge no more than your -cost of physically performing source distribution, a complete -machine-readable copy of the corresponding source code, to be -distributed under the terms of Sections 1 and 2 above on a medium -customarily used for software interchange; or, - -@item -Accompany it with the information you received as to the offer -to distribute corresponding source code. (This alternative is -allowed only for noncommercial distribution and only if you -received the program in object code or executable form with such -an offer, in accord with Subsection b above.) -@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 -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - -@item -You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - -@item -You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - -@item -Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - -@item -If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - -@item -If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - -@item -The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and ``any -later version'', you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - -@item -If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - -@iftex -@heading NO WARRANTY -@end iftex -@ifinfo -@center NO WARRANTY -@end ifinfo - -@item -BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - -@item -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. -@end enumerate - -@iftex -@heading END OF TERMS AND CONDITIONS -@end iftex -@ifinfo -@center END OF TERMS AND CONDITIONS -@end ifinfo - -@page -@unnumberedsec Applying These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and an idea of what it does.} -Copyright (C) 19@var{yy} @var{name of author} - -This program is free software; you can redistribute it and/or -modify it under the terms of the GNU General Public License -as published by the Free Software Foundation; either version 2 -of the License, or (at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program; if not, write to the -Free Software Foundation, Inc., 675 Mass Ave, -Cambridge, MA 02139, USA. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - -@smallexample -Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} -Gnomovision comes with ABSOLUTELY NO WARRANTY; for details -type `show w'. This is free software, and you are welcome -to redistribute it under certain conditions; type `show c' -for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, the -commands you use may be called something other than @samp{show w} and -@samp{show c}; they could even be mouse-clicks or menu items---whatever -suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a ``copyright disclaimer'' for the program, if -necessary. Here is a sample; alter the names: - -@smallexample -Yoyodyne, Inc., hereby disclaims all copyright interest in -the program `Gnomovision' (which makes passes at compilers) -written by James Hacker. - -@var{signature of Ty Coon}, 1 April 1989 -Ty Coon, President of Vice -@end smallexample - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. - -@node Index, , Copying, Top -@unnumbered Index - -@printindex cp - -@summarycontents -@contents -@bye |