diff options
| -rw-r--r-- | gas/doc/.Sanitize | 23 | ||||
| -rw-r--r-- | gas/doc/Makefile.in | 70 | ||||
| -rw-r--r-- | gas/doc/all.m4 | 21 | ||||
| -rw-r--r-- | gas/doc/as-all.texinfo | 5815 | ||||
| -rw-r--r-- | gas/doc/configure.in | 15 | ||||
| -rw-r--r-- | gas/doc/pretex.m4 | 268 |
6 files changed, 22 insertions, 6190 deletions
diff --git a/gas/doc/.Sanitize b/gas/doc/.Sanitize index 8cbb1bb..91ebfe7 100644 --- a/gas/doc/.Sanitize +++ b/gas/doc/.Sanitize @@ -27,23 +27,9 @@ Things-to-keep: Makefile.in configure.in -a29k-coff.m4 -a29k.m4 -all.m4 -as-all.texinfo +all.texi as.1 as.texinfo -gen.m4 -h8.m4 -i80386.m4 -i960.m4 -m680x0.m4 -none.m4 -pretex.m4 -sparc.m4 -vax.m4 -vintage.m4 -z8000.m4 Do-last: @@ -51,7 +37,12 @@ Do-last: # # # $Log$ -# Revision 1.8 1993/03/02 17:57:05 raeburn +# Revision 1.9 1993/04/08 03:12:53 pesch +# Converted to Texinfo conditionals; no longer need M4. +# Checked makeinfo output for "all" config; other old M4 configs now sanitized +# out, will be replaced by .texi configs as each config is tested. +# +# Revision 1.8 1993/03/02 17:57:05 raeburn # ChangeLog is gone # # Revision 1.7 1993/02/13 10:12:26 zoo diff --git a/gas/doc/Makefile.in b/gas/doc/Makefile.in index 47c6e69..a669e76 100644 --- a/gas/doc/Makefile.in +++ b/gas/doc/Makefile.in @@ -1,6 +1,5 @@ # Makefile for GNU Assembler documentation -# - see pretex.m4 for discussion of preprocessor definitions -# Copyright (C) 1987-1992 Free Software Foundation, Inc. +# Copyright (C) 1987-1993 Free Software Foundation, Inc. #This file is part of GNU GAS. @@ -59,19 +58,12 @@ AR = ar AR_FLAGS = qv BISON = bison MAKEINFO = makeinfo -TEXI2DVI = texi2dvi +TEXI2DVI = TEXINPUTS=$$TEXINPUTS:$(TEXIDIR) texi2dvi RANLIB = ranlib -# What version of the manual you want (see *.m4); "all" includes everything +# What version of the manual you want; "all" includes everything CONFIG=all -# Sun/Berkeley m4 doesn't have all the things we need; use GNU or sV -M4=m4 -#M4=/usr/5bin/m4 - -# Directory for gas source -srcdir=.. - # Where to find texinfo.tex to format docn with TeX TEXIDIR = $(srcdir)/../../texinfo @@ -89,8 +81,13 @@ install: info: as.info dvi: as.dvi -as.info: as-${CONFIG}.texinfo - $(MAKEINFO) -o as.info $(srcdir)/as-${CONFIG}.texinfo +asdoc-config.texi: $(CONFIG).texi + ln -s $(srcdir)/$(CONFIG).texi ./asdoc-config.texi || \ + ln $(srcdir)/$(CONFIG).texi ./asdoc-config.texi || \ + cp $(srcdir)/$(CONFIG).texi ./asdoc-config.texi + +as.info: as.texinfo asdoc-config.texi + $(MAKEINFO) -o as.info as.texinfo install-info: as.info -parent=`echo $(infodir)|sed -e 's@/[^/]*$$@@'`; \ @@ -100,12 +97,10 @@ install-info: as.info $(INSTALL_DATA) $$i $(infodir)/$$i ; \ done +dvi: as.dvi + as.dvi: as-${CONFIG}.texinfo - if [ -f $(srcdir)/as-$(CONFIG).texinfo ] ; then \ - $(TEXI2DVI) $(srcdir)/as-$(CONFIG).texinfo ; \ - else \ - $(TEXI2DVI) as-$(CONFIG).texinfo ; \ - fi + $(TEXI2DVI) as-${CONFIG}.texinfo mv as-${CONFIG}.dvi as.dvi # ROFF doc targets as.ms, as.mm, as.me @@ -138,44 +133,6 @@ as.me: as-${CONFIG}.texinfo 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-z8000.texinfo: as.texinfo pretex.m4 none.m4 z8000.m4 - ${M4} pretex.m4 none.m4 z8000.m4 as.texinfo >as-z8000.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* @@ -183,4 +140,3 @@ force: Makefile: $(srcdir)/Makefile.in $(host_makefile_frag) $(target_makefile_frag) $(SHELL) ./config.status - diff --git a/gas/doc/all.m4 b/gas/doc/all.m4 deleted file mode 100644 index 4684bd0..0000000 --- a/gas/doc/all.m4 +++ /dev/null @@ -1,21 +0,0 @@ -_divert__(-1) -<$Id$> -_define__(<_ALL_ARCH__>,<1>) -_define__(<_GENERIC__>,<1>) In case none.m4 changes its mind abt default - -_define__(<_AOUT__>,<1>) -_define__(<_BOUT__>,<1>) -_define__(<_COFF__>,<1>) -_define__(<_ELF__>,<1>) - -_define__(<_A29K__>,<1>) -_define__(<_H8__>,<1>) -_define__(<_I80386__>,<1>) -_define__(<_I960__>,<1>) -_define__(<_M680X0__>,<1>) -_define__(<_Z8000__>,<1>) -_define__(<_SPARC__>,<1>) -_define__(<_VAX__>,<1>) -_define__(<_VXWORKS__>,<1>) - -_divert__<>
\ No newline at end of file diff --git a/gas/doc/as-all.texinfo b/gas/doc/as-all.texinfo deleted file mode 100644 index 393667e..0000000 --- a/gas/doc/as-all.texinfo +++ /dev/null @@ -1,5815 +0,0 @@ -\input texinfo @c -*-Texinfo-*- -@c Copyright (c) 1991 1992 1993 Free Software Foundation, Inc. -@c %**start of header -@setfilename as.info -@settitle Using as -@setchapternewpage odd -@c @smallbook -@c @cropmarks -@c %**end of header - -@ifinfo -@format -START-INFO-DIR-ENTRY -* As: (as). The GNU assembler. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@finalout -@syncodeindex ky cp - -@c -@ifinfo -This file documents the GNU Assembler "as". - -Copyright (C) 1991, 1992, 1993 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 March 1993 -@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 -{\parskip=0pt -\hfill {\it Using {\tt as}}\par -\hfill Edited by Roland Pesch for Cygnus Support\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 - -@vskip 0pt plus 1filll -Copyright @copyright{} 1991, 1992, 1993 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 -@ifinfo -@node Top -@top Using as - -This file is a user guide to the GNU assembler @code{as}. -@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 -@end ifinfo - -@node Overview -@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 and 500 have no machine-dependent assembler options -@c Z8000 has no machine-dependent assembler options -@c see md_parse_option in tc-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[dhlns] -Turn on listings; -@samp{-ad}, omit debugging pseudo-ops from listing, -@samp{-ah}, include high-level source, -@samp{-al}, assembly listing, -@samp{-an}, no forms processing, -@samp{-as}, symbols. These options may be combined; @emph{e.g.}, -@samp{-aln} for assembly listing without forms processing. -By itself, @samp{-a} defaults to @samp{-ahls} --- that is, all listings -turned on. - -@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 -- | @var{files} @dots{} -Standard input, or source files to assemble. - -@end table - -The following options are available when as is configured for the -Intel 80960 processor. - -@table @code -@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC -Specify which variant of the 960 architecture is the target. - -@item -b -Add code to collect statistics about branches taken. - -@item -norelax -Do not alter compare-and-branch instructions for long displacements; -error if necessary. - -@end table - -The following options are available when as is configured for the -Motorola 68000 series. - -@table @code - -@item -l -Shorten references to undefined symbols, to one word instead of two. - -@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -mcpu32 -Specify what processor in the 68000 family is the target. The default -is normally the 68020, but this can be changed at configuration time. - -@item -m68881 | -m68882 | -mno-68881 | -mno-68882 -The target machine does (or does not) have a floating-point coprocessor. -The default is to assume a coprocessor for 68020, 68030, and cpu32. Although -the basic 68000 is not compatible with the 68881, a combination of the -two can be specified, since it's possible to do emulation of the -coprocessor instructions with the main processor. - -@item -m68851 | -mno-68851 -The target machine does (or does not) have a memory-management -unit coprocessor. The default is to assume an MMU for 68020 and up. - -@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 -@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 -@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 -@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 -@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 -@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 -@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{b.out}, -if @code{as} is configured for the Intel 80960, or -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. -(For some formats, this isn't currently possible, but it can be done for -@code{a.out} format.) - -@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 -@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 -@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. - -If you are invoking @code{as} via the GNU C compiler (version 2), you -can use the @samp{-Wa} option to pass arguments through to the -assembler. The assembler arguments must be separated from each other -(and the @samp{-Wa}) by commas. For example: - -@smallexample -gcc -c -g -O -Wa,-alh,-L file.c -@end smallexample - -will cause a listing to be emitted to standard output with high-level -and assembly source. - -Many compiler command-line options, such as @samp{-R} and many -machine-specific options, will be automatically be passed to the -assembler by the compiler, so usually you do not need to use this -@samp{-Wa} mechanism. - -@menu -* a:: -a[dhlns] enable listings -* D:: -D for compatibility -* f:: -f to work faster -* I:: -I for .include search path -* K:: -K for difference tables -* L:: -L to retain local labels -* o:: -o to name the object file -* R:: -R to join data and text sections -* v:: -v to announce version -* W:: -W to suppress warnings -@end menu - -@node a -@section Enable Listings: @code{-a[dhlns]} - -@kindex -a -@kindex -ad -@kindex -ah -@kindex -al -@kindex -an -@kindex -as -@cindex listings, enabling -@cindex assembly listings, enabling - -These options enable listing output from the assembler. By itself, -@samp{-a} requests high-level, assembly, and symbols listing. -Other letters may be used to select specific options for the list: -@samp{-ah} requests a high-level language listing, -@samp{-al} requests an output-program assembly listing, and -@samp{-as} requests a symbol table listing. -High-level listings require that a compiler debugging option like -@samp{-g} be used, and that assembly listings (@samp{-al}) be requested -also. - -The @samp{-ad} option may be used to omit debugging pseudo-ops from the -listing. - -Once you have specified one of these options, you can further control -listing output and its appearance using the directives @code{.list}, -@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and -@code{.sbttl}. -The @samp{-an} option turns off all forms processing. -If you do not request listing output with one of the @samp{-a} options, the -listing-control directives have no effect. - -The letters after @samp{-a} may be combined into one option, -@emph{e.g.}, @samp{-aln}. - -@node D -@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}. - -@node f -@section Work Faster: @code{-f} - -@kindex -f -@cindex trusted compiler -@cindex faster processing (@code{-f}) -@samp{-f} should only be used when assembling programs written by a -(trusted) compiler. @samp{-f} stops the assembler from pre-processing -the input file(s) before assembling them. @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 - -@node I -@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. - -@node K -@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. - -@node L -@section Include Local Labels: @code{-L} - -@kindex -L -@cindex local labels, retaining in output -Labels beginning with @samp{L} (upper case only) are called @dfn{local -labels}. @xref{Symbol Names}. Normally you don't see such labels when -debugging, because they are intended for the use of programs (like -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}. - -@node o -@section Name the Object File: @code{-o} - -@kindex -o -@cindex naming object file -@cindex object file name -There is always one object file output when you run @code{as}. By -default it has the name -@file{a.out} or @file{b.out}, depending on the target for which -@code{as} is configured. -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. - -@node R -@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 its 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}. - -@node v -@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. - -@node W -@section Suppress Warnings: @code{-W} - -@kindex -W -@cindex suppressing warnings -@cindex warnings, suppressing -@code{as} should never give a warning or error message when -assembling compiler output. But programs written by people often -cause @code{as} to give a warning that a particular assumption was -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 -@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 by the 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 -@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 -@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 -@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 SPARC; -@samp{|} on the 680x0; -@samp{;} for the AMD 29K family; -@samp{;} for the H8/300 family; -@samp{!} for the H8/500 family; -@samp{!} for the Z8000; -see @ref{Machine Dependent}. @refill -@c FIXME What about i386, m88k, i860? - -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 -@section 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 -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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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, H8/300, and H8/500 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 -@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 -@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 and H8/500, @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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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. -@xref{Machine Dependent} for additional directives. - -@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}} -* 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 -@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 -@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 -@section @code{.align @var{abs-expr} , @var{abs-expr}} - -@cindex padding the location counter -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@section @code{.lflags} - -@cindex @code{lflags} directive (ignored) -@code{as} accepts this directive, for compatibility with other -assemblers, but ignores it. - -@node Line -@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}. - -@node Ln -@section @code{.ln @var{line-number}} - -@cindex @code{ln} directive -@samp{.ln} is a synonym for @samp{.line}. - -@node List -@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 -@section @code{.long @var{expressions}} - -@cindex @code{long} directive -@code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}. - -@ignore -@c no one seems to know what this is for or whether this description is -@c what it really ought to do -@node Lsym -@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. -@end ignore - -@node Nolist -@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 -@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 -@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 -@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 -@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 -@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 @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 -@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 -@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 -@section @code{.short @var{expressions}} - -@cindex @code{short} directive -@code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}. - -@node Single -@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 -@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 -@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. - -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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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:: Hitachi H8/300 Dependent Features -* H8/500-Dependent:: Hitachi H8/500 Dependent Features -* i960-Dependent:: Intel 80960 Dependent Features -* M68K-Dependent:: M680x0 Dependent Features -* Sparc-Dependent:: SPARC Dependent Features -* Z8000-Dependent:: Z8000 Dependent Features -* i386-Dependent:: 80386 Dependent Features -@end menu - -@node Vax-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 -@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 -@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 -@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 -@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 -@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}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr}, -@code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs}, -@code{gequ}, @code{cc}, @code{lssu}, @code{cs}. -@var{COND} may also be one of the bit tests -@code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc}, -@code{bssi}, @code{bcci}, @code{lbs}, @code{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 -@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 -@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 -@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 -@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 -@subsection Syntax -@menu -* AMD29K-Chars:: Special Characters -* AMD29K-Regs:: Register Names -@end menu - -@node AMD29K-Chars -@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 -@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 -@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 -@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. - -@ignore -@c since we're ignoring .lsym... -@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}}. -@end ignore - -@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 -@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 -@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 -@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 -@subsection Syntax -@menu -* H8/300-Chars:: Special Characters -* H8/300-Regs:: Register Names -* H8/300-Addressing:: Addressing Modes -@end menu - -@node H8/300-Chars -@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 -@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 -@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 -@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 -@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 -@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 - @i{Legend:} - 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 H8/500-Dependent -@section H8/500 Dependent Features - -@cindex H8/500 support -@menu -* H8/500 Options:: Options -* H8/500 Syntax:: Syntax -* H8/500 Floating Point:: Floating Point -* H8/500 Directives:: H8/500 Machine Directives -* H8/500 Opcodes:: Opcodes -@end menu - -@node H8/500 Options -@subsection Options - -@cindex H8/500 options (none) -@cindex options, H8/500 (none) -@code{as} has no additional command-line options for the Hitachi -H8/500 family. - -@node H8/500 Syntax -@subsection Syntax - -@menu -* H8/500-Chars:: Special Characters -* H8/500-Regs:: Register Names -* H8/500-Addressing:: Addressing Modes -@end menu - -@node H8/500-Chars -@subsubsection Special Characters - -@cindex line comment character, H8/500 -@cindex H8/500 line comment character -@samp{!} is the line comment character. - -@cindex line separator, H8/500 -@cindex statement separator, H8/500 -@cindex H8/500 line separator -@samp{;} can be used instead of a newline to separate statements. - -@cindex symbol names, @samp{$} in -@cindex @code{$} in symbol names -Since @samp{$} has no special meaning, you may use it in symbol names. - -@node H8/500-Regs -@subsubsection Register Names - -@cindex H8/500 registers -@cindex registers, H8/500 -You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2}, -@samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, and @samp{r7} to refer to -the H8/500 registers. - -The H8/500 also has these control registers: - -@table @code -@item cp -code pointer - -@item dp -data pointer - -@item bp -base pointer - -@item tp -stack top pointer - -@item ep -extra pointer - -@item sr -status register - -@item ccr -condition code register -@end table - -All registers are 16 bits long. To represent 32 bit numbers, use two -adjacent registers; for distant memory addresses, use one of the segment -pointers (@code{cp} for the program counter; @code{dp} for -@code{r0}--@code{r3}; @code{ep} for @code{r4} and @code{r5}; and -@code{tp} for @code{r6} and @code{r7}. - -@node H8/500-Addressing -@subsubsection Addressing Modes - -@cindex addressing modes, H8/500 -@cindex H8/500 addressing modes -as understands the following addressing modes for the H8/500: -@table @code -@item R@var{n} -Register direct - -@item @@R@var{n} -Register indirect - -@item @@(d:8, R@var{n}) -Register indirect with 8 bit signed displacement - -@item @@(d:16, R@var{n}) -Register indirect with 16 bit signed displacement - -@item @@-R@var{n} -Register indirect with pre-decrement - -@item @@R@var{n}+ -Register indirect with post-increment - -@item @@@var{aa}:8 -8 bit absolute address - -@item @@@var{aa}:16 -16 bit absolute address - -@item #@var{xx}:8 -8 bit immediate - -@item #@var{xx}:16 -16 bit immediate -@end table - -@node H8/500 Floating Point -@subsection Floating Point - -@cindex floating point, H8/500 (@sc{ieee}) -@cindex H8/500 floating point (@sc{ieee}) -The H8/500 family uses @sc{ieee} floating-point numbers. - -@node H8/500 Directives -@subsection H8/500 Machine Directives - -@cindex H8/500 machine directives (none) -@cindex machine directives, H8/500 (none) -@cindex @code{word} directive, H8/500 -@cindex @code{int} directive, H8/500 -@code{as} has no machine-dependent directives for the H8/500. -However, on this platform the @samp{.int} and @samp{.word} directives -generate 16-bit numbers. - -@node H8/500 Opcodes -@subsection Opcodes - -@cindex H8/500 opcode summary -@cindex opcode summary, H8/500 -@cindex mnemonics, H8/500 -@cindex instruction summary, H8/500 -For detailed information on the H8/500 machine instruction set, see -@cite{H8/500 Series Programming Manual} (Hitachi M21T001). - -@code{as} implements all the standard H8/500 opcodes. No additional -pseudo-instructions are needed on this family. - -The following summary of H8/500 opcodes uses this notation to classify -the allowable operands: - -@table @var -@item abs@r{nn} -(@var{abs8}, @var{abs16}, @var{abs24}): nn-bit absolute address - -@item crb -@code{ccr}, @code{br}, @code{ep}, @code{dp}, @code{tp}, @code{dp} - -@item disp8 -Eight-bit displacement - -@item ea -@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},@* -@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16},@* -@code{#xx:8}, @code{#xx:16} - -@item ea_mem -@code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},@* -@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16} - -@item ea_noimm -@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},@* -@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16} - -@item @t{fp} -@code{r6} - -@item imm@r{nn} -(@var{imm4}, @var{imm8}, @var{imm16}): nn-bit immediate data - -@item pcrel@r{nn} -(@var{pcrel8}, @var{pcrel16}): nn-bit address, interpreted as offset -from program counter - -@item qim -@code{-2}, @code{-1}, @code{1}, @code{2} - -@item rd -Any register - -@item rs -A register (distinct from @var{rd}, if both used in the same schema) - -@item rlist -A comma-separated list of registers in parentheses; register ranges -@code{@var{rd}-@var{rs}} are allowed. @samp{(r0-r2,r5)} is an -@var{rlist} equivalent to @samp{(r0,r1,r2,r5)}. - -@item @t{sp} -Stack pointer (@code{r7}) - -@item @t{sr} -Status register - -@item sz -Size; @samp{.b} or @samp{.w}. May be omitted, with default @samp{.w} -@end table - -@noindent -Here is a summary of the opcodes and their arguments: - -@example -ldc[.b] @var{ea},@var{crb} -ldc[.w] @var{ea},sr -add[:q]@var{sz} @var{qim},@var{ea_noimm} -add[:g]@var{sz} @var{ea},@var{rd} -adds@var{sz} @var{ea},@var{rd} -addx@var{sz} @var{ea},@var{rd} -and@var{sz} @var{ea},@var{rd} -andc[.b] @var{imm8},@var{crb} -andc[.w] @var{imm16},sr -bpt -bra[.w] @var{pcrel16} -bra[.b] @var{pcrel8} -bt[.w] @var{pcrel16} -bt[.b] @var{pcrel8} -brn[.w] @var{pcrel16} -brn[.b] @var{pcrel8} -bf[.w] @var{pcrel16} -bf[.b] @var{pcrel8} -bhi[.w] @var{pcrel16} -bhi[.b] @var{pcrel8} -bls[.w] @var{pcrel16} -bls[.b] @var{pcrel8} -bcc[.w] @var{pcrel16} -bcc[.b] @var{pcrel8} -bhs[.w] @var{pcrel16} -bhs[.b] @var{pcrel8} -bcs[.w] @var{pcrel16} -bcs[.b] @var{pcrel8} -blo[.w] @var{pcrel16} -blo[.b] @var{pcrel8} -bne[.w] @var{pcrel16} -bne[.b] @var{pcrel8} -beq[.w] @var{pcrel16} -beq[.b] @var{pcrel8} -bvc[.w] @var{pcrel16} -bvc[.b] @var{pcrel8} -bvs[.w] @var{pcrel16} -bvs[.b] @var{pcrel8} -bpl[.w] @var{pcrel16} -bpl[.b] @var{pcrel8} -bmi[.w] @var{pcrel16} -bmi[.b] @var{pcrel8} -bge[.w] @var{pcrel16} -bge[.b] @var{pcrel8} -blt[.w] @var{pcrel16} -blt[.b] @var{pcrel8} -bgt[.w] @var{pcrel16} -bgt[.b] @var{pcrel8} -ble[.w] @var{pcrel16} -ble[.b] @var{pcrel8} -bclr@var{sz} @var{imm4},@var{ea_noimm} -bclr@var{sz} @var{rs},@var{ea_noimm} -bnot@var{sz} @var{imm4},@var{ea_noimm} -bnot@var{sz} @var{rs},@var{ea_noimm} -bset@var{sz} @var{imm4},@var{ea_noimm} -bset@var{sz} @var{rs},@var{ea_noimm} -bsr[.b] @var{pcrel8} -bsr[.w] @var{pcrel16} -btst@var{sz} @var{imm4},@var{ea_noimm} -btst@var{sz} @var{rs},@var{ea_noimm} -clr@var{sz} @var{ea} -cmp[:e][.b] @var{imm8},@var{rd} -cmp[:i][.w] @var{imm16},@var{rd} -cmp[:g].b @var{imm8},@var{ea_noimm} -cmp[:g][.w] @var{imm16},@var{ea_noimm} -cmp[:g]@var{sz} @var{ea},@var{rd} -dadd @var{rs},@var{rd} -divxu@var{sz} @var{ea},@var{rd} -dsub @var{rs},@var{rd} -exts[.b] @var{rd} -extu[.b] @var{rd} -jmp @@@var{rd} -jmp @@(@var{imm8},@var{rd}) -jmp @@(@var{imm16},@var{rd}) -jmp @var{abs16} -jsr @@@var{rd} -jsr @@(@var{imm8},@var{rd}) -jsr @@(@var{imm16},@var{rd}) -jsr @var{abs16} -ldm @@sp+,(@var{rlist}) -link fp,@var{imm8} -link fp,@var{imm16} -mov[:e][.b] @var{imm8},@var{rd} -mov[:i][.w] @var{imm16},@var{rd} -mov[:l][.w] @var{abs8},@var{rd} -mov[:l].b @var{abs8},@var{rd} -mov[:s][.w] @var{rs},@var{abs8} -mov[:s].b @var{rs},@var{abs8} -mov[:f][.w] @@(@var{disp8},fp),@var{rd} -mov[:f][.w] @var{rs},@@(@var{disp8},fp) -mov[:f].b @@(@var{disp8},fp),@var{rd} -mov[:f].b @var{rs},@@(@var{disp8},fp) -mov[:g]@var{sz} @var{rs},@var{ea_mem} -mov[:g]@var{sz} @var{ea},@var{rd} -mov[:g][.b] @var{imm8},@var{ea_mem} -mov[:g][.w] @var{imm16},@var{ea_mem} -movfpe[.b] @var{ea},@var{rd} -movtpe[.b] @var{rs},@var{ea_noimm} -mulxu@var{sz} @var{ea},@var{rd} -neg@var{sz} @var{ea} -nop -not@var{sz} @var{ea} -or@var{sz} @var{ea},@var{rd} -orc[.b] @var{imm8},@var{crb} -orc[.w] @var{imm16},sr -pjmp @var{abs24} -pjmp @@@var{rd} -pjsr @var{abs24} -pjsr @@@var{rd} -prtd @var{imm8} -prtd @var{imm16} -prts -rotl@var{sz} @var{ea} -rotr@var{sz} @var{ea} -rotxl@var{sz} @var{ea} -rotxr@var{sz} @var{ea} -rtd @var{imm8} -rtd @var{imm16} -rts -scb/f @var{rs},@var{pcrel8} -scb/ne @var{rs},@var{pcrel8} -scb/eq @var{rs},@var{pcrel8} -shal@var{sz} @var{ea} -shar@var{sz} @var{ea} -shll@var{sz} @var{ea} -shlr@var{sz} @var{ea} -sleep -stc[.b] @var{crb},@var{ea_noimm} -stc[.w] sr,@var{ea_noimm} -stm (@var{rlist}),@@-sp -sub@var{sz} @var{ea},@var{rd} -subs@var{sz} @var{ea},@var{rd} -subx@var{sz} @var{ea},@var{rd} -swap[.b] @var{rd} -tas[.b] @var{ea} -trapa @var{imm4} -trap/vs -tst@var{sz} @var{ea} -unlk fp -xch[.w] @var{rs},@var{rd} -xor@var{sz} @var{ea},@var{rd} -xorc.b @var{imm8},@var{crb} -xorc.w @var{imm16},sr -@end example -@node i960-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 - -@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 -@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 -@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 -@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 -@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 -@subsubsection Compare-and-Branch - -@cindex i960 compare/branch instructions -@cindex compare/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 - -@node M68K-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 -@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 -@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 -@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 -@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 -@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 -@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 -@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}. For example, for the -non-PC relative case: -@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 -@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 -@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 -@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 -@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 -@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 - -@node i386-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 -@subsection Options - -@cindex options for i386 (none) -@cindex i386 options (none) -The 80386 has no machine dependent options. - -@node i386-Syntax -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 Z8000-Dependent -@section Z8000 Dependent Features - -@cindex Z8000 support -The Z8000 as supports both members of the Z8000 family: the -unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with -24 bit addresses. - -When the assembler is in unsegmented mode (specified with the -@code{unsegm} directive), an address will take up one word (16 bit) -sized register. When the assembler is in segmented mode (specified with -the @code{segm} directive), a 24-bit address takes up a long (32 bit) -register. @xref{Z8000 Directives,,Assembler Directives for the Z8000}, -for a list of other Z8000 specific assembler directives. - -@menu -* Z8000 Options:: No special command-line options for Z8000 -* Z8000 Syntax:: Assembler syntax for the Z8000 -* Z8000 Directives:: Special directives for the Z8000 -* Z8000 Opcodes:: Opcodes -@end menu - -@node Z8000 Options -@subsection Options - -@cindex Z8000 options -@cindex options, Z8000 -@code{as} has no additional command-line options for the Zilog -Z8000 family. - -@node Z8000 Syntax -@subsection Syntax -@menu -* Z8000-Chars:: Special Characters -* Z8000-Regs:: Register Names -* Z8000-Addressing:: Addressing Modes -@end menu - -@node Z8000-Chars -@subsubsection Special Characters - -@cindex line comment character, Z8000 -@cindex Z8000 line comment character -@samp{!} is the line comment character. - -@cindex line separator, Z8000 -@cindex statement separator, Z8000 -@cindex Z8000 line separator -You can use @samp{;} instead of a newline to separate statements. - -@node Z8000-Regs -@subsubsection Register Names - -@cindex Z8000 registers -@cindex registers, Z8000 -The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer -to different sized groups of registers by register number, with the -prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and -@samp{rq} for 64 bit registers. You can also refer to the contents of -the first eight (of the sixteen 16 bit registers) by bytes. They are -named @samp{r@var{n}h} and @samp{r@var{n}l}. - -@smallexample -@exdent @emph{byte registers} -r0l r0h r1h r1l r2h r2l r3h r3l -r4h r4l r5h r5l r6h r6l r7h r7l - -@exdent @emph{word registers} -r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15 - -@exdent @emph{long word registers} -rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14 - -@exdent @emph{quad word registers} -rq0 rq4 rq8 rq12 -@end smallexample - -@node Z8000-Addressing -@subsubsection Addressing Modes - -@cindex addressing modes, Z8000 -@cindex Z800 addressing modes -as understands the following addressing modes for the Z8000: - -@table @code -@item r@var{n} -Register direct - -@item @@r@var{n} -Indirect register - -@item @var{addr} -Direct: the 16 bit or 24 bit address (depending on whether the assembler -is in segmented or unsegmented mode) of the operand is in the instruction. - -@item address(r@var{n}) -Indexed: the 16 or 24 bit address is added to the 16 bit register to produce -the final address in memory of the operand. - -@item r@var{n}(#@var{imm}) -Base Address: the 16 or 24 bit register is added to the 16 bit sign -extended immediate displacement to produce the final address in memory -of the operand. - -@item r@var{n}(r@var{m}) -Base Index: the 16 or 24 bit register r@var{n} is added to the sign -extended 16 bit index register r@var{m} to produce the final address in -memory of the operand. - -@item #@var{xx} -Immediate data @var{xx}. -@end table - -@node Z8000 Directives -@subsection Assembler Directives for the Z8000 - -@cindex Z8000 directives -@cindex directives, Z8000 -The Z8000 port of as includes these additional assembler directives, -for compatibility with other Z8000 assemblers. As shown, these do not -begin with @samp{.} (unlike the ordinary as directives). - -@table @code -@item segm -@kindex segm -Generates code for the segmented Z8001. - -@item unsegm -@kindex unsegm -Generates code for the unsegmented Z8002. - -@item name -@kindex name -Synonym for @code{.file} - -@item global -@kindex global -Synonum for @code{.global} - -@item wval -@kindex wval -Synonym for @code{.word} - -@item lval -@kindex lval -Synonym for @code{.long} - -@item bval -@kindex bval -Synonym for @code{.byte} - -@item sval -@kindex sval -Assemble a string. @code{sval} expects one string literal, delimited by -single quotes. It assembles each byte of the string into consecutive -addresses. You can use the escape sequence @samp{%@var{xx}} (where -@var{xx} represents a two-digit hexadecimal number) to represent the -character whose @sc{ascii} value is @var{xx}. Use this feature to -describe single quote and other characters that may not appear in string -literals as themselves. For example, the C statement @w{@samp{char *a = -"he said \"it's 50% off\"";}} is represented in Z8000 assembly language -(shown with the assembler output in hex at the left) as - -@iftex -@begingroup -@let@nonarrowing=@comment -@end iftex -@smallexample -68652073 sval 'he said %22it%27s 50%25 off%22%00' -61696420 -22697427 -73203530 -25206F66 -662200 -@end smallexample -@iftex -@endgroup -@end iftex - -@item rsect -@kindex rsect -synonym for @code{.section} - -@item block -@kindex block -synonym for @code{.space} - -@item even -@kindex even -synonym for @code{.align 1} -@end table - -@node Z8000 Opcodes -@subsection Opcodes - -@cindex Z8000 opcode summary -@cindex opcode summary, Z8000 -@cindex mnemonics, Z8000 -@cindex instruction summary, Z8000 -For detailed information on the Z8000 machine instruction set, see -@cite{Z8000 Technical Manual}. - -The following table summarizes the opcodes and their arguments: -@iftex -@begingroup -@let@nonarrowing=@comment -@end iftex -@smallexample - - rs @r{16 bit source register} - rd @r{16 bit destination register} - rbs @r{8 bit source register} - rbd @r{8 bit destination register} - rrs @r{32 bit source register} - rrd @r{32 bit destination register} - rqs @r{64 bit source register} - rqd @r{64 bit destination register} - addr @r{16/24 bit address} - imm @r{immediate data} - -adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc -adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc -add rd,@@rs clrb rbd dab rbd -add rd,addr com @@rd dbjnz rbd,disp7 -add rd,addr(rs) com addr dec @@rd,imm4m1 -add rd,imm16 com addr(rd) dec addr(rd),imm4m1 -add rd,rs com rd dec addr,imm4m1 -addb rbd,@@rs comb @@rd dec rd,imm4m1 -addb rbd,addr comb addr decb @@rd,imm4m1 -addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1 -addb rbd,imm8 comb rbd decb addr,imm4m1 -addb rbd,rbs comflg flags decb rbd,imm4m1 -addl rrd,@@rs cp @@rd,imm16 di i2 -addl rrd,addr cp addr(rd),imm16 div rrd,@@rs -addl rrd,addr(rs) cp addr,imm16 div rrd,addr -addl rrd,imm32 cp rd,@@rs div rrd,addr(rs) -addl rrd,rrs cp rd,addr div rrd,imm16 -and rd,@@rs cp rd,addr(rs) div rrd,rs -and rd,addr cp rd,imm16 divl rqd,@@rs -and rd,addr(rs) cp rd,rs divl rqd,addr -and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs) -and rd,rs cpb addr(rd),imm8 divl rqd,imm32 -andb rbd,@@rs cpb addr,imm8 divl rqd,rrs -andb rbd,addr cpb rbd,@@rs djnz rd,disp7 -andb rbd,addr(rs) cpb rbd,addr ei i2 -andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs -andb rbd,rbs cpb rbd,imm8 ex rd,addr -bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs) -bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs -bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs -bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr -bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs) -bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs -bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8 -bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8 -bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8 -bitb rbd,rs cpl rrd,@@rs ext8f imm8 -bpt cpl rrd,addr exts rrd -call @@rd cpl rrd,addr(rs) extsb rd -call addr cpl rrd,imm32 extsl rqd -call addr(rd) cpl rrd,rrs halt -calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs -clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16 -clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs -clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16 -clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1 -clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1 -inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs) -inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16 -incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs -incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs -incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr -incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs) -ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32 -indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs -inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd -inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr -iret ldib @@rd,@@rs,rr neg addr(rd) -jp cc,@@rd ldir @@rd,@@rs,rr neg rd -jp cc,addr ldirb @@rd,@@rs,rr negb @@rd -jp cc,addr(rd) ldk rd,imm4 negb addr -jr cc,disp8 ldl @@rd,rrs negb addr(rd) -ld @@rd,imm16 ldl addr(rd),rrs negb rbd -ld @@rd,rs ldl addr,rrs nop -ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs -ld addr(rd),rs ldl rd(rx),rrs or rd,addr -ld addr,imm16 ldl rrd,@@rs or rd,addr(rs) -ld addr,rs ldl rrd,addr or rd,imm16 -ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs -ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs -ld rd,@@rs ldl rrd,rrs orb rbd,addr -ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs) -ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8 -ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs -ld rd,rs ldm addr(rd),rs,n out @@rd,rs -ld rd,rs(imm16) ldm addr,rs,n out imm16,rs -ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs -lda rd,addr ldm rd,addr(rs),n outb imm16,rbs -lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra -lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba -lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra -ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra -ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs -ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs -ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs -ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs -ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs -ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs -ldb rbd,@@rs mbit popl addr,@@rs -ldb rbd,addr mreq rd popl rrd,@@rs -ldb rbd,addr(rs) mres push @@rd,@@rs -ldb rbd,imm8 mset push @@rd,addr -ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs) -ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16 -push @@rd,rs set addr,imm4 subl rrd,imm32 -pushl @@rd,@@rs set rd,imm4 subl rrd,rrs -pushl @@rd,addr set rd,rs tcc cc,rd -pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd -pushl @@rd,rrs setb addr(rd),imm4 test @@rd -res @@rd,imm4 setb addr,imm4 test addr -res addr(rd),imm4 setb rbd,imm4 test addr(rd) -res addr,imm4 setb rbd,rs test rd -res rd,imm4 setflg imm4 testb @@rd -res rd,rs sinb rbd,imm16 testb addr -resb @@rd,imm4 sinb rd,imm16 testb addr(rd) -resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd -resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd -resb rbd,imm4 sinib @@rd,@@rs,ra testl addr -resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd) -resflg imm4 sla rd,imm8 testl rrd -ret cc slab rbd,imm8 trdb @@rd,@@rs,rba -rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba -rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr -rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr -rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr -rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr -rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr -rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr -rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd -rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr -rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd) -rsvd36 sra rd,imm8 tset rd -rsvd38 srab rbd,imm8 tsetb @@rd -rsvd78 sral rrd,imm8 tsetb addr -rsvd7e srl rd,imm8 tsetb addr(rd) -rsvd9d srlb rbd,imm8 tsetb rbd -rsvd9f srll rrd,imm8 xor rd,@@rs -rsvdb9 sub rd,@@rs xor rd,addr -rsvdbf sub rd,addr xor rd,addr(rs) -sbc rd,rs sub rd,addr(rs) xor rd,imm16 -sbcb rbd,rbs sub rd,imm16 xor rd,rs -sc imm8 sub rd,rs xorb rbd,@@rs -sda rd,rs subb rbd,@@rs xorb rbd,addr -sdab rbd,rs subb rbd,addr xorb rbd,addr(rs) -sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8 -sdl rd,rs subb rbd,imm8 xorb rbd,rbs -sdlb rbd,rs subb rbd,rbs xorb rbd,rbs -sdll rrd,rs subl rrd,@@rs -set @@rd,imm4 subl rrd,addr -set addr(rd),imm4 subl rrd,addr(rs) -@end smallexample -@iftex -@endgroup -@end iftex - - -@node Copying -@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 -@unnumbered Index - -@printindex cp - -@contents -@bye diff --git a/gas/doc/configure.in b/gas/doc/configure.in index 69833cb..8fe48a9 100644 --- a/gas/doc/configure.in +++ b/gas/doc/configure.in @@ -27,25 +27,14 @@ # appropriate for this directory. For more information, check any # existing configure script. -srctrigger=all.m4 +srctrigger=as.texinfo srcname="gas doc" # per-host: # per-target: -# Make this link, so the Makefile's as-${CONFIG} references can all work, -# while we only keep as-all.texinfo in the source tree. - -cfgs="all a29k a29k-coff gen h8 z8000 i80386 m680x0 sparc vax vintage" files="" -if [ $srcdir != "." ] && [ `cd $srcdir ; pwd` != `pwd` ]; then - for cfg in $cfgs ; do - if [ -r $srcdir/as-$cfg.texinfo ]; then - files="$files as-$cfg.texinfo" - fi - done -fi -links="$files" +links="" # end of gas/doc/configure.in diff --git a/gas/doc/pretex.m4 b/gas/doc/pretex.m4 deleted file mode 100644 index 40c3d26..0000000 --- a/gas/doc/pretex.m4 +++ /dev/null @@ -1,268 +0,0 @@ -divert(-1) -*-Text-*- -` Copyright (c) 1991 Free Software Foundation, Inc.' -` This file defines and documents the M4 macros used ' -` to preprocess some GNU manuals' -` $Id$' - -I. INTRODUCTION - -This collection of M4 macros is meant to help in pre-processing texinfo -files to allow configuring them by hosts; for example, the reader of an -as manual who only has access to a 386 may not really want to see crud about -VAXen. - -A preprocessor is used, rather than extending texinfo, because this -way we can hack the conditionals in only one place; otherwise we would -have to write TeX macros, update makeinfo, and update the Emacs -info-formatting functions. - -II. COMPATIBILITY - -These macros should work with GNU m4 and System V m4; they do not work -with Sun or Berkeley M4. - -III. USAGE - -A. M4 INVOCATION -Assume this file is called "pretex.m4". Then, to preprocess a -document "mybook.texinfo" you might do something like the following: - - m4 pretex.m4 none.m4 PARTIC.m4 mybook.texinfo >mybook-PARTIC.texinfo - ----where your path is set to find GNU or SysV "m4", and the other m4 -files mentioned are as follows: - - none.m4: A file that defines, as 0, all the options you might - want to turn on using the conditionals defined below. - Unlike the C preprocessor, m4 does not default - undefined macros to 0. For example, here is a "none.m4" - I have been using: - _divert__(-1) - - _define__(<_ALL_ARCH__>,<0>) - _define__(<_INTERNALS__>,<0>) - - _define__(<_AMD29K__>,<0>) - _define__(<_I80386__>,<0>) - _define__(<_I960__>,<0>) - _define__(<_M680X0__>,<0>) - _define__(<_SPARC__>,<0>) - _define__(<_VAX__>,<0>) - - _divert__<> - - PARTIC.m4: A file that turns on whichever options you actually - want the manual configured for, in this particular - instance. Its contents are similar to one or more of - the lines in "none.m4", but of course the second - argument to _define__ is <1> rather than <0>. - - This is also a convenient place to _define__ any macros - that you want to expand to different text for - different configurations---for example, the name of - the program being described. - -Naturally, these are just suggested conventions; you could put your macro -definitions in any files or combinations of files you like. - -These macros use the characters < and > as m4 quotes; if you need -these characters in your text, you will also want to use the macros -_0__ and _1__ from this package---see the description of "Quote -Handling" in the "Implementation" section below. - -B. WHAT GOES IN THE PRE-TEXINFO SOURCE - -For the most part, the text of your book. In addition, you can -have text that is included only conditionally, using the macros -_if__ and _fi__ defined below. They BOTH take an argument! This is -primarily meant for readability (so a human can more easily see what -conditional end matches what conditional beginning), but the argument -is actually used in the _fi__ as well as the _if__ implementation. -You should always give a _fi__ the same argument as its matching -_if__. Other arguments may appear to work for a while, but are almost -certain to produce the wrong output for some configurations. - -For example, here is an excerpt from the very beginning of the -documentation for GNU as, to name the info file appropriately for -different configurations: - _if__(_ALL_ARCH__) - @setfilename as.info - _fi__(_ALL_ARCH__) - _if__(_M680X0__ && !_ALL_ARCH__) - @setfilename as-m680x0.info - _fi__(_M680X0__ && !_ALL_ARCH__) - _if__(_AMD29K__ && !_ALL_ARCH__) - @setfilename as-29k.info - _fi__(_AMD29K__ && !_ALL_ARCH__) - -Note that you can use Boolean expressions in the arguments; the -expression language is that of the built-in m4 macro `eval', described -in the m4 manual. - -IV. IMPLEMENTATION - -A.PRIMITIVE RENAMING -First, we redefine m4's built-ins to avoid conflict with plain text. -The naming convention used is that our macros all begin with a single -underbar and end with two underbars. The asymmetry is meant to avoid -conflict with some other conventions (which we may want to document) that -are intended to avoid conflict, like ANSI C predefined macros. - -define(`_undefine__',defn(`undefine')) -define(`_define__',defn(`define')) -define(`_defn__',defn(`defn')) -define(`_ppf__',`_define__(`_$1__',_defn__(`$1'))_undefine__(`$1')') -_ppf__(`builtin') -_ppf__(`changecom') -_ppf__(`changequote') -_ppf__(`decr') -_ppf__(`define') -_ppf__(`defn') -_ppf__(`divert') -_ppf__(`divnum') -_ppf__(`dnl') -_ppf__(`dumpdef') -_ppf__(`errprint') -_ppf__(`esyscmd') -_ppf__(`eval') -_ppf__(`format') -_ppf__(`ifdef') -_ppf__(`ifelse') -_ppf__(`include') -_ppf__(`incr') -_ppf__(`index') -_ppf__(`len') -_ppf__(`m4exit') -_ppf__(`m4wrap') -_ppf__(`maketemp') -_ppf__(`patsubst') -_ppf__(`popdef') -_ppf__(`pushdef') -_ppf__(`regexp') -_ppf__(`shift') -_ppf__(`sinclude') -_ppf__(`substr') -_ppf__(`syscmd') -_ppf__(`sysval') -_ppf__(`traceoff') -_ppf__(`traceon') -_ppf__(`translit') -_ppf__(`undefine') -_ppf__(`undivert') -_ppf__(`unix') - -B. QUOTE HANDLING. - -The characters used as quotes by M4, by default, are unfortunately -quite likely to occur in ordinary text. To avoid surprises, we will -use the characters <> ---which are just as suggestive (more so to -Francophones, perhaps) but a little less common in text (save for -those poor Francophones. You win some, you lose some). Still, we -expect also to have to set < and > occasionally in text; to do that, -we define a macro to turn off quote handling (_0__) and a macro to -turn it back on (_1__), according to our convention. - - BEWARE: This seems to make < and > unusable as relational operations - in calls to the builtin "eval". So far I've gotten - along without; but a better choice may be possible. - -Note that we postponed this for a while, for convenience in discussing -the issue and in the primitive renaming---not to mention in defining -_0__ and _1__ themselves! However, the quote redefinitions MUST -precede the _if__ / _fi__ definitions, because M4 will expand the text -as given---if we use the wrong quotes here, we will get the wrong -quotes when we use the conditionals. - -_define__(_0__,`_changequote__(,)')_define__(_1__,`_changequote__(<,>)') -_1__ - -C. CONDITIONALS - -We define two macros, _if__ and _fi__. BOTH take arguments! This is -meant both to help the human reader match up a _fi__ with its -corresponding _if__ and to aid in the implementation. You may use the -full expression syntax supported by M4 (see docn of `eval' builtin in -the m4 manual). - -The conditional macros are carefully defined to avoid introducing -extra whitespace (i.e., blank lines or blank characters). One side -effect exists--- - - BEWARE: text following an `_if__' on the same line is - DISCARDED even if the condition is true; text - following a `_fi__' on the same line is also - always discarded. - -The recommended convention is to always place _if__ and _fi__ on a -line by themselves. This will also aid the human reader. TeX won't -care about the line breaks; as for info, you may want to insert calls -to `@refill' at the end of paragraphs containing conditionalized text, -where you don't want line breaks separating unconditional from -conditional text. info formatting will then give you nice looking -paragraphs in the info file. - -Nesting: conditionals are designed to nest, in the following way: -*nothing* is output between an outer pair of false conditionals, even -if there are true conditionals inside. A false conditional "defeats" -all conditionals within it. The counter _IF_FS__ is used to -implement this; kindly avoid redefining it directly. - -_define__(<_IF_FS__>,<0>) - -NOTE: The definitions for our "pushf" and "popf" macros use eval -rather than incr and decr, because GNU m4 (0.75) tries to call eval -for us when we say "incr" or "decr"---but doesn't notice we've changed -eval's name. - -_define__( - <_pushf__>, - <_define__(<_IF_FS__>, - _eval__((_IF_FS__)+1))>) -_define__( - <_popf__>, - <_ifelse__(0,_IF_FS__, - <<>_dnl__<>>, - <_define__(<_IF_FS__>,_eval__((_IF_FS__)-1))>)>) - -_define__( - <_if__>, - <_ifelse__(1,_eval__( ($1) ), - <<>_dnl__<>>, - <_pushf__<>_divert__(-1)>)>) -_define__( - <_fi__>, - <_ifelse__(1,_eval__( ($1) ), - <<>_dnl__<>>, - <_popf__<>_ifelse__(0,_IF_FS__, - <_divert__<>_dnl__<>>,<>)>)>) - -D. CHAPTER/SECTION MACRO -In a parametrized manual, the heading level may need to be calculated; -for example, a manual that has a chapter on machine dependencies -should be conditionally structured as follows: - - IF the manual is configured for a SINGLE machine type, use -the chapter heading for that machine type, and run headings down -from there (top level for a particular machine is chapter, then within -that we have section, subsection etc); - - ELSE, if MANY machine types are described in the chapter, -use a generic chapter heading such as "@chapter Machine Dependencies", -use "section" for the top level description of EACH machine, and run -headings down from there (top level for a particular machine is -section, then within that we have subsection, subsubsection etc). - -The macro <_CHAPSEC__> is for this purpose: its argument is evaluated (so -you can construct expressions to express choices such as above), then -expands as follows: - 0: @chapter - 1: @section - 2: @subsection - 3: @subsubsection - ...and so on. - -_define__(<_CHAPSEC__>,<@_cs__(_eval__($1))>) -_define__(<_cs__>,<_ifelse__( - 0, $1, <chapter>, - 1, $1, <section>, - <sub<>_cs__(_eval__($1 - 1))>)>) - -_divert__<>_dnl__<> |