diff options
Diffstat (limited to 'gnu/usr.bin/as')
| -rw-r--r-- | gnu/usr.bin/as/doc/Makefile | 188 | ||||
| -rw-r--r-- | gnu/usr.bin/as/doc/as-all.texinfo | 4995 |
2 files changed, 4997 insertions, 186 deletions
diff --git a/gnu/usr.bin/as/doc/Makefile b/gnu/usr.bin/as/doc/Makefile index f2c319f..77a0cf2 100644 --- a/gnu/usr.bin/as/doc/Makefile +++ b/gnu/usr.bin/as/doc/Makefile @@ -1,187 +1,3 @@ -# This file was generated automatically by configure. Do not edit. -host_alias = i386 -host_cpu = i386 -host_vendor = unknown -host_os = scosysv322 -target_alias = i386 -target_cpu = i386 -target_vendor = unknown -target_os = scosysv322 -target_makefile_frag = -host_makefile_frag = -site_makefile_frag = -links = -VPATH = . -ALL=all.internal -# Makefile for GNU Assembler documentation -# - see pretex.m4 for discussion of preprocessor definitions -# Copyright (C) 1987-1992 Free Software Foundation, Inc. - -#This file is part of GNU GAS. - -#GNU GAS 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, or (at your option) -#any later version. - -#GNU GAS 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 GNU GAS; see the file COPYING. If not, write to -#the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. - -# The targets for external use include: -# all, doc, proto, install, uninstall, includes, TAGS, -# clean, cleanconfig, realclean, stage1, stage2, stage3, stage4. - -# Variables that exist for you to override. -# See below for how to change them for certain systems. - -srcdir = . - -prefix = /usr/local - -bindir = $(prefix)/bin -datadir = $(prefix)/lib -libdir = $(prefix)/lib -mandir = $(datadir)/man -man1dir = $(mandir)/man1 -man2dir = $(mandir)/man2 -man3dir = $(mandir)/man3 -man4dir = $(mandir)/man4 -man5dir = $(mandir)/man5 -man6dir = $(mandir)/man6 -man7dir = $(mandir)/man7 -man8dir = $(mandir)/man8 -man9dir = $(mandir)/man9 -infodir = $(datadir)/info -includedir = $(prefix)/include -docdir = $(datadir)/doc - -SHELL = /bin/sh - -INSTALL = install -c -INSTALL_PROGRAM = $(INSTALL) -INSTALL_DATA = $(INSTALL) - -AR = ar -AR_FLAGS = qv -BISON = bison -MAKEINFO = makeinfo -RANLIB = ranlib - -# What version of the manual you want (see *.m4); "all" includes everything -CONFIG=all - -# Sun/Berkeley m4 doesn't have all the things we need; use GNU or sV -M4=gm4 -#M4=/usr/5bin/m4 - -# Directory for gas source -srcdir = . - -# Where to find texinfo.tex to format docn with TeX -TEXIDIR = $(srcdir)/../texinfo/fsf - -#### host, target, and site specific Makefile frags come in here. -## - -all: -clean: -install: - $(INSTALL_DATA) $(srcdir)/as.1 $(man1dir)/as.1 - -info: as.info - -as.info: as-${CONFIG}.texinfo - makeinfo -o as.info as-${CONFIG}.texinfo - -install-info: as.info - [ -d $(infodir) ] || mkdir $(infodir) - for i in as.info* ; do \ - $(INSTALL_DATA) $$i $(infodir)/$$i ; \ - done - -as.dvi: as-${CONFIG}.texinfo - TEXINPUTS=${TEXIDIR}:.:$$TEXINPUTS tex as-${CONFIG}.texinfo - texindex as-${CONFIG}.?? - TEXINPUTS=${TEXIDIR}:.:$$TEXINPUTS tex as-${CONFIG}.texinfo - mv as-${CONFIG}.dvi as.dvi - rm as-${CONFIG}.?? as-${CONFIG}.??? - -# ROFF doc targets as.ms, as.mm, as.me -# (we don't use a variable because we don't trust all makes to handle -# a var in the target name right). -# roff output (-ms) -as.ms: as-${CONFIG}.texinfo - sed -e '/\\input texinfo/d' \ - -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ - -e 's/{.*,,/{/' \ - as-${CONFIG}.texinfo | \ - texi2roff -ms >as.ms - -# roff output (-mm) -as.mm: as-${CONFIG}.texinfo - sed -e '/\\input texinfo/d' \ - -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ - -e 's/{.*,,/{/' \ - -e '/@noindent/d' \ - as-${CONFIG}.texinfo | \ - texi2roff -mm | \ - sed -e 's/---/\\(em/g' \ - >as.mm - -# roff output (-me) -as.me: as-${CONFIG}.texinfo - sed -e '/\\input texinfo/d' \ - -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ - -e 's/{.*,,/{/' \ - as-${CONFIG}.texinfo | \ - texi2roff -me >as.me - - - -as-all.texinfo: as.texinfo pretex.m4 none.m4 all.m4 - ${M4} $(srcdir)/pretex.m4 $(srcdir)/none.m4 $(srcdir)/all.m4 $(srcdir)/as.texinfo >as-all.texinfo - -as-a29k.texinfo: as.texinfo pretex.m4 none.m4 a29k.m4 - ${M4} pretex.m4 none.m4 a29k.m4 as.texinfo >as-a29k.texinfo - -as-a29k-coff.texinfo: as.texinfo pretex.m4 none.m4 a29k-coff.m4 - ${M4} pretex.m4 none.m4 a29k-coff.m4 as.texinfo >as-a29k-coff.texinfo - -as-gen.texinfo: as.texinfo pretex.m4 none.m4 gen.m4 - ${M4} pretex.m4 none.m4 gen.m4 as.texinfo >as-gen.texinfo - -as-h8.texinfo: as.texinfo pretex.m4 none.m4 h8.m4 - ${M4} pretex.m4 none.m4 h8.m4 as.texinfo >as-h8.texinfo - -as-i80386.texinfo: as.texinfo pretex.m4 none.m4 i80386.m4 - ${M4} pretex.m4 none.m4 i80386.m4 as.texinfo >as-i80386.texinfo - -as-i960.texinfo: as.texinfo pretex.m4 none.m4 i960.m4 - ${M4} pretex.m4 none.m4 i960.m4 as.texinfo >as-i960.texinfo - -as-m680x0.texinfo: as.texinfo pretex.m4 none.m4 m680x0.m4 - ${M4} pretex.m4 none.m4 m680x0.m4 as.texinfo >as-m680x0.texinfo - -as-sparc.texinfo: as.texinfo pretex.m4 none.m4 sparc.m4 - ${M4} pretex.m4 none.m4 sparc.m4 as.texinfo >as-sparc.texinfo - -as-vax.texinfo: as.texinfo pretex.m4 none.m4 vax.m4 - ${M4} pretex.m4 none.m4 vax.m4 as.texinfo >as-vax.texinfo - -as-vintage.texinfo: as.texinfo pretex.m4 none.m4 vintage.m4 - ${M4} pretex.m4 none.m4 vintage.m4 as.texinfo >as-vintage.texinfo - -clean-info: - rm -f as-${CONFIG}.* as.dvi as.info* - -force: - -Makefile: $(srcdir)/Makefile.in $(host_makefile_frag) $(target_makefile_frag) - $(SHELL) ./config.status +INFO = as-all +.include <bsd.info.mk> diff --git a/gnu/usr.bin/as/doc/as-all.texinfo b/gnu/usr.bin/as/doc/as-all.texinfo new file mode 100644 index 0000000..99076ae --- /dev/null +++ b/gnu/usr.bin/as/doc/as-all.texinfo @@ -0,0 +1,4995 @@ + + +\input texinfo @c -*-Texinfo-*- +@c Copyright (c) 1991 1992 Free Software Foundation, Inc. +@c %**start of header +@setfilename as.info +@settitle Using as +@setchapternewpage odd +@c @smallbook +@c @cropmarks +@c %**end of header + +@finalout +@syncodeindex ky cp + +@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 +@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}. +@end ifinfo +@menu +* Overview:: Overview +* Invoking:: Command-Line Options +* Syntax:: Syntax +* Sections:: Sections and Relocation +* Symbols:: Symbols +* Expressions:: Expressions +* Pseudo Ops:: Assembler Directives +* Machine Dependent:: 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}. +@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 ] +@c am29k has no machine-dependent assembler options +@c h8/300 has no machine-dependent assembler options +@c see md_parse_option in i960.c + [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ] + [ -b ] [ -norelax ] + [ -l ] [ -mc68000 | -mc68010 | -mc68020 ] + [ -- | @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 +Issue warnings when difference tables altered for long displacements. + +@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 + +@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC +(When configured for Intel 960). +Specify which variant of the 960 architecture is the target. + +@item -b +(When configured for Intel 960). +Add code to collect statistics about branches taken. + +@item -norelax +(When configured for Intel 960). +Do not alter compare-and-branch instructions for long displacements; +error if necessary. + +@item -l +(When configured for Motorola 68000). +Shorten references to undefined symbols, to one word instead of two + +@item -mc68000 | -mc68010 | -mc68020 +(When configured for Motorola 68000). +Specify what processor in the 68000 family is the target (default 68020) + +@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}. + +This manual also describes some of the machine-dependent features of +various flavors of the assembler. +@refill + +@cindex machine instructions (not covered) +On the other hand, this manual is @emph{not} intended as an introduction +to programming in assembly language---let alone programming in general! +In a similar vein, we make no attempt to introduce the machine +architecture; we do @emph{not} describe the instruction set, standard +mnemonics, registers or addressing modes that are standard to a +particular architecture. +You may want to consult the manufacturer's +machine architecture manual for this information. + + +@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 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 + +@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. +Any exceptions are documented explicitly (@pxref{Machine Dependent}). +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. + +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}. + +@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 +(@pxref{Ln,,@code{.ln}}) +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{Machine Dependent}, for options specific +to particular machine architectures. + +@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 + +@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. + +@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. + +When @code{as} is configured for COFF output, +this option is only useful if you use sections named @samp{.text} and +@samp{.data}. + +@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 +assembler, except that @code{as} does not assemble Vax bit-fields. + +@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 +@samp{#} on the Vax; +@samp{#} on the i960; +@samp{|} on the 680x0; +@samp{;} for the AMD 29K family; +@samp{;} for the machine specific family; +@pxref{Machine Dependent}. @refill +@c FIXME: fill in SPARC line comment char + +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. + +@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 +the two characters @samp{_.} +On most machines, you can also use @code{$} in symbol names; exceptions +are noted in @ref{Machine Dependent}. +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 +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{Machine Dependent}.) 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. + +@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. +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 + +@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 +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 +@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. + +@node Flonums, , Bignums, Numbers +@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. +@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 +On the AMD 29K and H8/300 architectures, the letter must be: +One of the letters @samp{DFPRSX} (in upper or lower case). +On the Intel 960 architecture, the letter must be: +One of the letters @samp{DFT} (in upper or lower case). +@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}. + + +@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. +For the H8/300, @code{as} pads sections if needed to ensure they end +on a word (sixteen bit) boundary. + +@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. + +When it generates COFF output, +@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. + +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 + +@cindex named sections +@cindex sections, named +@item named sections +@cindex text section +@cindex data section +@item text section +@itemx data section +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. +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. + +@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. +The example uses the traditional section names @samp{.text} and @samp{.data}. +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 +Assembled bytes +conventionally +fall into two sections: text and data. +You may have separate groups of +data in named sections +that you want to end up near to each other in the object +file, even though they are not contiguous in the assembler source. +@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. + +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}.) + +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. +When generating COFF output, you +can also use an extra subsection +argument with arbitrary named sections: @samp{.section @var{name}, +@var{expression}}. +@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 +@samp{_.} +(On most machines, you can also use @code{$} in symbol names; exceptions +are noted in @ref{Machine Dependent}.) +That character may be followed by any string of digits, letters, +dollar signs (unless otherwise noted in @ref{Machine Dependent}), +and underscores. +Case of letters is significant: +@code{foo} is a different symbol name than @code{Foo}. + +For the AMD 29K family, @samp{?} is also allowed in the +body of a symbol name, though not at its beginning. + +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 +@samp{.block 4}. + +@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 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 +* a.out Symbols:: Symbol Attributes: @code{a.out} +* COFF Symbols:: Symbol Attributes for 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. + +@node Symbol Type, a.out Symbols, Symbol Value, Symbol Attributes +@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. + +@node a.out Symbols, COFF Symbols, Symbol Type, Symbol Attributes +@subsection Symbol Attributes: @code{a.out} + +@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}. + +@node COFF Symbols, , a.out Symbols, Symbol Attributes +@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. + +@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 < +@itemx << +@dfn{Shift Left}. Same as the C operator @samp{<<} + +@item > +@itemx >> +@dfn{Shift Right}. Same as the C operator @samp{>>} +@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, Machine Dependent, 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. + +@menu +* Abort:: @code{.abort} +* coff-ABORT:: @code{.ABORT} +* 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}} +* Def:: @code{.def @var{name}} +* Desc:: @code{.desc @var{symbol}, @var{abs-expression}} +* Dim:: @code{.dim} +* Double:: @code{.double @var{flonums}} +* Eject:: @code{.eject} +* Else:: @code{.else} +* Endef:: @code{.endef} +* Endif:: @code{.endif} +* Equ:: @code{.equ @var{symbol}, @var{expression}} +* Extern:: @code{.extern} +* File:: @code{.file @var{string}} +* 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} +* Line:: @code{.line @var{line-number}} +* 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}"} +* Scl:: @code{.scl @var{class}} +* Section:: @code{.section @var{name}, @var{subsection}} +* Set:: @code{.set @var{symbol}, @var{expression}} +* Short:: @code{.short @var{expressions}} +* Single:: @code{.single @var{flonums}} +* Size:: @code{.size} +* Space:: @code{.space @var{size} , @var{fill}} +* Stab:: @code{.stabd, .stabn, .stabs} +* Tag:: @code{.tag @var{structname}} +* Text:: @code{.text @var{subsection}} +* Title:: @code{.title "@var{heading}"} +* Type:: @code{.type @var{int}} +* Val:: @code{.val @var{addr}} +* Word:: @code{.word @var{expressions}} +* Deprecated:: Deprecated Directives +@end menu + +@node Abort, coff-ABORT, Pseudo Ops, Pseudo Ops +@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. + +@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}. + + +When producing @code{b.out} output, @code{as} accepts this directive, +but ignores it. + +@node Align, App-File, coff-ABORT, Pseudo Ops +@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} +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. + +@node Data, Def, Comm, Pseudo Ops +@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. + +@node Def, Desc, Data, Pseudo Ops +@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. + +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. + +@node Desc, Dim, Def, Pseudo Ops +@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. + +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. + +@node Dim, Double, Desc, Pseudo Ops +@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. + +@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. + +@node Double, Eject, Dim, Pseudo Ops +@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. +The exact kind of floating point numbers emitted depends on how +@code{as} is configured. @xref{Machine Dependent}. + +@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. + +@node Else, Endef, Eject, Pseudo Ops +@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. + + +@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}. + +@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. + +@node Endif, Equ, Endef, Pseudo Ops +@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}}. + +@node Extern, File, Equ, Pseudo Ops +@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. + +@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. +In some configurations of @code{as}, @code{.file} has already been +removed to avoid conflicts with other assemblers. @xref{Machine Dependent}. + +@node Fill, Float, File, Pseudo Ops +@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}. +The exact kind of floating point numbers emitted depends on how +@code{as} is configured. +@xref{Machine Dependent}. + +@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. + +@node hword, Ident, Global, Pseudo Ops +@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. + +This directive is a synonym for @samp{.short}; depending on the target +architecture, it may also be a synonym for @samp{.word}. + +@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. + +@node If, Include, Ident, Pseudo Ops +@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. + + +@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. + +@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 +@cindex integers, 32-bit +Expect zero or more @var{expressions}, of any section, separated by +commas. For each expression, emit a +32-bit +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}. + +@node Lflags, Line, Lcomm, Pseudo Ops +@section @code{.lflags} + +@cindex @code{lflags} directive (ignored) +@code{as} accepts this directive, for compatibility with other +assemblers, but ignores it. + +@node Line, Ln, Lflags, Pseudo Ops +@section @code{.line @var{line-number}} + +@cindex @code{line} directive +@cindex logical line number +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) +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 + +@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}. + +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. + +@node Ln, List, Line, Pseudo Ops +@section @code{.ln @var{line-number}} + +@cindex @code{ln} directive +@samp{.ln} is a synonym for @samp{.line}. + +@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 +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. + +@node Sbttl, Scl, Quad, Pseudo Ops +@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. + +@node Scl, Section, Sbttl, Pseudo Ops +@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. + +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. + +@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 +@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 +@code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}. +@node Single, Size, Short, Pseudo Ops +@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}. +The exact kind of floating point numbers emitted depends on how +@code{as} is configured. @xref{Machine Dependent}. + +@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. + +@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. + +@node Space, Stab, Size, Pseudo Ops +@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. + +@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{Machine Dependent}. +@end quotation + +@node Stab, Tag, Space, Pseudo Ops +@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 + +@node Tag, Text, Stab, Pseudo Ops +@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. + +@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. + +@node Text, Title, Tag, Pseudo Ops +@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. + +@node Title, Type, Text, Pseudo Ops +@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. + +@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. + +@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. + +@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. + +@samp{.val} is used only for COFF output; when @code{as} is +configured for @code{b.out}, it accepts this directive but ignores it. + +@node Word, Deprecated, Val, Pseudo Ops +@section @code{.word @var{expressions}} + +@cindex @code{word} directive +This directive expects zero or more @var{expressions}, of any section, +separated by commas. + +The size of the number emitted, and its byte order, +depends on what kind of computer will run the program. + +@c on amd29k, i960, sparc the "special treatment to support compilers" doesn't +@c happen---32-bit addressability, period; no long/short jumps. +@cindex difference tables altered +@cindex altered difference tables +@quotation +@emph{Warning: Special Treatment to support Compilers} +@end quotation + +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{Machine Dependent}), you can ignore this issue. + +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. + + +@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 Machine Dependent, Copying, Pseudo Ops, Top +@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 +* Vax-Dependent:: VAX Dependent Features +* AMD29K-Dependent:: AMD 29K Dependent Features +* H8/300-Dependent:: AMD 29K Dependent Features +* i960-Dependent:: Intel 80960 Dependent Features +* M68K-Dependent:: M680x0 Dependent Features +* Sparc-Dependent:: SPARC Dependent Features +* i386-Dependent:: 80386 Dependent Features +@end menu + +@node Vax-Dependent, AMD29K-Dependent, Machine Dependent, Machine Dependent +@section 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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsection 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. + +@node AMD29K-Dependent, H8/300-Dependent, Vax-Dependent, Machine Dependent +@section 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 +@subsection 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 +@subsection Syntax +@menu +* AMD29K-Chars:: Special Characters +* AMD29K-Regs:: Register Names +@end menu + +@node AMD29K-Chars, AMD29K-Regs, AMD29K Syntax, AMD29K Syntax +@subsubsection 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 +@subsubsection 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 +@subsection 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 +@subsection 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 +@subsection 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. + +@node H8/300-Dependent, i960-Dependent, AMD29K-Dependent, Machine Dependent +@section 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 +@subsection 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 +@subsection 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 +@subsubsection 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 +@subsubsection 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 +@subsubsection 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 +@subsection 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 +@subsection 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 +@subsection 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. + +@node i960-Dependent, M68K-Dependent, H8/300-Dependent, Machine Dependent +@section 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 + +@subsection 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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsubsection @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 +@subsubsection 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 + +@c FIXME! node conds are only sufficient for m68k alone, all, and vintage +@node M68K-Dependent, Sparc-Dependent, i960-Dependent, Machine Dependent +@section 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 +@subsection 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 +@subsection 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}. + + +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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsubsection 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 +@subsubsection 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. + +@node Sparc-Dependent, i386-Dependent, M68K-Dependent, Machine Dependent +@section 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 +@subsection 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 +@subsection 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 +@subsection 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 + +@c FIXME! Conditionalize for all combinations in this section +@node i386-Dependent, , Sparc-Dependent, Machine Dependent +@section 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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsection 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 +@subsection 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}. + + +@node Copying, Index, Machine Dependent, 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 |
