X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gas%2Fdoc%2Fas.texinfo;h=3988d00944cd8a4e9ecb7d2ba95e8f87ff25cf3d;hb=84ea6cf2c5170547163a4bf09ac2bbb3cd424685;hp=ce886426ea5ef85fddc8627f16dd2f6dedaa85e8;hpb=99c4053d0cb7b661e23a98f0e5973b4e6ba2356e;p=deliverable%2Fbinutils-gdb.git diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo index ce886426ea..3988d00944 100644 --- a/gas/doc/as.texinfo +++ b/gas/doc/as.texinfo @@ -1,5 +1,6 @@ \input texinfo @c -*-Texinfo-*- -@c Copyright (c) 1991 1992 1993 1994 Free Software Foundation, Inc. +@c Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 2000 +@c Free Software Foundation, Inc. @c UPDATE!! On future updates-- @c (1) check for new machine-dep cmdline options in @c md_parse_option definitions in config/tc-*.c @@ -15,11 +16,15 @@ @set have-stabs @c --- @include asconfig.texi +@include gasver.texi @c --- @c common OR combinations of conditions @ifset AOUT @set aout-bout @end ifset +@ifset ARM/Thumb +@set ARM +@end ifset @ifset BOUT @set aout-bout @end ifset @@ -82,11 +87,14 @@ END-INFO-DIR-ENTRY @ifinfo This file documents the GNU Assembler "@value{AS}". -Copyright (C) 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 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, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with no Invariant Sections, with no Front-Cover Texts, and with no + Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". @ignore Permission is granted to process this file through Tex and print the @@ -95,28 +103,21 @@ 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 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. @end ifinfo @titlepage @title Using @value{AS} -@subtitle The GNU Assembler +@subtitle The @sc{gnu} Assembler @ifclear GENERIC @subtitle for the @value{TARGET} family @end ifclear @sp 1 -@subtitle January 1994 +@subtitle Version @value{VERSION} @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. +first (Vax) version of @code{as} for Project @sc{gnu}. The proprietors, management and staff of TNCCA thank FSF for distracting the boss while they got some work done. @@ -126,7 +127,7 @@ done. @tex {\parskip=0pt \hfill {\it Using {\tt @value{AS}}}\par -\hfill Edited by Roland Pesch for Cygnus Support\par +\hfill Edited by Cygnus Support\par } %"boxit" macro for figures: %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3) @@ -137,30 +138,32 @@ done. @end tex @vskip 0pt plus 1filll -Copyright @copyright{} 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 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, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with no Invariant Sections, with no Front-Cover Texts, and with no + Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". -Permission is granted to copy and distribute modified versions of this manual -under the conditions for verbatim copying, 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. @end titlepage @ifinfo @node Top @top Using @value{AS} -This file is a user guide to the @sc{gnu} assembler @code{@value{AS}}. +This file is a user guide to the @sc{gnu} assembler @code{@value{AS}} version +@value{VERSION}. @ifclear GENERIC This version of the file describes @code{@value{AS}} configured to generate code for @value{TARGET} architectures. @end ifclear + +This document is distributed under the terms of the GNU Free +Documentation License. A copy of the license is included in the +section entitled "GNU Free Documentation License". + @menu * Overview:: Overview * Invoking:: Command-Line Options @@ -170,7 +173,9 @@ code for @value{TARGET} architectures. * Expressions:: Expressions * Pseudo Ops:: Assembler Directives * Machine Dependencies:: Machine Dependent Features +* Reporting Bugs:: Reporting Bugs * Acknowledgements:: Who Did What +* GNU Free Documentation License:: GNU Free Documentation License * Index:: Index @end menu @end ifinfo @@ -194,26 +199,57 @@ Here is a brief summary of how to invoke @code{@value{AS}}. For details, @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 -@value{AS} [ -a[dhlns] ] [ -D ] [ -f ] [ --help ] - [ -I @var{dir} ] [ -J ] [ -K ] [ -L ] [ -o @var{objfile} ] - [ -R ] [ --statistics ] [ -v ] [ -version ] [ --version ] - [ -W ] [ -w ] [ -x ] [ -Z ] +@value{AS} [ -a[cdhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ] + [ -f ] [ --gstabs ] [ --gdwarf2 ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ] + [ --keep-locals ] [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ] + [ -version ] [ --version ] [ -W ] [ --warn ] [ --fatal-warnings ] + [ -w ] [ -x ] [ -Z ] [ --target-help ] @ifset A29K @c am29k has no machine-dependent assembler options @end ifset -@c start-sanitize-arc @ifset ARC [ -mbig-endian | -mlittle-endian ] @end ifset -@c end-sanitize-arc +@ifset ARM + [ -m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 | -m[arm]6 | -m[arm]60 | + -m[arm]600 | -m[arm]610 | -m[arm]620 | -m[arm]7[t][[d]m[i]][fe] | -m[arm]70 | + -m[arm]700 | -m[arm]710[c] | -m[arm]7100 | -m[arm]7500 | -m[arm]8 | + -m[arm]810 | -m[arm]9 | -m[arm]920 | -m[arm]920t | -m[arm]9tdmi | + -mstrongarm | -mstrongarm110 | -mstrongarm1100 ] + [ -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m | -m[arm]v4 | -m[arm]v4t | + -m[arm]v5 | -[arm]v5t ] + [ -mthumb | -mall ] + [ -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu ] + [ -EB | -EL ] + [ -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant ] + [ -mthumb-interwork ] + [ -moabi ] + [ -k ] +@end ifset +@ifset D10V + [ -O ] +@end ifset +@ifset D30V + [ -O | -n | -N ] +@end ifset @ifset H8 @c Hitachi family chips have no machine-dependent assembler options @end ifset @ifset HPPA @c HPPA has no machine-dependent assembler options (yet). @end ifset +@ifset PJ + [ -mb | -me ] +@end ifset @ifset SPARC - [ -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite | -bump ] +@c The order here is important. See c-sparc.texi. + [ -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite + -Av8plus | -Av8plusa | -Av9 | -Av9a ] + [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ] [ -32 | -64 ] +@end ifset +@ifset TIC54X + [ -mcpu=54[123589] | -mcpu=54[56]lp ] [ -mfar-mode | -mf ] + [ -merrors-to-file | -me ] @end ifset @ifset Z8000 @c Z8000 has no machine-dependent assembler options @@ -223,22 +259,40 @@ Here is a brief summary of how to invoke @code{@value{AS}}. For details, [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ] [ -b ] [ -no-relax ] @end ifset +@ifset M32R + [ --m32rx | --[no-]warn-explicit-parallel-conflicts | --W[n]p ] +@end ifset @ifset M680X0 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ] @end ifset +@ifset MCORE + [ -jsri2bsr ] [ -sifilter ] [ -relax ] + [ -mcpu=[210|340] ] +@end ifset +@ifset M68HC11 + [ -m68hc11 | -m68hc12 ] + [ --force-long-branchs ] [ --short-branchs ] [ --strict-direct-mode ] + [ --print-insn-syntax ] [ --print-opcodes ] [ --generate-example ] +@end ifset @ifset MIPS [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ] - [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ] + [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -mips4 ] [ -mips5 ] + [ -mips32 ] [ -mips64 ] + [ -m4650 ] [ -no-m4650 ] [ --trap ] [ --break ] + [ --emulation=@var{name} ] @end ifset [ -- | @var{files} @dots{} ] @end smallexample @table @code -@item -a[dhlns] +@item -a[cdhlmns] Turn on listings, in any of a variety of ways: @table @code +@item -ac +omit false conditionals + @item -ad omit debugging directives @@ -248,28 +302,51 @@ include high-level source @item -al include assembly +@item -am +include macro expansions + @item -an omit forms processing @item -as include symbols + +@item =file +set the name of the listing file @end table You may combine these options; for example, use @samp{-aln} for assembly -listing without forms processing. By itself, @samp{-a} defaults to -@samp{-ahls}---that is, all listings turned on. +listing without forms processing. The @samp{=file} option, if used, must be +the last one. By itself, @samp{-a} defaults to @samp{-ahls}. @item -D Ignored. This option is accepted for script compatibility with calls to other assemblers. +@item --defsym @var{sym}=@var{value} +Define the symbol @var{sym} to be @var{value} before assembling the input file. +@var{value} must be an integer constant. As in C, a leading @samp{0x} +indicates a hexadecimal value, and a leading @samp{0} indicates an octal value. + @item -f ``fast''---skip whitespace and comment preprocessing (assume source is compiler output). +@item --gstabs +Generate stabs debugging information for each assembler line. This +may help debugging assembler code, if the debugger can handle it. + +@item --gdwarf2 +Generate DWARF2 debugging information for each assembler line. This +may help debugging assembler code, if the debugger can handle it. Note - this +option is only supported by some targets, not all of them. + @item --help Print a summary of the command line options and exit. +@item --target-help +Print a summary of all target specific options and exit. + @item -I @var{dir} Add directory @var{dir} to the search list for @code{.include} directives. @@ -285,7 +362,10 @@ Issue warnings when difference tables altered for long displacements. @end ifset @item -L -Keep (in the symbol table) local symbols, starting with @samp{L}. +@itemx --keep-locals +Keep (in the symbol table) local symbols. On traditional a.out systems +these start with @samp{L}, but different systems have different local +label prefixes. @item -o @var{objfile} Name the object-file output from @code{@value{AS}} @var{objfile}. @@ -297,6 +377,9 @@ Fold the data section into the text section. Print the maximum space (in bytes) and total time (in seconds) used by assembly. +@item --strip-local-absolute +Remove local absolute symbols from the outgoing symbol table. + @item -v @itemx -version Print the @code{as} version. @@ -305,8 +388,15 @@ Print the @code{as} version. Print the @code{as} version and exit. @item -W +@itemx --no-warn Suppress warning messages. +@item --fatal-warnings +Treat warnings as errors. + +@item --warn +Don't suppress warning messages or treat them as errors. + @item -w Ignored. @@ -340,6 +430,61 @@ Generate ``little endian'' format output. @end table @end ifset +@ifset ARM +The following options are available when @value{AS} is configured for the ARM +processor family. + +@table @code +@item -m[arm][1|2|3|6|7|8|9][...] +Specify which ARM processor variant is the target. +@item -m[arm]v[2|2a|3|3m|4|4t|5|5t] +Specify which ARM architecture variant is used by the target. +@item -mthumb | -mall +Enable or disable Thumb only instruction decoding. +@item -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu +Select which Floating Point architcture is the target. +@item -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant | -moabi +Select which procedure calling convention is in use. +@item -EB | -EL +Select either big-endian (-EB) or little-endian (-EL) output. +@item -mthumb-interwork +Specify that the code has been generated with interworking between Thumb and +ARM code in mind. +@item -k +Specify that PIC code has been generated. +@end table +@end ifset + +@ifset D10V +The following options are available when @value{AS} is configured for +a D10V processor. +@table @code +@cindex D10V optimization +@cindex optimization, D10V +@item -O +Optimize output by parallelizing instructions. +@end table +@end ifset + +@ifset D30V +The following options are available when @value{AS} is configured for a D30V +processor. +@table @code +@cindex D30V optimization +@cindex optimization, D30V +@item -O +Optimize output by parallelizing instructions. + +@cindex D30V nops +@item -n +Warn when nops are generated. + +@cindex D30V nops after 32-bit multiply +@item -N +Warn when a nop after a 32-bit multiply instruction is generated. +@end table +@end ifset + @ifset I960 The following options are available when @value{AS} is configured for the Intel 80960 processor. @@ -358,6 +503,27 @@ error if necessary. @end table @end ifset +@ifset M32R +The following options are available when @value{AS} is configured for the +Mitsubishi M32R series. + +@table @code + +@item --m32rx +Specify which processor in the M32R family is the target. The default +is normally the M32R, but this option changes it to the M32RX. + +@item --warn-explicit-parallel-conflicts or --Wp +Produce warning messages when questionable parallel constructs are +encountered. + +@item --no-warn-explicit-parallel-conflicts or --Wnp +Do not produce warning messages when questionable parallel constructs are +encountered. + +@end table +@end ifset + @ifset M680X0 The following options are available when @value{AS} is configured for the Motorola 68000 series. @@ -367,8 +533,8 @@ Motorola 68000 series. @item -l Shorten references to undefined symbols, to one word instead of two. -@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 -@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 +@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060 +@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200 Specify what processor in the 68000 family is the target. The default is normally the 68020, but this can be changed at configuration time. @@ -386,19 +552,101 @@ unit coprocessor. The default is to assume an MMU for 68020 and up. @end table @end ifset +@ifset PJ +The following options are available when @value{AS} is configured for +a picoJava processor. + +@table @code + +@cindex PJ endianness +@cindex endianness, PJ +@cindex big endian output, PJ +@item -mb +Generate ``big endian'' format output. + +@cindex little endian output, PJ +@item -ml +Generate ``little endian'' format output. + +@end table +@end ifset + +@ifset M68HC11 +The following options are available when @value{AS} is configured for the +Motorola 68HC11 or 68HC12 series. + +@table @code + +@item -m68hc11 | -m68hc12 +Specify what processor is the target. The default is +defined by the configuration option when building the assembler. + +@item --force-long-branchs +Relative branches are turned into absolute ones. This concerns +conditional branches, unconditional branches and branches to a +sub routine. + +@item -S | --short-branchs +Do not turn relative branchs into absolute ones +when the offset is out of range. + +@item --strict-direct-mode +Do not turn the direct addressing mode into extended addressing mode +when the instruction does not support direct addressing mode. + +@item --print-insn-syntax +Print the syntax of instruction in case of error. + +@item --print-opcodes +print the list of instructions with syntax and then exit. + +@item --generate-example +print an example of instruction for each possible instruction and then exit. +This option is only useful for testing @code{@value{AS}}. + +@end table +@end ifset + @ifset SPARC The following options are available when @code{@value{AS}} is configured for the SPARC architecture: @table @code -@item -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite +@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite +@itemx -Av8plus | -Av8plusa | -Av9 | -Av9a Explicitly select a variant of the SPARC architecture. +@samp{-Av8plus} and @samp{-Av8plusa} select a 32 bit environment. +@samp{-Av9} and @samp{-Av9a} select a 64 bit environment. + +@samp{-Av8plusa} and @samp{-Av9a} enable the SPARC V9 instruction set with +UltraSPARC extensions. + +@item -xarch=v8plus | -xarch=v8plusa +For compatibility with the Solaris v9 assembler. These options are +equivalent to -Av8plus and -Av8plusa, respectively. + @item -bump Warn when the assembler switches to another architecture. @end table @end ifset +@ifset TIC54X +The following options are available when @value{AS} is configured for the 'c54x +architecture. + +@table @code +@item -mfar-mode +Enable extended addressing mode. All addresses and relocations will assume +extended addressing (usually 23 bits). +@item -mcpu=@var{CPU_VERSION} +Sets the CPU version being compiled for. +@item -merrors-to-file @var{FILENAME} +Redirect error output to a file, for broken systems which don't support such +behaviour in the shell. +@end table +@end ifset + @ifset MIPS The following options are available when @value{AS} is configured for a MIPS processor. @@ -423,13 +671,18 @@ Generate ``little endian'' format output. @item -mips1 @itemx -mips2 @itemx -mips3 +@itemx -mips4 +@itemx -mips32 Generate code for a particular MIPS Instruction Set Architecture level. @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors, @samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000} processor. +@samp{-mips5}, @samp{-mips32}, and @samp{-mips64} correspond +to generic @sc{MIPS V}, @sc{MIPS32}, and @sc{MIPS64} ISA +processors, respectively. @item -m4650 -@item -no-m4650 +@itemx -no-m4650 Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop} instructions around accesses to the @samp{HI} and @samp{LO} registers. @@ -439,10 +692,36 @@ instructions around accesses to the @samp{HI} and @samp{LO} registers. Generate code for a particular MIPS cpu. This has little effect on the assembler, but it is passed by @code{@value{GCC}}. +@cindex emulation +@item --emulation=@var{name} +This option causes @code{@value{AS}} to emulate @code{@value{AS}} configured +for some other target, in all respects, including output format (choosing +between ELF and ECOFF only), handling of pseudo-opcodes which may generate +debugging information or store symbol table information, and default +endianness. The available configuration names are: @samp{mipsecoff}, +@samp{mipself}, @samp{mipslecoff}, @samp{mipsbecoff}, @samp{mipslelf}, +@samp{mipsbelf}. The first two do not alter the default endianness from that +of the primary target for which the assembler was configured; the others change +the default to little- or big-endian as indicated by the @samp{b} or @samp{l} +in the name. Using @samp{-EB} or @samp{-EL} will override the endianness +selection in any case. + +This option is currently supported only when the primary target +@code{@value{AS}} is configured for is a MIPS ELF or ECOFF target. +Furthermore, the primary target or others specified with +@samp{--enable-targets=@dots{}} at configuration time must include support for +the other format, if both are to be available. For example, the Irix 5 +configuration includes support for both. + +Eventually, this option will support more configurations, with more +fine-grained control over the assembler's behavior, and will be supported for +more processors. + @item -nocpp @code{@value{AS}} ignores this option. It is accepted for compatibility with the native tools. +@need 900 @item --trap @itemx --no-trap @itemx --break @@ -455,9 +734,40 @@ break exception. @end table @end ifset +@ifset MCORE +The following options are available when @value{AS} is configured for +an MCore processor. + +@table @code +@item -jsri2bsr +@itemx -nojsri2bsr +Enable or disable the JSRI to BSR transformation. By default this is enabled. +The command line option @samp{-nojsri2bsr} can be used to disable it. + +@item -sifilter +@itemx -nosifilter +Enable or disable the silicon filter behaviour. By default this is disabled. +The default can be overidden by the @samp{-sifilter} command line option. + +@item -relax +Alter jump instructions for long displacements. + +@item -mcpu=[210|340] +Select the cpu type on the target hardware. This controls which instructions +can be assembled. + +@item -EB +Assemble for a big endian target. + +@item -EL +Assemble for a little endian target. + +@end table +@end ifset + @menu * Manual:: Structure of this Manual -* GNU Assembler:: @value{AS}, the GNU Assembler +* GNU Assembler:: The GNU Assembler * Object Formats:: Object File Formats * Command Line:: Command Line * Input Files:: Input Files @@ -513,7 +823,7 @@ For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Techni @end ifset @end ifclear -@c I think this is premature---pesch@cygnus.com, 17jan1991 +@c I think this is premature---doc@cygnus.com, 17jan1991 @ignore Throughout this manual, we assume that you are running @dfn{GNU}, the portable operating system from the @dfn{Free Software @@ -538,7 +848,7 @@ computer-readable series of instructions. Different versions of @c directives). @node GNU Assembler -@section @value{AS}, the GNU Assembler +@section The GNU Assembler @sc{gnu} @code{as} is really a family of assemblers. @ifclear GENERIC @@ -551,7 +861,7 @@ 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{@value{AS}} +@cindex purpose of @sc{gnu} assembler @code{@value{AS}} is primarily intended to assemble the output of the @sc{gnu} C compiler @code{@value{GCC}} for use by the linker @code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}} @@ -644,7 +954,7 @@ 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 +@c APL training... doc@cygnus.com The source program is a concatenation of the text in all the files, in the order specified. @@ -681,10 +991,11 @@ number in a physical file; the other refers to a line number in a to @code{@value{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{@value{AS}} -source is itself synthesized from other files. -@xref{App-File,,@code{.app-file}}. +directives; they bear no relation to physical files. Logical file names help +error messages reflect the original source file, when @code{@value{AS}} source +is itself synthesized from other files. @code{@value{AS}} understands the +@samp{#} directives emitted by the @code{@value{GCC}} preprocessor. See also +@ref{File,,@code{.file}}. @node Object @section Output (Object) File @@ -719,14 +1030,14 @@ 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. +@c don't forget to describe @sc{gnu} info as well as Unix lossage. @node Errors @section Error and Warning Messages @cindex error messsages @cindex warning messages -@cindex messages from @code{@value{AS}} +@cindex messages from assembler @code{@value{AS}} may write warnings and error messages to the standard error file (usually your terminal). This should not happen when a compiler runs @code{@value{AS}} automatically. Warnings report an assumption made so @@ -743,9 +1054,8 @@ file_name:@b{NNN}:Warning Message Text @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{File,,@code{.file}}) it is used for the filename, otherwise the name of +the current input file is used. If a logical line number was given @ifset GENERIC (@pxref{Line,,@code{.line}}) @end ifset @@ -774,7 +1084,7 @@ because many of them aren't supposed to happen. @node Invoking @chapter Command-Line Options -@cindex options, all versions of @code{@value{AS}} +@cindex options, all versions of assembler This chapter describes command-line options available in @emph{all} versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific @ifclear GENERIC @@ -784,18 +1094,19 @@ to the @value{TARGET}. to particular machine architectures. @end ifset -If you are invoking @code{@value{AS}} via the @sc{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: +If you are invoking @code{@value{AS}} via the @sc{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 @noindent -emits a listing to standard output with high-level -and assembly source. +This passes two options to the assembler: @samp{-alh} (emit a listing to +standard output with with high-level and assembly source) and @samp{-L} (retain +local symbols in the symbol table). Usually you do not need to use this @samp{-Wa} mechanism, since many compiler command-line options are automatically passed to the assembler by the compiler. @@ -804,7 +1115,7 @@ precisely what options it passes to each compilation pass, including the assembler.) @menu -* a:: -a[dhlns] enable listings +* a:: -a[cdhlns] enable listings * D:: -D for compatibility * f:: -f to work faster * I:: -I for .include search path @@ -816,18 +1127,22 @@ assembler.) @end ifset * L:: -L to retain local labels +* M:: -M or --mri to assemble in MRI compatibility mode +* MD:: --MD for dependency tracking * o:: -o to name the object file * R:: -R to join data and text sections * statistics:: --statistics to see statistics about assembly +* traditional-format:: --traditional-format for compatible output * v:: -v to announce version -* W:: -W to suppress warnings +* W:: -W, --no-warn, --warn, --fatal-warnings to control warnings * Z:: -Z to make object file even after errors @end menu @node a -@section Enable Listings: @code{-a[dhlns]} +@section Enable Listings: @code{-a[cdhlns]} @kindex -a +@kindex -ac @kindex -ad @kindex -ah @kindex -al @@ -846,6 +1161,11 @@ High-level listings require that a compiler debugging option like @samp{-g} be used, and that assembly listings (@samp{-al}) be requested also. +Use the @samp{-ac} option to omit false conditionals from a listing. Any lines +which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any +other conditional), or a true @code{.if} followed by an @code{.else}, will be +omitted from the listing. + Use the @samp{-ad} option to omit debugging directives from the listing. @@ -944,11 +1264,152 @@ target is allowed to redefine the local label prefix. @ifset HPPA On the HPPA local labels begin with @samp{L$}. @end ifset -@c start-sanitize-arc -@ifset ARC -On the ARC local labels begin with @samp{.L}. -@end ifset -@c end-sanitize-arc + +@node M +@section Assemble in MRI Compatibility Mode: @code{-M} + +@kindex -M +@cindex MRI compatibility mode +The @code{-M} or @code{--mri} option selects MRI compatibility mode. This +changes the syntax and pseudo-op handling of @code{@value{AS}} to make it +compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the +configured target) assembler from Microtec Research. The exact nature of the +MRI syntax will not be documented here; see the MRI manuals for more +information. Note in particular that the handling of macros and macro +arguments is somewhat different. The purpose of this option is to permit +assembling existing MRI assembler code using @code{@value{AS}}. + +The MRI compatibility is not complete. Certain operations of the MRI assembler +depend upon its object file format, and can not be supported using other object +file formats. Supporting these would require enhancing each object file format +individually. These are: + +@itemize @bullet +@item global symbols in common section + +The m68k MRI assembler supports common sections which are merged by the linker. +Other object file formats do not support this. @code{@value{AS}} handles +common sections by treating them as a single common symbol. It permits local +symbols to be defined within a common section, but it can not support global +symbols, since it has no way to describe them. + +@item complex relocations + +The MRI assemblers support relocations against a negated section address, and +relocations which combine the start addresses of two or more sections. These +are not support by other object file formats. + +@item @code{END} pseudo-op specifying start address + +The MRI @code{END} pseudo-op permits the specification of a start address. +This is not supported by other object file formats. The start address may +instead be specified using the @code{-e} option to the linker, or in a linker +script. + +@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops + +The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module +name to the output file. This is not supported by other object file formats. + +@item @code{ORG} pseudo-op + +The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given +address. This differs from the usual @code{@value{AS}} @code{.org} pseudo-op, +which changes the location within the current section. Absolute sections are +not supported by other object file formats. The address of a section may be +assigned within a linker script. +@end itemize + +There are some other features of the MRI assembler which are not supported by +@code{@value{AS}}, typically either because they are difficult or because they +seem of little consequence. Some of these may be supported in future releases. + +@itemize @bullet + +@item EBCDIC strings + +EBCDIC strings are not supported. + +@item packed binary coded decimal + +Packed binary coded decimal is not supported. This means that the @code{DC.P} +and @code{DCB.P} pseudo-ops are not supported. + +@item @code{FEQU} pseudo-op + +The m68k @code{FEQU} pseudo-op is not supported. + +@item @code{NOOBJ} pseudo-op + +The m68k @code{NOOBJ} pseudo-op is not supported. + +@item @code{OPT} branch control options + +The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB}, +@code{BRL}, and @code{BRW}---are ignored. @code{@value{AS}} automatically +relaxes all branches, whether forward or backward, to an appropriate size, so +these options serve no purpose. + +@item @code{OPT} list control options + +The following m68k @code{OPT} list control options are ignored: @code{C}, +@code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M}, +@code{MEX}, @code{MC}, @code{MD}, @code{X}. + +@item other @code{OPT} options + +The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O}, +@code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}. + +@item @code{OPT} @code{D} option is default + +The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler. +@code{OPT NOD} may be used to turn it off. + +@item @code{XREF} pseudo-op. + +The m68k @code{XREF} pseudo-op is ignored. + +@item @code{.debug} pseudo-op + +The i960 @code{.debug} pseudo-op is not supported. + +@item @code{.extended} pseudo-op + +The i960 @code{.extended} pseudo-op is not supported. + +@item @code{.list} pseudo-op. + +The various options of the i960 @code{.list} pseudo-op are not supported. + +@item @code{.optimize} pseudo-op + +The i960 @code{.optimize} pseudo-op is not supported. + +@item @code{.output} pseudo-op + +The i960 @code{.output} pseudo-op is not supported. + +@item @code{.setreal} pseudo-op + +The i960 @code{.setreal} pseudo-op is not supported. + +@end itemize + +@node MD +@section Dependency tracking: @code{--MD} + +@kindex --MD +@cindex dependency tracking +@cindex make rules + +@code{@value{AS}} can generate a dependency file for the file it creates. This +file consists of a single rule suitable for @code{make} describing the +dependencies of the main source file. + +The rule is written to the file named in its argument. + +This feature is used in the automatic updating of makefiles. @node o @section Name the Object File: @code{-o} @@ -1023,31 +1484,55 @@ Use @samp{--statistics} to display two statistics about the resources used by (in bytes), and the total execution time taken for the assembly (in @sc{cpu} seconds). +@node traditional-format +@section Compatible output: @code{--traditional-format} + +@kindex --traditional-format +For some targets, the output of @code{@value{AS}} is different in some ways +from the output of some existing assembler. This switch requests +@code{@value{AS}} to use the traditional format instead. + +For example, it disables the exception frame optimizations which +@code{@value{AS}} normally does by default on @code{@value{GCC}} output. + @node v @section Announce Version: @code{-v} @kindex -v @kindex -version -@cindex @code{@value{AS}} version -@cindex version of @code{@value{AS}} +@cindex assembler version +@cindex version of assembler 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} +@section Control Warnings: @code{-W}, @code{--warn}, @code{--no-warn}, @code{--fatal-warnings} -@kindex -W -@cindex suppressing warnings -@cindex warnings, suppressing @code{@value{AS}} should never give a warning or error message when assembling compiler output. But programs written by people often cause @code{@value{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{@value{AS}} assembles your file. Errors, which stop the assembly, are -still reported. + +@kindex @samp{-W} +@kindex @samp{--no-warn} +@cindex suppressing warnings +@cindex warnings, suppressing +If you use the @code{-W} and @code{--no-warn} options, no warnings are issued. +This only affects the warning messages: it does not change any particular of +how @code{@value{AS}} assembles your file. Errors, which stop the assembly, +are still reported. + +@kindex @samp{--fatal-warnings} +@cindex errors, caused by warnings +@cindex warnings, causing error +If you use the @code{--fatal-warnings} option, @code{@value{AS}} considers +files that generate warnings to be in error. + +@kindex @samp{--warn} +@cindex warnings, switching on +You can switch these options off again by specifying @code{--warn}, which +causes warnings to be output as usual. @node Z @section Generate Object File in Spite of Errors: @code{-Z} @@ -1163,25 +1648,14 @@ This means you may not nest these comments. @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 -@c start-sanitize-arc +@ifset A29K +@samp{;} for the AMD 29K family; +@end ifset @ifset ARC @samp{;} on the ARC; @end ifset -@c end-sanitize-arc -@ifset VAX -@samp{#} on the Vax; -@end ifset -@ifset I960 -@samp{#} on the i960; -@end ifset -@ifset SPARC -@samp{!} on the SPARC; -@end ifset -@ifset M680X0 -@samp{|} on the 680x0; -@end ifset -@ifset A29K -@samp{;} for the AMD 29K family; +@ifset ARM +@samp{@@} on the ARM; @end ifset @ifset H8/300 @samp{;} for the H8/300 family; @@ -1192,12 +1666,36 @@ is considered a comment and is ignored. The line comment character is @ifset HPPA @samp{;} for the HPPA; @end ifset +@ifset I960 +@samp{#} on the i960; +@end ifset +@ifset PJ +@samp{;} for picoJava; +@end ifset @ifset SH @samp{!} for the Hitachi SH; @end ifset +@ifset SPARC +@samp{!} on the SPARC; +@end ifset +@ifset M32R +@samp{#} on the m32r; +@end ifset +@ifset M680X0 +@samp{|} on the 680x0; +@end ifset +@ifset M68HC11 +@samp{#} on the 68HC11 and 68HC12; +@end ifset +@ifset VAX +@samp{#} on the Vax; +@end ifset @ifset Z8000 @samp{!} for the Z8000; @end ifset +@ifset V850 +@samp{#} on the V850; +@end ifset see @ref{Machine Dependencies}. @refill @c FIXME What about i386, m88k, i860? @@ -1207,6 +1705,13 @@ character only begins a comment if it is the first non-whitespace character on a line, while the other always begins a comment. @end ifset +@ifset V850 +The V850 assembler also supports a double dash as starting a comment that +extends to the end of the line. + +@samp{--}; +@end ifset + @kindex # @cindex lines starting with @code{#} @cindex logical line numbers @@ -1308,22 +1813,12 @@ exception: they do not end statements. It is an error to end any statement with end-of-file: the last character of any input file should be a newline.@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{@value{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 @defn{} it in that case, as was done previously... doc@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 @@ -1414,39 +1909,39 @@ escape character). The complete list of escapes follows. @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}) +@item \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}) +@item \f Mnemonic for FormFeed; for ASCII this is octal code 014. -@item \n @cindex @code{\n} (newline character) @cindex newline (@code{\n}) +@item \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}) +@item \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}) +@item \t Mnemonic for horizontal Tab; for ASCII this is octal code 011. @c @item \v @@ -1454,24 +1949,22 @@ Mnemonic for horizontal Tab; for ASCII this is octal code 011. @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}}) +@item \ @var{digit} @var{digit} @var{digit} An octal character code. The numeric code is 3 octal digits. For compatibility with other Unix systems, 8 and 9 are accepted as digits: for example, @code{\008} has the value 010, and @code{\009} the value 011. -@ifset HPPA -@item \@code{x} @var{hex-digit} @var{hex-digit} -@cindex @code{\@var{xdd}} (hex character code) -@cindex hex character code (@code{\@var{xdd}}) -A hex character code. The numeric code is 2 hexadecimal digits. Either -upper or lower case @code{x} works. -@end ifset +@cindex @code{\@var{xd...}} (hex character code) +@cindex hex character code (@code{\@var{xd...}}) +@item \@code{x} @var{hex-digits...} +A hex character code. All trailing hex digits are combined. Either upper or +lower case @code{x} works. -@item \\ @cindex @code{\\} (@samp{\} character) @cindex backslash (@code{\\}) +@item \\ Represents one @samp{\} character. @c @item \' @@ -1480,9 +1973,9 @@ Represents one @samp{\} character. @c (@xref{Characters,,Character Constants}.) to represent @c a @samp{'}. @c -@item \" @cindex @code{\"} (doublequote character) @cindex doublequote (@code{\"}) +@item \" Represents one @samp{"} character. Needed in strings to represent this character, because an unescaped @samp{"} would end the string. @@ -1632,10 +2125,8 @@ Hitachi SH, and AMD 29K architectures, the letter must be one of the letters @samp{DFPRSX} (in upper or lower case). -@c start-sanitize-arc -On the ARC, the letter one of the letters @samp{DFRS} +On the ARC, the letter must be one of the letters @samp{DFRS} (in upper or lower case). -@c end-sanitize-arc On the Intel 960 architecture, the letter must be one of the letters @samp{DFT} (in upper or lower case). @@ -1646,20 +2137,18 @@ On the HPPA architecture, the letter must be @samp{E} (upper case only). @ifset A29K One of the letters @samp{DFPRSX} (in upper or lower case). @end ifset -@c start-sanitize-arc @ifset ARC One of the letters @samp{DFRS} (in upper or lower case). @end ifset -@c end-sanitize-arc @ifset H8 One of the letters @samp{DFPRSX} (in upper or lower case). @end ifset -@ifset I960 -One of the letters @samp{DFT} (in upper or lower case). -@end ifset @ifset HPPA The letter @samp{E} (upper case only). @end ifset +@ifset I960 +One of the letters @samp{DFT} (in upper or lower case). +@end ifset @end ifclear @item @@ -1737,8 +2226,8 @@ The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long}, @menu * Secs Background:: Background -* Ld Sections:: @value{LD} Sections -* As Sections:: @value{AS} Internal Sections +* Ld Sections:: Linker Sections +* As Sections:: Assembler Internal Sections * Sub-Sections:: Sub-Sections * bss:: bss Section @end menu @@ -1774,7 +2263,7 @@ and for the Hitachi SH, ensure they end on a word (sixteen bit) boundary. @end ifset -@cindex standard @code{@value{AS}} sections +@cindex standard assembler sections An object file written by @code{@value{AS}} has at least three sections, any of which may be empty. These are named @dfn{text}, @dfn{data} and @dfn{bss} sections. @@ -1882,7 +2371,7 @@ Some sections are manipulated by @code{@value{LD}}; others are invented for use of @code{@value{AS}} and have no meaning except during assembly. @node Ld Sections -@section @value{LD} Sections +@section Linker Sections @code{@value{LD}} deals with just four kinds of sections, summarized below. @table @strong @@ -1987,9 +2476,9 @@ DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil} @c END TEXI2ROFF-KILL @node As Sections -@section @value{AS} Internal Sections +@section Assembler Internal Sections -@cindex internal @code{@value{AS}} sections +@cindex internal assembler sections @cindex sections in messages, internal These sections are meant only for the internal use of @code{@value{AS}}. They have no meaning at run-time. You do not really need to know about these @@ -2000,13 +2489,13 @@ value of every expression in your assembly language program to be a section-relative address. @table @b -@item ASSEMBLER-INTERNAL-LOGIC-ERROR! @cindex assembler internal logic error +@item ASSEMBLER-INTERNAL-LOGIC-ERROR! An internal assembler logic error has been found. This means there is a bug in the assembler. -@item expr section @cindex expr (internal section) +@item expr section The assembler stores complex expression internally as combinations of symbols. When it needs to represent an expression as a symbol, it puts it in the expr section. @@ -2136,10 +2625,19 @@ 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}}. +The @code{.lcomm} pseudo-op defines a symbol in the bss section; see +@ref{Lcomm,,@code{.lcomm}}. + +The @code{.comm} pseudo-op may be used to declare a common symbol, which is +another form of uninitialized symbol; see @xref{Comm,,@code{.comm}}. + +@ifset GENERIC +When assembling for a target which supports multiple sections, such as ELF or +COFF, you may switch into the @code{.bss} section and define symbols as usual; +see @ref{Section,,@code{.section}}. You may only assemble zero values into the +section. Typically the section will only contain symbol definitions and +@code{.skip} directives (@pxref{Skip,,@code{.skip}}). +@end ifset @node Symbols @chapter Symbols @@ -2268,7 +2766,7 @@ 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} +@item @kbd{C-A} This unusual character is included so you do not accidentally invent a symbol of the same name. The character has ASCII value @samp{\001}. @@ -2280,8 +2778,8 @@ 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}. +For instance, the first @code{1:} is named @code{L1@kbd{C-A}1}, the 44th +@code{3:} is named @code{L3@kbd{C-A}44}. @node Dot @section The Special Dot Symbol @@ -2643,18 +3141,18 @@ Intermediate precedence Lowest Precedence @table @code -@item + @cindex addition, permitted arguments @cindex plus, permitted arguments @cindex arguments for addition +@item + @dfn{Addition}. If either argument is absolute, the result has the section of the other argument. You may not add together arguments from different sections. -@item - @cindex subtraction, permitted arguments @cindex minus, permitted arguments @cindex arguments for subtraction +@item - @dfn{Subtraction}. If the right argument is absolute, the result has the section of the left argument. If both arguments are in the same section, the result is absolute. @@ -2694,7 +3192,6 @@ Some machine configurations provide additional directives. @end ifset * 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{} * Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}} @@ -2714,25 +3211,43 @@ Some machine configurations provide additional directives. * Double:: @code{.double @var{flonums}} * Eject:: @code{.eject} * Else:: @code{.else} +* Elseif:: @code{.elseif} +* End:: @code{.end} @ifset COFF * Endef:: @code{.endef} @end ifset +* Endfunc:: @code{.endfunc} * Endif:: @code{.endif} * Equ:: @code{.equ @var{symbol}, @var{expression}} +* Equiv:: @code{.equiv @var{symbol}, @var{expression}} +* Err:: @code{.err} +* Exitm:: @code{.exitm} * Extern:: @code{.extern} +* Fail:: @code{.fail} @ifclear no-file-dir * File:: @code{.file @var{string}} @end ifclear * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}} * Float:: @code{.float @var{flonums}} +* Func:: @code{.func} * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}} +@ifset ELF +* Hidden:: @code{.hidden @var{names}} +@end ifset + * hword:: @code{.hword @var{expressions}} * Ident:: @code{.ident} * If:: @code{.if @var{absolute expression}} * Include:: @code{.include "@var{file}"} * Int:: @code{.int @var{expressions}} +@ifset ELF +* Internal:: @code{.internal @var{names}} +@end ifset + +* Irp:: @code{.irp @var{symbol},@var{values}}@dots{} +* Irpc:: @code{.irpc @var{symbol},@var{values}}@dots{} * Lcomm:: @code{.lcomm @var{symbol} , @var{length}} * Lflags:: @code{.lflags} @ifclear no-line-dir @@ -2740,50 +3255,80 @@ Some machine configurations provide additional directives. @end ifclear * Ln:: @code{.ln @var{line-number}} +* Linkonce:: @code{.linkonce [@var{type}]} * List:: @code{.list} * Long:: @code{.long @var{expressions}} @ignore * Lsym:: @code{.lsym @var{symbol}, @var{expression}} @end ignore +* Macro:: @code{.macro @var{name} @var{args}}@dots{} +* MRI:: @code{.mri @var{val}} * Nolist:: @code{.nolist} * Octa:: @code{.octa @var{bignums}} * Org:: @code{.org @var{new-lc} , @var{fill}} * P2align:: @code{.p2align @var{abs-expr} , @var{abs-expr}} +@ifset ELF +* PopSection:: @code{.popsection} +* Previous:: @code{.previous} +@end ifset + +* Print:: @code{.print @var{string}} +@ifset ELF +* Protected:: @code{.protected @var{names}} +@end ifset + * Psize:: @code{.psize @var{lines}, @var{columns}} +* Purgem:: @code{.purgem @var{name}} +@ifset ELF +* PushSection:: @code{.pushsection @var{name}} +@end ifset + * Quad:: @code{.quad @var{bignums}} +* Rept:: @code{.rept @var{count}} * Sbttl:: @code{.sbttl "@var{subheading}"} @ifset COFF * Scl:: @code{.scl @var{class}} -@end ifset -@ifset COFF * Section:: @code{.section @var{name}, @var{subsection}} @end ifset * Set:: @code{.set @var{symbol}, @var{expression}} * Short:: @code{.short @var{expressions}} * Single:: @code{.single @var{flonums}} -@ifset COFF -* Size:: @code{.size} -@end ifset - +* Size:: @code{.size [@var{name} , @var{expression}]} +* Skip:: @code{.skip @var{size} , @var{fill}} +* Sleb128:: @code{.sleb128 @var{expressions}} * Space:: @code{.space @var{size} , @var{fill}} @ifset have-stabs * Stab:: @code{.stabd, .stabn, .stabs} @end ifset * String:: @code{.string "@var{str}"} +* Struct:: @code{.struct @var{expression}} +@ifset ELF +* SubSection:: @code{.subsection} +* Symver:: @code{.symver @var{name},@var{name2@@nodename}} +@end ifset + @ifset COFF * Tag:: @code{.tag @var{structname}} @end ifset * Text:: @code{.text @var{subsection}} * Title:: @code{.title "@var{heading}"} +* Type:: @code{.type <@var{int} | @var{name} , @var{type description}>} +* Uleb128:: @code{.uleb128 @var{expressions}} @ifset COFF -* Type:: @code{.type @var{int}} * Val:: @code{.val @var{addr}} @end ifset +@ifset ELF +* Version:: @code{.version "@var{string}"} +* VTableEntry:: @code{.vtable_entry @var{table}, @var{offset}} +* VTableInherit:: @code{.vtable_inherit @var{child}, @var{parent}} +* Weak:: @code{.weak @var{names}} +@end ifset + * Word:: @code{.word @var{expressions}} * Deprecated:: Deprecated Directives @end menu @@ -2814,25 +3359,38 @@ but ignores it. @end ifset @node Align -@section @code{.align @var{abs-expr} , @var{abs-expr}} +@section @code{.align @var{abs-expr}, @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 -alignment required, as described below. -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. +Pad the location counter (in the current subsection) to a particular storage +boundary. The first expression (which must be absolute) is the alignment +required, as described below. + +The second expression (also absolute) gives the fill value to be stored in the +padding bytes. It (and the comma) may be omitted. If it is omitted, the +padding bytes are normally zero. However, on some systems, if the section is +marked as containing code and the fill value is omitted, the space is filled +with no-op instructions. + +The third expression is also absolute, and is also optional. If it is present, +it is the maximum number of bytes that should be skipped by this alignment +directive. If doing the alignment would require skipping more bytes than the +specified maximum, then the alignment is not done at all. You can omit the +fill value (the second argument) entirely by simply using two commas after the +required alignment; this can be useful if you want the alignment to be filled +with no-op instructions when appropriate. The way the required alignment is specified varies from system to system. -For the a29k, HPPA, m86k, m88k, w65, sparc, and i386 using ELF format, +For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF +format, the first expression is the alignment request in bytes. For example @samp{.align 8} advances the location counter until it is a multiple of 8. If the location counter is already a multiple of 8, no change is needed. -For other systems, including the i386 using a.out format, it is the +For other systems, including the i386 using a.out format, and the arm and +strongarm, it is the number of low-order zero bits the location counter must have after advancement. For example @samp{.align 3} advances the location counter until it a multiple of 8. If the location counter is already a @@ -2844,24 +3402,6 @@ GAS also provides @code{.balign} and @code{.p2align} directives, described later, which have a consistent behavior across all architectures (but are specific to GAS). -@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} -@ifclear no-file-dir -(which may also be spelled @samp{.file}) -@end ifclear -tells @code{@value{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{@value{AS}} -programs.@refill - @node Ascii @section @code{.ascii "@var{string}"}@dots{} @@ -2881,7 +3421,7 @@ trailing zero byte) into consecutive addresses. a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''. @node Balign -@section @code{.balign @var{abs-expr} , @var{abs-expr}} +@section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} @cindex padding the location counter given number of bytes @cindex @code{balign} directive @@ -2891,9 +3431,30 @@ alignment request in bytes. For example @samp{.balign 8} advances the location counter until it is 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. +The second expression (also absolute) gives the fill value to be stored in the +padding bytes. It (and the comma) may be omitted. If it is omitted, the +padding bytes are normally zero. However, on some systems, if the section is +marked as containing code and the fill value is omitted, the space is filled +with no-op instructions. + +The third expression is also absolute, and is also optional. If it is present, +it is the maximum number of bytes that should be skipped by this alignment +directive. If doing the alignment would require skipping more bytes than the +specified maximum, then the alignment is not done at all. You can omit the +fill value (the second argument) entirely by simply using two commas after the +required alignment; this can be useful if you want the alignment to be filled +with no-op instructions when appropriate. + +@cindex @code{balignw} directive +@cindex @code{balignl} directive +The @code{.balignw} and @code{.balignl} directives are variants of the +@code{.balign} directive. The @code{.balignw} directive treats the fill +pattern as a two byte word value. The @code{.balignl} directives treats the +fill pattern as a four byte longword value. For example, @code{.balignw +4,0x368d} will align to a multiple of 4. If it skips two bytes, they will be +filled in with the value 0x368d (the exact placement of the bytes depends upon +the endianness of the processor). If it skips 1 or 3 bytes, the fill value is +undefined. @node Byte @section @code{.byte @var{expressions}} @@ -2908,13 +3469,26 @@ Each expression is assembled into the next byte. @cindex @code{comm} directive @cindex symbol, common -@code{.comm} declares a named common area in the bss section. Normally -@code{@value{LD}} reserves memory addresses for it during linking, so no partial -program defines the location of the symbol. Use @code{.comm} to tell -@code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}} -allocates 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. +@code{.comm} declares a common symbol named @var{symbol}. When linking, a +common symbol in one object file may be merged with a defined or common symbol +of the same name in another object file. If @code{@value{LD}} does not see a +definition for the symbol--just one or more common symbols--then it will +allocate @var{length} bytes of uninitialized memory. @var{length} must be an +absolute expression. If @code{@value{LD}} sees multiple common symbols with +the same name, and they do not all have the same size, it will allocate space +using the largest size. + +@ifset ELF +When using ELF, the @code{.comm} directive takes an optional third argument. +This is the desired alignment of the symbol, specified as a byte boundary (for +example, an alignment of 16 means that the least significant 4 bits of the +address should be zero). The alignment must be an absolute expression, and it +must be a power of two. If @code{@value{LD}} allocates uninitialized memory +for the common symbol, it will use the alignment when placing the symbol. If +no alignment is specified, @code{@value{AS}} will set the alignment to the +largest power of two less than or equal to the size of the symbol, up to a +maximum of 16. +@end ifset @ifset HPPA The syntax for @code{.comm} differs slightly on the HPPA. The syntax is @@ -3019,15 +3593,20 @@ 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. -@ignore -@node End, Endef, Else, Pseudo Ops +@node Elseif +@section @code{.elseif} + +@cindex @code{elseif} directive +@code{.elseif} is part of the @code{@value{AS}} support for conditional +assembly; @pxref{If,,@code{.if}}. It is shorthand for beginning a new +@code{.if} block that would otherwise fill the entire @code{.else} section. + +@node End @section @code{.end} @cindex @code{end} directive -This doesn't do anything---but isn't an s_ignore, so I suspect it's -meant to do something eventually (which is why it isn't documented here -as "for compatibility with blah"). -@end ignore +@code{.end} marks the end of the assembly file. @code{@value{AS}} does not +process anything in the file past the @code{.end} directive. @ifset COFF @node Endef @@ -3044,6 +3623,11 @@ directive but ignores it. @end ifset @end ifset +@node Endfunc +@section @code{.endfunc} +@cindex @code{endfunc} directive +@code{.endfunc} marks the end of a function specified with @code{.func}. + @node Endif @section @code{.endif} @@ -3066,6 +3650,31 @@ The syntax for @code{equ} on the HPPA is @samp{@var{symbol} .equ @var{expression}}. @end ifset +@node Equiv +@section @code{.equiv @var{symbol}, @var{expression}} +@cindex @code{equiv} directive +The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that +the assembler will signal an error if @var{symbol} is already defined. + +Except for the contents of the error message, this is roughly equivalent to +@smallexample +.ifdef SYM +.err +.endif +.equ SYM,VAL +@end smallexample + +@node Err +@section @code{.err} +@cindex @code{err} directive +If @code{@value{AS}} assembles a @code{.err} directive, it will print an error +message and, unless the @code{-Z} option was used, it will not generate an +object file. This can be used to signal error an conditionally compiled code. + +@node Exitm +@section @code{.exitm} +Exit early from the current macro definition. @xref{Macro}. + @node Extern @section @code{.extern} @@ -3074,6 +3683,16 @@ The syntax for @code{equ} on the HPPA is with other assemblers---but it is ignored. @code{@value{AS}} treats all undefined symbols as external. +@node Fail +@section @code{.fail @var{expression}} + +@cindex @code{fail} directive +Generates an error or a warning. If the value of the @var{expression} is 500 +or more, @code{@value{AS}} will print a warning message. If the value is less +than 500, @code{@value{AS}} will print an error message. The message will +include the value of @var{expression}. This can occasionally be useful inside +complex nested macros or conditional assembly. + @ifclear no-file-dir @node File @section @code{.file @var{string}} @@ -3081,13 +3700,12 @@ all undefined symbols as external. @cindex @code{file} directive @cindex logical file name @cindex file name, logical -@code{.file} (which may also be spelled @samp{.app-file}) tells -@code{@value{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{@value{AS}} programs. +@code{.file} tells @code{@value{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{@value{AS}} programs. @ifset A29K In some configurations of @code{@value{AS}}, @code{.file} has already been removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}. @@ -3136,6 +3754,18 @@ in @sc{ieee} format. @end ifset @end ifclear +@node Func +@section @code{.func @var{name}[,@var{label}]} +@cindex @code{func} directive +@code{.func} emits debugging information to denote function @var{name}, and +is ignored unless the file is assembled with debugging enabled. +Only @samp{--gstabs} is currently supported. +@var{label} is the entry point of the function and if omitted @var{name} +prepended with the @samp{leading char} is used. +@samp{leading char} is usually @code{_} or nothing, depending on the target. +All functions are currently defined to have @code{void} return type. +The function must be terminated with @code{.endfunc}. + @node Global @section @code{.global @var{symbol}}, @code{.globl @var{symbol}} @@ -3156,6 +3786,21 @@ partial programs. You may need the HPPA-only @code{.EXPORT} directive as well. @xref{HPPA Directives,, HPPA Assembler Directives}. @end ifset +@ifset ELF +@node Hidden +@section @code{.hidden @var{names}} + +@cindex @code{.hidden} directive +@cindex Visibility +This one of the ELF visibility directives. The other two are +@pxref{Internal,,@code{.internal}} and @pxref{Protected,,@code{.protected}} + +This directive overrides the named symbols default visibility (which is set by +their binding: local, global or weak). The directive sets the visibility to +@code{hidden} which means that the symbols are not visible to other components. +Such symbols are always considered to be @code{protected} as well. +@end ifset + @node hword @section @code{.hword @var{expressions}} @@ -3198,32 +3843,72 @@ 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}}. +alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}). +If you have several conditions to check, @code{.elseif} may be used to avoid +nesting blocks if/else within each subsequent @code{.else} block. The following variants of @code{.if} are also supported: @table @code -@item .ifdef @var{symbol} @cindex @code{ifdef} directive +@item .ifdef @var{symbol} Assembles the following section of code if the specified @var{symbol} has been defined. -@ignore -@item .ifeqs +@cindex @code{ifc} directive +@item .ifc @var{string1},@var{string2} +Assembles the following section of code if the two strings are the same. The +strings may be optionally quoted with single quotes. If they are not quoted, +the first string stops at the first comma, and the second string stops at the +end of the line. Strings which contain whitespace should be quoted. The +string comparison is case sensitive. + +@cindex @code{ifeq} directive +@item .ifeq @var{absolute expression} +Assembles the following section of code if the argument is zero. + @cindex @code{ifeqs} directive -Not yet implemented. -@end ignore +@item .ifeqs @var{string1},@var{string2} +Another form of @code{.ifc}. The strings must be quoted using double quotes. + +@cindex @code{ifge} directive +@item .ifge @var{absolute expression} +Assembles the following section of code if the argument is greater than or +equal to zero. + +@cindex @code{ifgt} directive +@item .ifgt @var{absolute expression} +Assembles the following section of code if the argument is greater than zero. + +@cindex @code{ifle} directive +@item .ifle @var{absolute expression} +Assembles the following section of code if the argument is less than or equal +to zero. + +@cindex @code{iflt} directive +@item .iflt @var{absolute expression} +Assembles the following section of code if the argument is less than zero. + +@cindex @code{ifnc} directive +@item .ifnc @var{string1},@var{string2}. +Like @code{.ifc}, but the sense of the test is reversed: this assembles the +following section of code if the two strings are not the same. -@item .ifndef @var{symbol} -@itemx ifnotdef @var{symbol} @cindex @code{ifndef} directive @cindex @code{ifnotdef} directive +@item .ifndef @var{symbol} +@itemx .ifnotdef @var{symbol} Assembles the following section of code if the specified @var{symbol} has not been defined. Both spelling variants are equivalent. -@ignore -@item ifnes -Not yet implemented. -@end ignore +@cindex @code{ifne} directive +@item .ifne @var{absolute expression} +Assembles the following section of code if the argument is not equal to zero +(in other words, this is equivalent to @code{.if}). + +@cindex @code{ifnes} directive +@item .ifnes @var{string1},@var{string2} +Like @code{.ifeqs}, but the sense of the test is reversed: this assembles the +following section of code if the two strings are not the same. @end table @node Include @@ -3258,6 +3943,78 @@ integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits @end ifset @end ifclear +@ifset ELF +@node Internal +@section @code{.internal @var{names}} + +@cindex @code{.internal} directive +@cindex Visibility +This one of the ELF visibility directives. The other two are +@pxref{Hidden,,@code{.hidden}} and @pxref{Protected,,@code{.protected}} + +This directive overrides the named symbols default visibility (which is set by +their binding: local, global or weak). The directive sets the visibility to +@code{internal} which means that the symbols are considered to be @code{hidden} +(ie not visible to other components), and that some extra, processor specific +processing must also be performed upon the symbols as well. +@end ifset + +@node Irp +@section @code{.irp @var{symbol},@var{values}}@dots{} + +@cindex @code{irp} directive +Evaluate a sequence of statements assigning different values to @var{symbol}. +The sequence of statements starts at the @code{.irp} directive, and is +terminated by an @code{.endr} directive. For each @var{value}, @var{symbol} is +set to @var{value}, and the sequence of statements is assembled. If no +@var{value} is listed, the sequence of statements is assembled once, with +@var{symbol} set to the null string. To refer to @var{symbol} within the +sequence of statements, use @var{\symbol}. + +For example, assembling + +@example + .irp param,1,2,3 + move d\param,sp@@- + .endr +@end example + +is equivalent to assembling + +@example + move d1,sp@@- + move d2,sp@@- + move d3,sp@@- +@end example + +@node Irpc +@section @code{.irpc @var{symbol},@var{values}}@dots{} + +@cindex @code{irpc} directive +Evaluate a sequence of statements assigning different values to @var{symbol}. +The sequence of statements starts at the @code{.irpc} directive, and is +terminated by an @code{.endr} directive. For each character in @var{value}, +@var{symbol} is set to the character, and the sequence of statements is +assembled. If no @var{value} is listed, the sequence of statements is +assembled once, with @var{symbol} set to the null string. To refer to +@var{symbol} within the sequence of statements, use @var{\symbol}. + +For example, assembling + +@example + .irpc param,123 + move d\param,sp@@- + .endr +@end example + +is equivalent to assembling + +@example + move d1,sp@@- + move d2,sp@@- + move d3,sp@@- +@end example + @node Lcomm @section @code{.lcomm @var{symbol} , @var{length}} @@ -3271,6 +4028,11 @@ section, so that at run-time the bytes start off zeroed. @var{Symbol} is not declared global (@pxref{Global,,@code{.global}}), so is normally not visible to @code{@value{LD}}. +@ifset GENERIC +Some targets permit a third argument to be used with @code{.lcomm}. This +argument specifies the desired alignment of the symbol in the bss section. +@end ifset + @ifset HPPA The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional. @@ -3324,6 +4086,43 @@ used by compilers to generate auxiliary symbol information for debugging. @end ifclear +@node Linkonce +@section @code{.linkonce [@var{type}]} +@cindex COMDAT +@cindex @code{linkonce} directive +@cindex common sections +Mark the current section so that the linker only includes a single copy of it. +This may be used to include the same section in several different object files, +but ensure that the linker will only include it once in the final output file. +The @code{.linkonce} pseudo-op must be used for each instance of the section. +Duplicate sections are detected based on the section name, so it should be +unique. + +This directive is only supported by a few object file formats; as of this +writing, the only object file format which supports it is the Portable +Executable format used on Windows NT. + +The @var{type} argument is optional. If specified, it must be one of the +following strings. For example: +@smallexample +.linkonce same_size +@end smallexample +Not all types may be supported on all object file formats. + +@table @code +@item discard +Silently discard duplicate sections. This is the default. + +@item one_only +Warn if there are duplicate sections, but still keep only one copy. + +@item same_size +Warn if any of the duplicates have different sizes. + +@item same_contents +Warn if any of the duplicates do not have exactly the same contents. +@end table + @node Ln @section @code{.ln @var{line-number}} @@ -3345,6 +4144,16 @@ output format. @end ifset @end ifset +@node MRI +@section @code{.mri @var{val}} + +@cindex @code{mri} directive +@cindex MRI mode, temporarily +If @var{val} is non-zero, this tells @code{@value{AS}} to enter MRI mode. If +@var{val} is zero, this tells @code{@value{AS}} to exit MRI mode. This change +affects code assembled until the next @code{.mri} directive, or until the end +of the file. @xref{M, MRI mode, MRI mode}. + @node List @section @code{.list} @@ -3387,6 +4196,99 @@ the same as the expression value: The new symbol is not flagged as external. @end ignore +@node Macro +@section @code{.macro} + +@cindex macros +The commands @code{.macro} and @code{.endm} allow you to define macros that +generate assembly output. For example, this definition specifies a macro +@code{sum} that puts a sequence of numbers into memory: + +@example + .macro sum from=0, to=5 + .long \from + .if \to-\from + sum "(\from+1)",\to + .endif + .endm +@end example + +@noindent +With that definition, @samp{SUM 0,5} is equivalent to this assembly input: + +@example + .long 0 + .long 1 + .long 2 + .long 3 + .long 4 + .long 5 +@end example + +@ftable @code +@item .macro @var{macname} +@itemx .macro @var{macname} @var{macargs} @dots{} +@cindex @code{macro} directive +Begin the definition of a macro called @var{macname}. If your macro +definition requires arguments, specify their names after the macro name, +separated by commas or spaces. You can supply a default value for any +macro argument by following the name with @samp{=@var{deflt}}. For +example, these are all valid @code{.macro} statements: + +@table @code +@item .macro comm +Begin the definition of a macro called @code{comm}, which takes no +arguments. + +@item .macro plus1 p, p1 +@itemx .macro plus1 p p1 +Either statement begins the definition of a macro called @code{plus1}, +which takes two arguments; within the macro definition, write +@samp{\p} or @samp{\p1} to evaluate the arguments. + +@item .macro reserve_str p1=0 p2 +Begin the definition of a macro called @code{reserve_str}, with two +arguments. The first argument has a default value, but not the second. +After the definition is complete, you can call the macro either as +@samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to +@var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str +,@var{b}} (with @samp{\p1} evaluating as the default, in this case +@samp{0}, and @samp{\p2} evaluating to @var{b}). +@end table + +When you call a macro, you can specify the argument values either by +position, or by keyword. For example, @samp{sum 9,17} is equivalent to +@samp{sum to=17, from=9}. + +@item .endm +@cindex @code{endm} directive +Mark the end of a macro definition. + +@item .exitm +@cindex @code{exitm} directive +Exit early from the current macro definition. + +@cindex number of macros executed +@cindex macros, count executed +@item \@@ +@code{@value{AS}} maintains a counter of how many macros it has +executed in this pseudo-variable; you can copy that number to your +output with @samp{\@@}, but @emph{only within a macro definition}. + +@ignore +@item LOCAL @var{name} [ , @dots{} ] +@emph{Warning: @code{LOCAL} is only available if you select ``alternate +macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,, +Alternate macro syntax}. + +Generate a string replacement for each of the @var{name} arguments, and +replace any instances of @var{name} in each macro expansion. The +replacement string is unique in the assembly, and different for each +separate macro expansion. @code{LOCAL} allows you to write macros that +define symbols, without fear of conflict between separate macro expansions. +@end ignore +@end ftable + @node Nolist @section @code{.nolist} @@ -3433,7 +4335,7 @@ 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 +@c section. doc@cygnus.com 18feb91 Because @code{@value{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. @@ -3448,7 +4350,7 @@ absolute expression. If the comma and @var{fill} are omitted, @var{fill} defaults to zero. @node P2align -@section @code{.p2align @var{abs-expr} , @var{abs-expr}} +@section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} @cindex padding the location counter given a power of two @cindex @code{p2align} directive @@ -3459,9 +4361,88 @@ advancement. For example @samp{.p2align 3} advances 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. +The second expression (also absolute) gives the fill value to be stored in the +padding bytes. It (and the comma) may be omitted. If it is omitted, the +padding bytes are normally zero. However, on some systems, if the section is +marked as containing code and the fill value is omitted, the space is filled +with no-op instructions. + +The third expression is also absolute, and is also optional. If it is present, +it is the maximum number of bytes that should be skipped by this alignment +directive. If doing the alignment would require skipping more bytes than the +specified maximum, then the alignment is not done at all. You can omit the +fill value (the second argument) entirely by simply using two commas after the +required alignment; this can be useful if you want the alignment to be filled +with no-op instructions when appropriate. + +@cindex @code{p2alignw} directive +@cindex @code{p2alignl} directive +The @code{.p2alignw} and @code{.p2alignl} directives are variants of the +@code{.p2align} directive. The @code{.p2alignw} directive treats the fill +pattern as a two byte word value. The @code{.p2alignl} directives treats the +fill pattern as a four byte longword value. For example, @code{.p2alignw +2,0x368d} will align to a multiple of 4. If it skips two bytes, they will be +filled in with the value 0x368d (the exact placement of the bytes depends upon +the endianness of the processor). If it skips 1 or 3 bytes, the fill value is +undefined. + +@ifset ELF +@node Previous +@section @code{.previous} + +@cindex @code{.previous} directive +@cindex Section Stack +This is one of the ELF section stack manipulation directives. The others are +@pxref{Section}, @xref{SubSection}, @pxref{PushSection}, and +@pxref{PopSection}. + +This directive swaps the current section (and subsection) with most recently +referenced section (and subsection) prior to this one. Multiple +@code{.previous} directives in a row will flip between two sections (and their +subsections). + +In terms of the section stack, this directive swaps the current section with +the top section on the section stack. +@end ifset + +@ifset ELF +@node PopSection +@section @code{.popsection} + +@cindex @code{.popsection} directive +@cindex Section Stack +This is one of the ELF section stack manipulation directives. The others are +@pxref{Section}, @xref{SubSection}, @pxref{PushSection}, and +@pxref{Previous}. + +This directive replaces the current section (and subsection) with the top +section (and subsection) on the section stack. This section is popped off the +stack. +@end ifset + +@node Print +@section @code{.print @var{string}} + +@cindex @code{print} directive +@code{@value{AS}} will print @var{string} on the standard output during +assembly. You must put @var{string} in double quotes. + +@ifset ELF +@node Protected +@section @code{.protected @var{names}} + +@cindex @code{.protected} directive +@cindex Visibility +This one of the ELF visibility directives. The other two are +@pxref{Hidden} and @pxref{Internal} + +This directive overrides the named symbols default visibility (which is set by +their binding: local, global or weak). The directive sets the visibility to +@code{protected} which means that any references to the symbols from within the +components that defines them must be resolved to the definition in that +component, even if a definition in another component would normally preempt +this. +@end ifset @node Psize @section @code{.psize @var{lines} , @var{columns}} @@ -3483,6 +4464,28 @@ lines is exceeded (or whenever you explicitly request one, using If you specify @var{lines} as @code{0}, no formfeeds are generated save those explicitly specified with @code{.eject}. +@node Purgem +@section @code{.purgem @var{name}} + +@cindex @code{purgem} directive +Undefine the macro @var{name}, so that later uses of the string will not be +expanded. @xref{Macro}. + +@ifset ELF +@node PushSection +@section @code{.pushsection @var{name} , @var{subsection}} + +@cindex @code{.pushsection} directive +@cindex Section Stack +This is one of the ELF section stack manipulation directives. The others are +@pxref{Section}, @xref{SubSection}, @pxref{PopSection}, and +@pxref{Previous}. + +This directive is a synonym for @code{.section}. It psuhes the current section +(and subsection) onto the top of the section stack, and then replaces the +current section and subsection with @code{name} and @code{subsection}. +@end ifset + @node Quad @section @code{.quad @var{bignums}} @@ -3505,6 +4508,29 @@ warning message; and just takes the lowest order 16 bytes of the bignum. @cindex integer, 16-byte @end ifset +@node Rept +@section @code{.rept @var{count}} + +@cindex @code{rept} directive +Repeat the sequence of lines between the @code{.rept} directive and the next +@code{.endr} directive @var{count} times. + +For example, assembling + +@example + .rept 3 + .long 0 + .endr +@end example + +is equivalent to assembling + +@example + .long 0 + .long 0 + .long 0 +@end example + @node Sbttl @section @code{.sbttl "@var{subheading}"} @@ -3536,25 +4562,117 @@ accepts this directive but ignores it. @end ifset @end ifset -@ifset COFF @node Section -@section @code{.section @var{name}, @var{subsection}} +@section @code{.section @var{name}} (COFF version) @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{@value{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. -@ifset GENERIC +@cindex named section +Use the @code{.section} directive to assemble the following code into a section +named @var{name}. + This directive is only supported for targets that actually support arbitrarily named sections; on @code{a.out} targets, for example, it is not accepted, even -with a standard @code{a.out} section name as its parameter. -@end ifset +with a standard @code{a.out} section name. + +For COFF targets, the @code{.section} directive is used in one of the following +ways: + +@smallexample +.section @var{name}[, "@var{flags}"] +.section @var{name}[, @var{subsegment}] +@end smallexample + +If the optional argument is quoted, it is taken as flags to use for the +section. Each flag is a single character. The following flags are recognized: +@table @code +@item b +bss section (uninitialized data) +@item n +section is not loaded +@item w +writable section +@item d +data section +@item r +read-only section +@item x +executable section +@item s +shared section (meaningful for PE targets) +@end table + +If no flags are specified, the default flags depend upon the section name. If +the section name is not recognized, the default will be for the section to be +loaded and writable. + +If the optional argument to the @code{.section} directive is not quoted, it is +taken as a subsegment number (@pxref{Sub-Sections}). + + +@section @code{.section @var{name}} (ELF version) + +@cindex @code{section} directive +@cindex named section +@ifset ELF +@cindex Section Stack +This is one of the ELF section stack manipulation directives. The others are +@xref{SubSection}, @pxref{PushSection}@pxref{PopSection}, and +@pxref{Previous}. @end ifset +For ELF targets, the @code{.section} directive is used like this: + +@smallexample +.section @var{name} [, "@var{flags}"[, @@@var{type}]] +@end smallexample + +The optional @var{flags} argument is a quoted string which may contain any +combintion of the following characters: +@table @code +@item a +section is allocatable +@item w +section is writable +@item x +section is executable +@end table + +The optional @var{type} argument may contain one of the following constants: +@table @code +@item @@progbits +section contains data +@item @@nobits +section does not contain data (i.e., section only occupies space) +@end table + +If no flags are specified, the default flags depend upon the section name. If +the section name is not recognized, the default will be for the section to have +none of the above flags: it will not be allocated in memory, nor writable, nor +executable. The section will contain data. + +For ELF targets, the assembler supports another type of @code{.section} +directive for compatibility with the Solaris assembler: + +@smallexample +.section "@var{name}"[, @var{flags}...] +@end smallexample + +Note that the section name is quoted. There may be a sequence of comma +separated flags: +@table @code +@item #alloc +section is allocatable +@item #write +section is writable +@item #execinstr +section is executable +@end table + +This directive replaces the current section and subsection. The replaced +section and subsection are pushed onto the section stack. See the contents of +the gas testsuite directory @code{gas/testsuite/gas/elf} for some examples of +how this directive and the other section stack directives work. + @node Set @section @code{.set @var{symbol}, @var{expression}} @@ -3563,7 +4681,7 @@ with a standard @code{a.out} section name as its parameter. Set the value of @var{symbol} to @var{expression}. This changes @var{symbol}'s value and type to conform to @var{expression}. If @var{symbol} was flagged as external, it remains -flagged. (@xref{Symbol Attributes}.) +flagged (@pxref{Symbol Attributes}). You may @code{.set} a symbol many times in the same assembly. @@ -3614,23 +4732,47 @@ numbers in @sc{ieee} format. @end ifset @end ifclear -@ifset COFF @node Size -@section @code{.size} +@section @code{.size} (COFF version) @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. -@ifset BOUT +@ifset BOUT @samp{.size} is only meaningful when generating COFF format output; when @code{@value{AS}} is generating @code{b.out}, it accepts this directive but ignores it. @end ifset -@end ifset + +@section @code{.size @var{name} , @var{expression}} (ELF version) +@cindex @code{size} directive + +This directive is used to set the size associated with a symbol @var{name}. +The size in bytes is computed from @var{expression} which can make use of label +arithmetic. This directive is typically used to set the size of function +symbols. + +@node Sleb128 +@section @code{.sleb128 @var{expressions}} + +@cindex @code{sleb128} directive +@var{sleb128} stands for ``signed little endian base 128.'' This is a +compact, variable length representation of numbers used by the DWARF +symbolic debugging format. @xref{Uleb128,@code{.uleb128}}. @ifclear no-space-dir +@node Skip +@section @code{.skip @var{size} , @var{fill}} + +@cindex @code{skip} 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. This is the same as +@samp{.space}. + @node Space @section @code{.space @var{size} , @var{fill}} @@ -3638,7 +4780,8 @@ ignores it. @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. +and @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same +as @samp{.skip}. @ifset HPPA @quotation @@ -3721,12 +4864,12 @@ relocatably. When your program is linked, the value of this symbol is the address of the location counter when the @code{.stabd} was assembled. -@item .stabn @var{type} , @var{other} , @var{desc} , @var{value} @cindex @code{stabn} directive +@item .stabn @var{type} , @var{other} , @var{desc} , @var{value} 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 +@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value} All five fields are specified. @end table @end ifset @@ -3743,6 +4886,97 @@ one string to copy, separated by commas. Unless otherwise specified for a particular machine, the assembler marks the end of each string with a 0 byte. You can use any of the escape sequences described in @ref{Strings,,Strings}. +@node Struct +@section @code{.struct @var{expression}} + +@cindex @code{struct} directive +Switch to the absolute section, and set the section offset to @var{expression}, +which must be an absolute expression. You might use this as follows: +@smallexample + .struct 0 +field1: + .struct field1 + 4 +field2: + .struct field2 + 4 +field3: +@end smallexample +This would define the symbol @code{field1} to have the value 0, the symbol +@code{field2} to have the value 4, and the symbol @code{field3} to have the +value 8. Assembly would be left in the absolute section, and you would need to +use a @code{.section} directive of some sort to change to some other section +before further assembly. + +@ifset ELF +@node SubSection +@section @code{.subsection @var{name}} + +@cindex @code{.subsection} directive +@cindex Section Stack +This is one of the ELF section stack manipulation directives. The others are +@pxref{Section}, @xref{PushSection}, @pxref{PopSection}, and +@pxref{Previous}. + +This directive replaces the current subsection with @code{name}. The current +section is not changed. The replaced subsection is put onto the section stack +in place of the then current top of stack subsection. +@end ifset + +@ifset ELF +@node Symver +@section @code{.symver} +@cindex @code{symver} directive +@cindex symbol versioning +@cindex versions of symbols +Use the @code{.symver} directive to bind symbols to specific version nodes +within a source file. This is only supported on ELF platforms, and is +typically used when assembling files to be linked into a shared library. +There are cases where it may make sense to use this in objects to be bound +into an application itself so as to override a versioned symbol from a +shared library. + +For ELF targets, the @code{.symver} directive can be used like this: +@smallexample +.symver @var{name}, @var{name2@@nodename} +@end smallexample +If the symbol @var{name} is defined within the file +being assembled, the @code{.symver} directive effectively creates a symbol +alias with the name @var{name2@@nodename}, and in fact the main reason that we +just don't try and create a regular alias is that the @var{@@} character isn't +permitted in symbol names. The @var{name2} part of the name is the actual name +of the symbol by which it will be externally referenced. The name @var{name} +itself is merely a name of convenience that is used so that it is possible to +have definitions for multiple versions of a function within a single source +file, and so that the compiler can unambiguously know which version of a +function is being mentioned. The @var{nodename} portion of the alias should be +the name of a node specified in the version script supplied to the linker when +building a shared library. If you are attempting to override a versioned +symbol from a shared library, then @var{nodename} should correspond to the +nodename of the symbol you are trying to override. + +If the symbol @var{name} is not defined within the file being assembled, all +references to @var{name} will be changed to @var{name2@@nodename}. If no +reference to @var{name} is made, @var{name2@@nodename} will be removed from the +symbol table. + +Another usage of the @code{.symver} directive is: +@smallexample +.symver @var{name}, @var{name2@@@@nodename} +@end smallexample +In this case, the symbol @var{name} must exist and be defined within +the file being assembled. It is similiar to @var{name2@@nodename}. The +difference is @var{name2@@@@nodename} will also be used to resolve +references to @var{name2} by the linker. + +The third usage of the @code{.symver} directive is: +@smallexample +.symver @var{name}, @var{name2@@@@@@nodename} +@end smallexample +When @var{name} is not defined within the +file being assembled, it is treated as @var{name2@@nodename}. When +@var{name} is defined within the file being assembled, the symbol +name, @var{name}, will be changed to @var{name2@@@@nodename}. +@end ifset + @ifset COFF @node Tag @section @code{.tag @var{structname}} @@ -3782,22 +5016,55 @@ 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. -@ifset COFF @node Type -@section @code{.type @var{int}} +@section @code{.type @var{int}} (COFF version) @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. -@ifset BOUT +@ifset BOUT @samp{.type} is associated only with COFF format output; when @code{@value{AS}} is configured for @code{b.out} output, it accepts this directive but ignores it. @end ifset -@end ifset + +@section @code{.type @var{name} , @var{type description}} (ELF version) + +@cindex ELF symbol type +@cindex symbol type, ELF +@cindex @code{type} directive +This directive is used to set the type of symbol @var{name} to be either a +function symbol or an ojbect symbol. There are five different syntaxes +supported for the @var{type description} field, in order to provide +comptability with various other assemblers. The syntaxes supported are: + +@smallexample + .type ,#function + .type ,#object + + .type ,@@function + .type ,@@object + + .type ,%function + .type ,%object + + .type ,"function" + .type ,"object" + + .type STT_FUNCTION + .type STT_OBJECT +@end smallexample + +@node Uleb128 +@section @code{.uleb128 @var{expressions}} + +@cindex @code{uleb128} directive +@var{uleb128} stands for ``unsigned little endian base 128.'' This is a +compact, variable length representation of numbers used by the DWARF +symbolic debugging format. @xref{Sleb128,@code{.sleb128}}. @ifset COFF @node Val @@ -3816,6 +5083,42 @@ configured for @code{b.out}, it accepts this directive but ignores it. @end ifset @end ifset +@ifset ELF +@node Version +@section @code{.version "@var{string}"} + +@cindex @code{.version} +This directive creates a @code{.note} section and places into it an ELF +formatted note of type NT_VERSION. The note's name is set to @code{string}. +@end ifset + +@ifset ELF +@node VTableEntry +@section @code{.vtable_entry @var{table}, @var{offset}} + +@cindex @code{.vtable_entry} +This directive finds or creates a symbol @code{table} and creates a +@code{VTABLE_ENTRY} relocation for it with an addend of @code{offset}. + +@node VTableInherit +@section @code{.vtable_inherit @var{child}, @var{parent}} + +@cindex @code{.vtable_inherit} +This directive finds the symbol @code{child} and finds or creates the symbol +@code{parent} and then creates a @code{VTABLE_INHERIT} relocation for the +parent whoes addend is the value of the child symbol. As a special case the +parent name of @code{0} is treated as refering the @code{*ABS*} section. +@end ifset + +@ifset ELF +@node Weak +@section @code{.weak @var{names}} + +@cindex @code{.weak} +This directive sets the weak attribute on the comma seperated list of symbol +@code{names}. If the symbols do not already exist, they will be created. +@end ifset + @node Word @section @code{.word @var{expressions}} @@ -3891,7 +5194,6 @@ 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 @@ -3913,16 +5215,20 @@ include details on any machine's instruction set. For details on that subject, see the hardware manufacturer's manual. @menu -@c start-sanitize-arc +@ifset A29K +* AMD29K-Dependent:: AMD 29K Dependent Features +@end ifset @ifset ARC * ARC-Dependent:: ARC Dependent Features @end ifset -@c end-sanitize-arc -@ifset VAX -* Vax-Dependent:: VAX Dependent Features +@ifset ARM +* ARM-Dependent:: ARM Dependent Features @end ifset -@ifset A29K -* AMD29K-Dependent:: AMD 29K Dependent Features +@ifset D10V +* D10V-Dependent:: D10V Dependent Features +@end ifset +@ifset D30V +* D30V-Dependent:: D30V Dependent Features @end ifset @ifset H8/300 * H8/300-Dependent:: Hitachi H8/300 Dependent Features @@ -3933,26 +5239,50 @@ subject, see the hardware manufacturer's manual. @ifset HPPA * HPPA-Dependent:: HPPA Dependent Features @end ifset -@ifset SH -* SH-Dependent:: Hitachi SH Dependent Features +@ifset I370 +* ESA/390-Dependent:: IBM ESA/390 Dependent Features @end ifset -@ifset I960 +@ifset I80386 +* i386-Dependent:: Intel 80386 Dependent Features +@end ifset +@ifset I860 +* i860-Dependent:: Intel 80860 Dependent Features +@end ifset +@ifset I960 * i960-Dependent:: Intel 80960 Dependent Features @end ifset +@ifset M32R +* M32R-Dependent:: M32R Dependent Features +@end ifset @ifset M680X0 * M68K-Dependent:: M680x0 Dependent Features @end ifset +@ifset M68HC11 +* M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features +@end ifset +@ifset MIPS +* MIPS-Dependent:: MIPS Dependent Features +@end ifset +@ifset SH +* SH-Dependent:: Hitachi SH Dependent Features +@end ifset +@ifset PJ +* PJ-Dependent:: picoJava Dependent Features +@end ifset @ifset SPARC * Sparc-Dependent:: SPARC Dependent Features @end ifset +@ifset TIC54X +* TIC54X-Dependent:: TI TMS320C54x Dependent Features +@end ifset +@ifset V850 +* V850-Dependent:: V850 Dependent Features +@end ifset @ifset Z8000 * Z8000-Dependent:: Z8000 Dependent Features @end ifset -@ifset MIPS -* MIPS-Dependent:: MIPS Dependent Features -@end ifset -@ifset I80386 -* i386-Dependent:: 80386 Dependent Features +@ifset VAX +* Vax-Dependent:: VAX Dependent Features @end ifset @end menu @@ -3967,7 +5297,6 @@ subject, see the hardware manufacturer's manual. @c node and sectioning commands; hence the repetition of @chapter BLAH @c in both conditional blocks. -@c start-sanitize-arc @ifset ARC @ifset GENERIC @page @@ -3998,7 +5327,8 @@ variants) of chip, using the same core instruction set, but including a few additional instructions at each level. By default, @code{@value{AS}} assumes the core instruction set (ARC -base). The @code{.cpu} pseudo-op is used to select a different variant. +base). The @code{.cpu} pseudo-op is intended to be used to select +the variant. @table @code @cindex @code{-mbig-endian} option (ARC) @@ -4036,515 +5366,22 @@ machine directives: @table @code @item .cpu @cindex @code{cpu} directive, SPARC -This must be followed by the desired cpu. It must be one of -@code{base}, @code{host}, @code{graphics}, or @code{audio}. - -@end table - -@end ifset -@c end-sanitize-arc - -@ifset VAX -@ifset GENERIC -@node Vax-Dependent -@chapter VAX Dependent Features -@cindex VAX support - -@end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter VAX Dependent Features -@cindex VAX support +This must be followed by the desired cpu. +The ARC is intended to be customizable, @code{.cpu} is used to +select the desired variant [though currently there are none]. -@end ifclear - -@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 -@section VAX Command-Line Options - -@cindex command-line options ignored, VAX -@cindex VAX command-line options ignored -The Vax version of @code{@value{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 @code -@item @code{-D} (Debug) -@itemx @code{-S} (Symbol Table) -@itemx @code{-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 @code{-d} (Displacement size for JUMPs) -@cindex @code{-d}, VAX option -This option expects a number following the @samp{-d}. Like options -that expect filenames, the number may immediately follow the -@samp{-d} (old standard) or constitute the whole of the command line -argument that follows @samp{-d} (@sc{gnu} standard). - -@item @code{-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{@value{AS}} always does this, so this -option is redundant. - -@item @code{-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 @code{-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. Since @code{@value{AS}} does not use a temporary disk file, this -option makes no difference. @samp{-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 @samp{-h}, and @samp{-+}. The -@samp{-h} option prevents @code{@value{AS}} from modifying the -symbol-table entries for symbols that contain lowercase -characters (I think). The @samp{-+} option causes @code{@value{AS}} to -print warning messages if the FILENAME part of the object file, -or any symbol name is larger than 31 characters. The @samp{-+} -option also inserts some code following the @samp{_main} -symbol so that the object file is compatible with Vax-11 -"C". - -@node VAX-float -@section 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 -@section 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 -@section 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 -@section 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 -reaches 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 do not need this feature, avoid 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 -@section 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}. Upper and lower case letters are equivalent. - -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 -@section Not Supported on VAX - -@cindex VAX bitfields not supported -@cindex bitfields, not supported on VAX -Vax bit fields can not be assembled with @code{@value{AS}}. Someone -can add the required code if they really need it. - @end ifset @ifset A29K -@ifset GENERIC -@page -@node AMD29K-Dependent -@chapter AMD 29K Dependent Features +@include c-a29k.texi @end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter AMD 29K Dependent Features -@end ifclear - -@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 -@section Options -@cindex AMD 29K options (none) -@cindex options for AMD29K (none) -@code{@value{AS}} has no additional command-line options for the AMD -29K family. - -@node AMD29K Syntax -@section Syntax -@menu -* AMD29K-Chars:: Special Characters -* AMD29K-Regs:: Register Names -@end menu - -@node AMD29K-Chars -@subsection 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 -@subsection 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{@value{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 -@section 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 -@section 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 @sc{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 @sc{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 -@section Opcodes - -@cindex AMD 29K opcodes -@cindex opcodes for AMD 29K -@code{@value{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. +@ifset ARM +@include c-arm.texi @end ifset + @ifset Hitachi-all @ifclear GENERIC @node Machine Dependencies @@ -4564,3038 +5401,347 @@ family. @end ifclear @end ifset -@ifset H8/300 -@ifset GENERIC -@page +@ifset D10V +@include c-d10v.texi @end ifset -@node H8/300-Dependent -@chapter 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 +@ifset D30V +@include c-d30v.texi +@end ifset -@node H8/300 Options -@section Options +@ifset H8/300 +@include c-h8300.texi +@end ifset -@cindex H8/300 options (none) -@cindex options, H8/300 (none) -@code{@value{AS}} has no additional command-line options for the Hitachi -H8/300 family. +@ifset H8/500 +@include c-h8500.texi +@end ifset -@node H8/300 Syntax -@section Syntax -@menu -* H8/300-Chars:: Special Characters -* H8/300-Regs:: Register Names -* H8/300-Addressing:: Addressing Modes -@end menu +@ifset HPPA +@include c-hppa.texi +@end ifset -@node H8/300-Chars -@subsection 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 -@subsection Register Names - -@cindex H8/300 registers -@cindex register names, 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). - -On the H8/300H, you can also use the eight predefined symbols -@samp{er@var{n}} (@samp{er0} @dots{} @samp{er7}) to refer to the 32-bit -general purpose registers. - -The two control registers are called @code{pc} (program counter; a -16-bit register, except on the H8/300H where it is 24 bits) 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 -@subsection Addressing Modes - -@cindex addressing modes, H8/300 -@cindex H8/300 addressing modes -@value{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}) -@itemx @@(@var{d}:24, r@var{n}) -Register indirect: 16-bit or 24-bit displacement @var{d} from register -@var{n}. (24-bit displacements are only meaningful on the H8/300H.) - -@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 -@itemx @code{@@}@var{aa}:24 -Absolute address @code{aa}. (The address size @samp{:24} only makes -sense on the H8/300H.) - -@item #@var{xx} -@itemx #@var{xx}:8 -@itemx #@var{xx}:16 -@itemx #@var{xx}:32 -Immediate data @var{xx}. You may specify the @samp{:8}, @samp{:16}, or -@samp{:32} for clarity, if you wish; but @code{@value{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{@value{AS}} neither requires this nor uses it. -@end table +@ifset I370 +@include c-i370.texi +@end ifset -@node H8/300 Floating Point -@section Floating Point +@ifset I80386 +@include c-i386.texi +@end ifset -@cindex floating point, H8/300 (@sc{ieee}) -@cindex H8/300 floating point (@sc{ieee}) -The H8/300 family has no hardware floating point, but the @code{.float} -directive generates @sc{ieee} floating-point numbers for compatibility -with other development tools. +@ifset I860 +@include c-i860.texi +@end ifset -@page -@node H8/300 Directives -@section H8/300 Machine Directives +@ifset I960 +@include c-i960.texi +@end ifset -@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{@value{AS}} has only one machine-dependent directive for the -H8/300: +@ifset M32R +@include c-m32r.texi +@end ifset -@table @code -@cindex H8/300H, assembling for -@item .h8300h -Recognize and emit additional instructions for the H8/300H variant, and -also make @code{.int} emit 32-bit numbers rather than the usual (16-bit) -for the H8/300 family. -@end table +@ifset M680X0 +@include c-m68k.texi +@end ifset -On the H8/300 family (including the H8/300H) @samp{.word} directives -generate 16-bit numbers. +@ifset M68HC11 +@include c-m68hc11.texi +@end ifset -@node H8/300 Opcodes -@section Opcodes +@ifset MIPS +@include c-mips.texi +@end ifset -@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). For -information specific to the H8/300H, see @cite{H8/300H Series -Programming Manual} (Hitachi). +@ifset NS32K +@include c-ns32k.texi +@end ifset -@code{@value{AS}} implements all the standard H8/300 opcodes. No additional -pseudo-instructions are needed on this family. +@ifset PJ +@include c-pj.texi +@end ifset -@ifset SMALL -@c this table, due to the multi-col faking and hardcoded order, looks silly -@c except in smallbook. See comments below "@set SMALL" near top of this file. +@ifset SH +@include c-sh.texi +@end ifset -The following table summarizes the H8/300 opcodes, and their arguments. -Entries marked @samp{*} are opcodes used only on the H8/300H. +@ifset SPARC +@include c-sparc.texi +@end ifset -@smallexample -@c Using @group seems to use the normal baselineskip, not the smallexample -@c baselineskip; looks approx doublespaced. - @i{Legend:} - Rs @r{source register} - Rd @r{destination register} - abs @r{absolute address} - imm @r{immediate data} - disp:N @r{N-bit displacement from a register} - pcrel:N @r{N-bit displacement relative to program counter} - - add.b #imm,rd * andc #imm,ccr - add.b rs,rd band #imm,rd - add.w rs,rd band #imm,@@rd -* add.w #imm,rd band #imm,@@abs:8 -* add.l rs,rd bra pcrel:8 -* add.l #imm,rd * bra pcrel:16 - adds #imm,rd bt pcrel:8 - addx #imm,rd * bt pcrel:16 - addx rs,rd brn pcrel:8 - and.b #imm,rd * brn pcrel:16 - and.b rs,rd bf pcrel:8 -* and.w rs,rd * bf pcrel:16 -* and.w #imm,rd bhi pcrel:8 -* and.l #imm,rd * bhi pcrel:16 -* and.l rs,rd bls pcrel:8 -@page -* bls pcrel:16 bld #imm,rd - bcc pcrel:8 bld #imm,@@rd -* bcc pcrel:16 bld #imm,@@abs:8 - bhs pcrel:8 bnot #imm,rd -* bhs pcrel:16 bnot #imm,@@rd - bcs pcrel:8 bnot #imm,@@abs:8 -* bcs pcrel:16 bnot rs,rd - blo pcrel:8 bnot rs,@@rd -* blo pcrel:16 bnot rs,@@abs:8 - bne pcrel:8 bor #imm,rd -* bne pcrel:16 bor #imm,@@rd - beq pcrel:8 bor #imm,@@abs:8 -* beq pcrel:16 bset #imm,rd - bvc pcrel:8 bset #imm,@@rd -* bvc pcrel:16 bset #imm,@@abs:8 - bvs pcrel:8 bset rs,rd -* bvs pcrel:16 bset rs,@@rd - bpl pcrel:8 bset rs,@@abs:8 -* bpl pcrel:16 bsr pcrel:8 - bmi pcrel:8 bsr pcrel:16 -* bmi pcrel:16 bst #imm,rd - bge pcrel:8 bst #imm,@@rd -* bge pcrel:16 bst #imm,@@abs:8 - blt pcrel:8 btst #imm,rd -* blt pcrel:16 btst #imm,@@rd - bgt pcrel:8 btst #imm,@@abs:8 -* bgt pcrel:16 btst rs,rd - ble pcrel:8 btst rs,@@rd -* ble pcrel:16 btst rs,@@abs:8 - bclr #imm,rd bxor #imm,rd - bclr #imm,@@rd bxor #imm,@@rd - bclr #imm,@@abs:8 bxor #imm,@@abs:8 - bclr rs,rd cmp.b #imm,rd - bclr rs,@@rd cmp.b rs,rd - bclr rs,@@abs:8 cmp.w rs,rd - biand #imm,rd cmp.w rs,rd - biand #imm,@@rd * cmp.w #imm,rd - biand #imm,@@abs:8 * cmp.l #imm,rd - bild #imm,rd * cmp.l rs,rd - bild #imm,@@rd daa rs - bild #imm,@@abs:8 das rs - bior #imm,rd dec.b rs - bior #imm,@@rd * dec.w #imm,rd - bior #imm,@@abs:8 * dec.l #imm,rd - bist #imm,rd divxu.b rs,rd - bist #imm,@@rd * divxu.w rs,rd - bist #imm,@@abs:8 * divxs.b rs,rd - bixor #imm,rd * divxs.w rs,rd - bixor #imm,@@rd eepmov - bixor #imm,@@abs:8 * eepmovw -@page -* exts.w rd mov.w rs,@@abs:16 -* exts.l rd * mov.l #imm,rd -* extu.w rd * mov.l rs,rd -* extu.l rd * mov.l @@rs,rd - inc rs * mov.l @@(disp:16,rs),rd -* inc.w #imm,rd * mov.l @@(disp:24,rs),rd -* inc.l #imm,rd * mov.l @@rs+,rd - jmp @@rs * mov.l @@abs:16,rd - jmp abs * mov.l @@abs:24,rd - jmp @@@@abs:8 * mov.l rs,@@rd - jsr @@rs * mov.l rs,@@(disp:16,rd) - jsr abs * mov.l rs,@@(disp:24,rd) - jsr @@@@abs:8 * mov.l rs,@@-rd - ldc #imm,ccr * mov.l rs,@@abs:16 - ldc rs,ccr * mov.l rs,@@abs:24 -* ldc @@abs:16,ccr movfpe @@abs:16,rd -* ldc @@abs:24,ccr movtpe rs,@@abs:16 -* ldc @@(disp:16,rs),ccr mulxu.b rs,rd -* ldc @@(disp:24,rs),ccr * mulxu.w rs,rd -* ldc @@rs+,ccr * mulxs.b rs,rd -* ldc @@rs,ccr * mulxs.w rs,rd -* mov.b @@(disp:24,rs),rd neg.b rs -* mov.b rs,@@(disp:24,rd) * neg.w rs - mov.b @@abs:16,rd * neg.l rs - mov.b rs,rd nop - mov.b @@abs:8,rd not.b rs - mov.b rs,@@abs:8 * not.w rs - mov.b rs,rd * not.l rs - mov.b #imm,rd or.b #imm,rd - mov.b @@rs,rd or.b rs,rd - mov.b @@(disp:16,rs),rd * or.w #imm,rd - mov.b @@rs+,rd * or.w rs,rd - mov.b @@abs:8,rd * or.l #imm,rd - mov.b rs,@@rd * or.l rs,rd - mov.b rs,@@(disp:16,rd) orc #imm,ccr - mov.b rs,@@-rd pop.w rs - mov.b rs,@@abs:8 * pop.l rs - mov.w rs,@@rd push.w rs -* mov.w @@(disp:24,rs),rd * push.l rs -* mov.w rs,@@(disp:24,rd) rotl.b rs -* mov.w @@abs:24,rd * rotl.w rs -* mov.w rs,@@abs:24 * rotl.l rs - mov.w rs,rd rotr.b rs - mov.w #imm,rd * rotr.w rs - mov.w @@rs,rd * rotr.l rs - mov.w @@(disp:16,rs),rd rotxl.b rs - mov.w @@rs+,rd * rotxl.w rs - mov.w @@abs:16,rd * rotxl.l rs - mov.w rs,@@(disp:16,rd) rotxr.b rs - mov.w rs,@@-rd * rotxr.w rs -@page -* rotxr.l rs * stc ccr,@@(disp:24,rd) - bpt * stc ccr,@@-rd - rte * stc ccr,@@abs:16 - rts * stc ccr,@@abs:24 - shal.b rs sub.b rs,rd -* shal.w rs sub.w rs,rd -* shal.l rs * sub.w #imm,rd - shar.b rs * sub.l rs,rd -* shar.w rs * sub.l #imm,rd -* shar.l rs subs #imm,rd - shll.b rs subx #imm,rd -* shll.w rs subx rs,rd -* shll.l rs * trapa #imm - shlr.b rs xor #imm,rd -* shlr.w rs xor rs,rd -* shlr.l rs * xor.w #imm,rd - sleep * xor.w rs,rd - stc ccr,rd * xor.l #imm,rd -* stc ccr,@@rs * xor.l rs,rd -* stc ccr,@@(disp:16,rd) xorc #imm,ccr -@end smallexample +@ifset TIC54X +@include c-tic54x.texi @end ifset -@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}, -@samp{.w}, and @samp{.l} to specify the size of a memory operand. -@code{@value{AS}} supports these suffixes, but does not require them; -since one of the operands is always a register, @code{@value{AS}} can -deduce the correct size. +@ifset Z8000 +@include c-z8k.texi +@end ifset -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 +@ifset VAX +@include c-vax.texi +@end ifset -If you use the size suffixes, @code{@value{AS}} issues a warning when -the suffix and the register size do not match. +@ifset V850 +@include c-v850.texi @end ifset -@ifset H8/500 -@page -@node H8/500-Dependent -@chapter H8/500 Dependent Features +@ifset GENERIC +@c reverse effect of @down at top of generic Machine-Dep chapter +@raisesections +@end ifset -@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 Reporting Bugs +@chapter Reporting Bugs +@cindex bugs in assembler +@cindex reporting bugs in assembler -@node H8/500 Options -@section Options +Your bug reports play an essential role in making @code{@value{AS}} reliable. -@cindex H8/500 options (none) -@cindex options, H8/500 (none) -@code{@value{AS}} has no additional command-line options for the Hitachi -H8/500 family. +Reporting a bug may help you by bringing a solution to your problem, or it may +not. But in any case the principal function of a bug report is to help the +entire community by making the next version of @code{@value{AS}} work better. +Bug reports are your contribution to the maintenance of @code{@value{AS}}. -@node H8/500 Syntax -@section Syntax +In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. @menu -* H8/500-Chars:: Special Characters -* H8/500-Regs:: Register Names -* H8/500-Addressing:: Addressing Modes +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs @end menu -@node H8/500-Chars -@subsection Special Characters +@node Bug Criteria +@section Have you found a bug? +@cindex bug criteria -@cindex line comment character, H8/500 -@cindex H8/500 line comment character -@samp{!} is the line comment character. +If you are not sure whether you have found a bug, here are some guidelines: -@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. +@itemize @bullet +@cindex fatal signal +@cindex assembler crash +@cindex crash of assembler +@item +If the assembler gets a fatal signal, for any input whatever, that is a +@code{@value{AS}} bug. Reliable assemblers never crash. -@node H8/500-Regs -@subsection Register Names +@cindex error on valid input +@item +If @code{@value{AS}} produces an error message for valid input, that is a bug. -@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. +@cindex invalid input +@item +If @code{@value{AS}} does not produce an error message for invalid input, that +is a bug. However, you should note that your idea of ``invalid input'' might +be our idea of ``an extension'' or ``support for traditional practice''. -The H8/500 also has these control registers: +@item +If you are an experienced user of assemblers, your suggestions for improvement +of @code{@value{AS}} are welcome in any case. +@end itemize -@table @code -@item cp -code pointer +@node Bug Reporting +@section How to report bugs +@cindex bug reports +@cindex assembler bugs, reporting -@item dp -data pointer +A number of companies and individuals offer support for @sc{gnu} products. If +you obtained @code{@value{AS}} from a support organization, we recommend you +contact that organization first. -@item bp -base pointer +You can find contact information for many support companies and +individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs +distribution. -@item tp -stack top pointer +In any event, we also recommend that you send bug reports for @code{@value{AS}} +to @samp{bug-gnu-utils@@gnu.org}. -@item ep -extra pointer +The fundamental principle of reporting bugs usefully is this: +@strong{report all the facts}. If you are not sure whether to state a +fact or leave it out, state it! -@item sr -status register +Often people omit facts because they think they know what causes the problem +and assume that some details do not matter. Thus, you might assume that the +name of a symbol you use in an example does not matter. Well, probably it does +not, but one cannot be sure. Perhaps the bug is a stray memory reference which +happens to fetch from the location where that name is stored in memory; +perhaps, if the name were different, the contents of that location would fool +the assembler into doing the right thing despite the bug. Play it safe and +give a specific, complete example. That is the easiest thing for you to do, +and the most helpful. -@item ccr -condition code register -@end table +Keep in mind that the purpose of a bug report is to enable us to fix the bug if +it is new to us. Therefore, always write your bug reports on the assumption +that the bug has not been reported previously. -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}. +Sometimes people give a few sketchy facts and ask, ``Does this ring a +bell?'' Those bug reports are useless, and we urge everyone to +@emph{refuse to respond to them} except to chide the sender to report +bugs properly. -@node H8/500-Addressing -@subsection Addressing Modes +To enable us to fix the bug, you should include all these things: -@cindex addressing modes, H8/500 -@cindex H8/500 addressing modes -@value{AS} understands the following addressing modes for the H8/500: -@table @code -@item R@var{n} -Register direct +@itemize @bullet +@item +The version of @code{@value{AS}}. @code{@value{AS}} announces it if you start +it with the @samp{--version} argument. -@item @@R@var{n} -Register indirect +Without this, we will not know whether there is any point in looking for +the bug in the current version of @code{@value{AS}}. -@item @@(d:8, R@var{n}) -Register indirect with 8 bit signed displacement +@item +Any patches you may have applied to the @code{@value{AS}} source. -@item @@(d:16, R@var{n}) -Register indirect with 16 bit signed displacement +@item +The type of machine you are using, and the operating system name and +version number. -@item @@-R@var{n} -Register indirect with pre-decrement +@item +What compiler (and its version) was used to compile @code{@value{AS}}---e.g. +``@code{gcc-2.7}''. -@item @@R@var{n}+ -Register indirect with post-increment +@item +The command arguments you gave the assembler to assemble your example and +observe the bug. To guarantee you will not omit something important, list them +all. A copy of the Makefile (or the output from make) is sufficient. -@item @@@var{aa}:8 -8 bit absolute address +If we were to try to guess the arguments, we would probably guess wrong +and then we might not encounter the bug. -@item @@@var{aa}:16 -16 bit absolute address +@item +A complete input file that will reproduce the bug. If the bug is observed when +the assembler is invoked via a compiler, send the assembler source, not the +high level language source. Most compilers will produce the assembler source +when run with the @samp{-S} option. If you are using @code{@value{GCC}}, use +the options @samp{-v --save-temps}; this will save the assembler source in a +file with an extension of @file{.s}, and also show you exactly how +@code{@value{AS}} is being run. -@item #@var{xx}:8 -8 bit immediate +@item +A description of what behavior you observe that you believe is +incorrect. For example, ``It gets a fatal signal.'' + +Of course, if the bug is that @code{@value{AS}} gets a fatal signal, then we +will certainly notice it. But if the bug is incorrect output, we might not +notice unless it is glaringly wrong. You might as well not give us a chance to +make a mistake. + +Even if the problem you experience is a fatal signal, you should still say so +explicitly. Suppose something strange is going on, such as, your copy of +@code{@value{AS}} is out of synch, or you have encountered a bug in the C +library on your system. (This has happened!) Your copy might crash and ours +would not. If you told us to expect a crash, then when ours fails to crash, we +would know that the bug was not happening for us. If you had not told us to +expect a crash, then we would not be able to draw any conclusion from our +observations. -@item #@var{xx}:16 -16 bit immediate -@end table +@item +If you wish to suggest changes to the @code{@value{AS}} source, send us context +diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p} +option. Always send diffs from the old file to the new file. If you even +discuss something in the @code{@value{AS}} source, refer to it by context, not +by line number. + +The line numbers in our development sources will not match those in your +sources. Your line numbers would convey no useful information to us. +@end itemize -@node H8/500 Floating Point -@section Floating Point +Here are some things that are not necessary: -@cindex floating point, H8/500 (@sc{ieee}) -@cindex H8/500 floating point (@sc{ieee}) -The H8/500 family has no hardware floating point, but the @code{.float} -directive generates @sc{ieee} floating-point numbers for compatibility -with other development tools. +@itemize @bullet +@item +A description of the envelope of the bug. -@node H8/500 Directives -@section H8/500 Machine Directives +Often people who encounter a bug spend a lot of time investigating +which changes to the input file will make the bug go away and which +changes will not affect it. -@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{@value{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. +This is often time consuming and not very useful, because the way we +will find the bug is by running a single example under the debugger +with breakpoints, not by pure deduction from a series of examples. +We recommend that you save your time for something else. -@node H8/500 Opcodes -@section Opcodes +Of course, if you can find a simpler example to report @emph{instead} +of the original one, that is a convenience for us. Errors in the +output will be easier to spot, running under the debugger will take +less time, and so on. -@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). +However, simplification is not vital; if you do not want to do this, +report the bug anyway and send us the entire test case you used. -@code{@value{AS}} implements all the standard H8/500 opcodes. No additional -pseudo-instructions are needed on this family. +@item +A patch for the bug. -@ifset SMALL -@c this table, due to the multi-col faking and hardcoded order, looks silly -@c except in smallbook. See comments below "@set SMALL" near top of this file. +A patch for the bug does help us if it is a good one. But do not omit +the necessary information, such as the test case, on the assumption that +a patch is all we need. We might see problems with your patch and decide +to fix the problem another way, or we might not understand it at all. -The following table summarizes H8/500 opcodes and their operands: +Sometimes with a program as complicated as @code{@value{AS}} it is very hard to +construct an example that will make the program follow a certain path through +the code. If you do not send us the example, we will not be able to construct +one, so we will not be able to verify that the bug is fixed. -@c Use @group if it ever works, instead of @page -@page -@smallexample -@i{Legend:} -abs8 @r{8-bit absolute address} -abs16 @r{16-bit absolute address} -abs24 @r{24-bit absolute address} -crb @r{@code{ccr}, @code{br}, @code{ep}, @code{dp}, @code{tp}, @code{dp}} -disp8 @r{8-bit displacement} -ea @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},} - @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16},} - @r{@code{#xx:8}, @code{#xx:16}} -ea_mem @r{@code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},} - @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}} -ea_noimm @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},} - @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}} -fp r6 -imm4 @r{4-bit immediate data} -imm8 @r{8-bit immediate data} -imm16 @r{16-bit immediate data} -pcrel8 @r{8-bit offset from program counter} -pcrel16 @r{16-bit offset from program counter} -qim @r{@code{-2}, @code{-1}, @code{1}, @code{2}} -rd @r{any register} -rs @r{a register distinct from rd} -rlist @r{comma-separated list of registers in parentheses;} - @r{register ranges @code{rd-rs} are allowed} -sp @r{stack pointer (@code{r7})} -sr @r{status register} -sz @r{size; @samp{.b} or @samp{.w}. If omitted, default @samp{.w}} - -ldc[.b] ea,crb bcc[.w] pcrel16 -ldc[.w] ea,sr bcc[.b] pcrel8 -add[:q] sz qim,ea_noimm bhs[.w] pcrel16 -add[:g] sz ea,rd bhs[.b] pcrel8 -adds sz ea,rd bcs[.w] pcrel16 -addx sz ea,rd bcs[.b] pcrel8 -and sz ea,rd blo[.w] pcrel16 -andc[.b] imm8,crb blo[.b] pcrel8 -andc[.w] imm16,sr bne[.w] pcrel16 -bpt bne[.b] pcrel8 -bra[.w] pcrel16 beq[.w] pcrel16 -bra[.b] pcrel8 beq[.b] pcrel8 -bt[.w] pcrel16 bvc[.w] pcrel16 -bt[.b] pcrel8 bvc[.b] pcrel8 -brn[.w] pcrel16 bvs[.w] pcrel16 -brn[.b] pcrel8 bvs[.b] pcrel8 -bf[.w] pcrel16 bpl[.w] pcrel16 -bf[.b] pcrel8 bpl[.b] pcrel8 -bhi[.w] pcrel16 bmi[.w] pcrel16 -bhi[.b] pcrel8 bmi[.b] pcrel8 -bls[.w] pcrel16 bge[.w] pcrel16 -bls[.b] pcrel8 bge[.b] pcrel8 -@page -blt[.w] pcrel16 mov[:g][.b] imm8,ea_mem -blt[.b] pcrel8 mov[:g][.w] imm16,ea_mem -bgt[.w] pcrel16 movfpe[.b] ea,rd -bgt[.b] pcrel8 movtpe[.b] rs,ea_noimm -ble[.w] pcrel16 mulxu sz ea,rd -ble[.b] pcrel8 neg sz ea -bclr sz imm4,ea_noimm nop -bclr sz rs,ea_noimm not sz ea -bnot sz imm4,ea_noimm or sz ea,rd -bnot sz rs,ea_noimm orc[.b] imm8,crb -bset sz imm4,ea_noimm orc[.w] imm16,sr -bset sz rs,ea_noimm pjmp abs24 -bsr[.b] pcrel8 pjmp @@rd -bsr[.w] pcrel16 pjsr abs24 -btst sz imm4,ea_noimm pjsr @@rd -btst sz rs,ea_noimm prtd imm8 -clr sz ea prtd imm16 -cmp[:e][.b] imm8,rd prts -cmp[:i][.w] imm16,rd rotl sz ea -cmp[:g].b imm8,ea_noimm rotr sz ea -cmp[:g][.w] imm16,ea_noimm rotxl sz ea -Cmp[:g] sz ea,rd rotxr sz ea -dadd rs,rd rtd imm8 -divxu sz ea,rd rtd imm16 -dsub rs,rd rts -exts[.b] rd scb/f rs,pcrel8 -extu[.b] rd scb/ne rs,pcrel8 -jmp @@rd scb/eq rs,pcrel8 -jmp @@(imm8,rd) shal sz ea -jmp @@(imm16,rd) shar sz ea -jmp abs16 shll sz ea -jsr @@rd shlr sz ea -jsr @@(imm8,rd) sleep -jsr @@(imm16,rd) stc[.b] crb,ea_noimm -jsr abs16 stc[.w] sr,ea_noimm -ldm @@sp+,(rlist) stm (rlist),@@-sp -link fp,imm8 sub sz ea,rd -link fp,imm16 subs sz ea,rd -mov[:e][.b] imm8,rd subx sz ea,rd -mov[:i][.w] imm16,rd swap[.b] rd -mov[:l][.w] abs8,rd tas[.b] ea -mov[:l].b abs8,rd trapa imm4 -mov[:s][.w] rs,abs8 trap/vs -mov[:s].b rs,abs8 tst sz ea -mov[:f][.w] @@(disp8,fp),rd unlk fp -mov[:f][.w] rs,@@(disp8,fp) xch[.w] rs,rd -mov[:f].b @@(disp8,fp),rd xor sz ea,rd -mov[:f].b rs,@@(disp8,fp) xorc.b imm8,crb -mov[:g] sz rs,ea_mem xorc.w imm16,sr -mov[:g] sz ea,rd -@end smallexample -@end ifset -@end ifset +And if we cannot understand what bug you are trying to fix, or why your +patch should be an improvement, we will not install it. A test case will +help us to understand. -@ifset HPPA -@page -@node HPPA-Dependent -@chapter HPPA Dependent Features +@item +A guess about what the bug is or what it depends on. -@cindex support -@menu -* HPPA Notes:: Notes -* HPPA Options:: Options -* HPPA Syntax:: Syntax -* HPPA Floating Point:: Floating Point -* HPPA Directives:: HPPA Machine Directives -* HPPA Opcodes:: Opcodes -@end menu +Such guesses are usually wrong. Even we cannot guess right about such +things without first using the debugger to find the facts. +@end itemize -@node HPPA Notes -@section Notes -As a back end for @sc{gnu} @sc{cc} @code{@value{AS}} has been throughly tested and should -work extremely well. We have tested it only minimally on hand written assembly -code and no one has tested it much on the assembly output from the HP -compilers. +@node Acknowledgements +@chapter Acknowledgements -The format of the debugging sections has changed since the original -@code{@value{AS}} port (version 1.3X) was released; therefore, -you must rebuild all HPPA objects and libraries with the new -assembler so that you can debug the final executable. +If you have contributed to @code{@value{AS}} and your name isn't listed here, +it is not meant as a slight. We just don't know about it. Send mail to the +maintainer, and we'll correct the situation. Currently +@c (January 1994), +the maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}). -The HPPA @code{@value{AS}} port generates a small subset of the relocations -available in the SOM and ELF object file formats. Additional relocation -support will be added as it becomes necessary. +Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any +more details?} -@node HPPA Options -@section Options -@code{@value{AS}} has no machine-dependent command-line options for the HPPA. +Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug +information and the 68k series machines, most of the preprocessing pass, and +extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}. -@cindex HPPA Syntax -@node HPPA Syntax -@section Syntax -The assembler syntax closely follows the HPPA instruction set -reference manual; assembler directives and general syntax closely follow the -HPPA assembly language reference manual, with a few noteworthy differences. +K. Richard Pixley maintained GAS for a while, adding various enhancements and +many bug fixes, including merging support for several processors, breaking GAS +up to handle multiple object file format back ends (including heavy rewrite, +testing, an integration of the coff and b.out back ends), adding configuration +including heavy testing and verification of cross assemblers and file splits +and renaming, converted GAS to strictly ANSI C including full prototypes, added +support for m680[34]0 and cpu32, did considerable work on i960 including a COFF +port (including considerable amounts of reverse engineering), a SPARC opcode +file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know'' +assertions and made them work, much other reorganization, cleanup, and lint. -First, a colon may immediately follow a label definition. This is -simply for compatibility with how most assembly language programmers -write code. +Ken Raeburn wrote the high-level BFD interface code to replace most of the code +in format-specific I/O modules. -Some obscure expression parsing problems may affect hand written code which -uses the @code{spop} instructions, or code which makes significant -use of the @code{!} line separator. +The original VMS support was contributed by David L. Kashtan. Eric Youngdale +has done much work with it since. -@code{@value{AS}} is much less forgiving about missing arguments and other -similar oversights than the HP assembler. @code{@value{AS}} notifies you -of missing arguments as syntax errors; this is regarded as a feature, not a -bug. +The Intel 80386 machine description was written by Eliot Dresselhaus. -Finally, @code{@value{AS}} allows you to use an external symbol without -explicitly importing the symbol. @emph{Warning:} in the future this will be -an error for HPPA targets. +Minh Tran-Le at IntelliCorp contributed some AIX 386 support. -Special characters for HPPA targets include: +The Motorola 88k machine description was contributed by Devon Bowen of Buffalo +University and Torbjorn Granlund of the Swedish Institute of Computer Science. -@samp{;} is the line comment character. +Keith Knowles at the Open Software Foundation wrote the original MIPS back end +(@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support +(which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to +support a.out format. -@samp{!} can be used instead of a newline to separate statements. - -Since @samp{$} has no special meaning, you may use it in symbol names. - -@node HPPA Floating Point -@section Floating Point -@cindex floating point, HPPA (@sc{ieee}) -@cindex HPPA floating point (@sc{ieee}) -The HPPA family uses @sc{ieee} floating-point numbers. - -@node HPPA Directives -@section HPPA Assembler Directives - -@code{@value{AS}} for the HPPA supports many additional directives for -compatibility with the native assembler. This section describes them only -briefly. For detailed information on HPPA-specific assembler directives, see -@cite{HP9000 Series 800 Assembly Language Reference Manual} (HP 92432-90001). - -@cindex HPPA directives not supported -@code{@value{AS}} does @emph{not} support the following assembler directives -described in the HP manual: - -@example -.endm .liston -.enter .locct -.leave .macro -.listoff -@end example - -@cindex @code{.param} on HPPA -Beyond those implemented for compatibility, @code{@value{AS}} supports one -additional assembler directive for the HPPA: @code{.param}. It conveys -register argument locations for static functions. Its syntax closely follows -the @code{.export} directive. - -@cindex HPPA-only directives -These are the additional directives in @code{@value{AS}} for the HPPA: - -@table @code -@item .block @var{n} -@itemx .blockz @var{n} -Reserve @var{n} bytes of storage, and initialize them to zero. - -@item .call -Mark the beginning of a procedure call. Only the special case with @emph{no -arguments} is allowed. - -@item .callinfo [ @var{param}=@var{value}, @dots{} ] [ @var{flag}, @dots{} ] -Specify a number of parameters and flags that define the environment for a -procedure. - -@var{param} may be any of @samp{frame} (frame size), @samp{entry_gr} (end of -general register range), @samp{entry_fr} (end of float register range), -@samp{entry_sr} (end of space register range). - -The values for @var{flag} are @samp{calls} or @samp{caller} (proc has -subroutines), @samp{no_calls} (proc does not call subroutines), @samp{save_rp} -(preserve return pointer), @samp{save_sp} (proc preserves stack pointer), -@samp{no_unwind} (do not unwind this proc), @samp{hpux_int} (proc is interrupt -routine). - -@item .code -Assemble into the standard section called @samp{$TEXT$}, subsection -@samp{$CODE$}. - -@ifset SOM -@item .copyright "@var{string}" -In the SOM object format, insert @var{string} into the object code, marked as a -copyright string. -@end ifset - -@ifset ELF -@item .copyright "@var{string}" -In the ELF object format, insert @var{string} into the object code, marked as a -version string. -@end ifset - -@item .enter -Not yet supported; the assembler rejects programs containing this directive. - -@item .entry -Mark the beginning of a procedure. - -@item .exit -Mark the end of a procedure. - -@item .export @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ] -Make a procedure @var{name} available to callers. @var{typ}, if present, must -be one of @samp{absolute}, @samp{code} (ELF only, not SOM), @samp{data}, -@samp{entry}, @samp{data}, @samp{entry}, @samp{millicode}, @samp{plabel}, -@samp{pri_prog}, or @samp{sec_prog}. - -@var{param}, if present, provides either relocation information for the -procedure arguments and result, or a privilege level. @var{param} may be -@samp{argw@var{n}} (where @var{n} ranges from @code{0} to @code{3}, and -indicates one of four one-word arguments); @samp{rtnval} (the procedure's -result); or @samp{priv_lev} (privilege level). For arguments or the result, -@var{r} specifies how to relocate, and must be one of @samp{no} (not -relocatable), @samp{gr} (argument is in general register), @samp{fr} (in -floating point register), or @samp{fu} (upper half of float register). -For @samp{priv_lev}, @var{r} is an integer. - -@item .half @var{n} -Define a two-byte integer constant @var{n}; synonym for the portable -@code{@value{AS}} directive @code{.short}. - -@item .import @var{name} [ ,@var{typ} ] -Converse of @code{.export}; make a procedure available to call. The arguments -use the same conventions as the first two arguments for @code{.export}. - -@item .label @var{name} -Define @var{name} as a label for the current assembly location. - -@item .leave -Not yet supported; the assembler rejects programs containing this directive. - -@item .origin @var{lc} -Advance location counter to @var{lc}. Synonym for the @code{@value{as}} -portable directive @code{.org}. - -@item .param @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ] -@c Not in HP manual; GNU HPPA extension -Similar to @code{.export}, but used for static procedures. - -@item .proc -Use preceding the first statement of a procedure. - -@item .procend -Use following the last statement of a procedure. - -@item @var{label} .reg @var{expr} -@c ?? Not in HP manual (Jan 1988 vn) -Synonym for @code{.equ}; define @var{label} with the absolute expression -@var{expr} as its value. - -@item .space @var{secname} [ ,@var{params} ] -Switch to section @var{secname}, creating a new section by that name if -necessary. You may only use @var{params} when creating a new section, not -when switching to an existing one. @var{secname} may identify a section by -number rather than by name. - -If specified, the list @var{params} declares attributes of the section, -identified by keywords. The keywords recognized are @samp{spnum=@var{exp}} -(identify this section by the number @var{exp}, an absolute expression), -@samp{sort=@var{exp}} (order sections according to this sort key when linking; -@var{exp} is an absolute expression), @samp{unloadable} (section contains no -loadable data), @samp{notdefined} (this section defined elsewhere), and -@samp{private} (data in this section not available to other programs). - -@item .spnum @var{secnam} -@c ?? Not in HP manual (Jan 1988) -Allocate four bytes of storage, and initialize them with the section number of -the section named @var{secnam}. (You can define the section number with the -HPPA @code{.space} directive.) - -@item .string "@var{str}" -@cindex @code{string} directive on HPPA -Copy the characters in the string @var{str} to the object file. -@xref{Strings,,Strings}, for information on escape sequences you can use in -@code{@value{AS}} strings. - -@emph{Warning!} The HPPA version of @code{.string} differs from the -usual @code{@value{AS}} definition: it does @emph{not} write a zero byte -after copying @var{str}. - -@item .stringz "@var{str}" -Like @code{.string}, but appends a zero byte after copying @var{str} to object -file. - -@item .subspa @var{name} [ ,@var{params} ] -Similar to @code{.space}, but selects a subsection @var{name} within the -current section. You may only specify @var{params} when you create a -subsection (in the first instance of @code{.subspa} for this @var{name}). - -If specified, the list @var{params} declares attributes of the subsection, -identified by keywords. The keywords recognized are @samp{quad=@var{expr}} -(``quadrant'' for this subsection), @samp{align=@var{expr}} (alignment for -beginning of this subsection; a power of two), @samp{access=@var{expr}} (value -for ``access rights'' field), @samp{sort=@var{expr}} (sorting order for this -subspace in link), @samp{code_only} (subsection contains only code), -@samp{unloadable} (subsection cannot be loaded into memory), @samp{common} -(subsection is common block), @samp{dup_comm} (initialized data may have -duplicate names), or @samp{zero} (subsection is all zeros, do not write in -object file). - -@item .version "@var{str}" -Write @var{str} as version identifier in object code. -@end table - -@node HPPA Opcodes -@section Opcodes -For detailed information on the HPPA machine instruction set, see -@cite{PA-RISC Architecture and Instruction Set Reference Manual} -(HP 09740-90039). -@end ifset - -@ifset SH -@page -@node SH-Dependent -@chapter Hitachi SH Dependent Features - -@cindex SH support -@menu -* SH Options:: Options -* SH Syntax:: Syntax -* SH Floating Point:: Floating Point -* SH Directives:: SH Machine Directives -* SH Opcodes:: Opcodes -@end menu - -@node SH Options -@section Options - -@cindex SH options (none) -@cindex options, SH (none) -@code{@value{AS}} has no additional command-line options for the Hitachi -SH family. - -@node SH Syntax -@section Syntax - -@menu -* SH-Chars:: Special Characters -* SH-Regs:: Register Names -* SH-Addressing:: Addressing Modes -@end menu - -@node SH-Chars -@subsection Special Characters - -@cindex line comment character, SH -@cindex SH line comment character -@samp{!} is the line comment character. - -@cindex line separator, SH -@cindex statement separator, SH -@cindex SH line separator -You can use @samp{;} 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 SH-Regs -@subsection Register Names - -@cindex SH registers -@cindex registers, SH -You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2}, -@samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, @samp{r7}, @samp{r8}, -@samp{r9}, @samp{r10}, @samp{r11}, @samp{r12}, @samp{r13}, @samp{r14}, -and @samp{r15} to refer to the SH registers. - -The SH also has these control registers: - -@table @code -@item pr -procedure register (holds return address) - -@item pc -program counter - -@item mach -@itemx macl -high and low multiply accumulator registers - -@item sr -status register - -@item gbr -global base register - -@item vbr -vector base register (for interrupt vectors) -@end table - -@node SH-Addressing -@subsection Addressing Modes - -@cindex addressing modes, SH -@cindex SH addressing modes -@code{@value{AS}} understands the following addressing modes for the SH. -@code{R@var{n}} in the following refers to any of the numbered -registers, but @emph{not} the control registers. - -@table @code -@item R@var{n} -Register direct - -@item @@R@var{n} -Register indirect - -@item @@-R@var{n} -Register indirect with pre-decrement - -@item @@R@var{n}+ -Register indirect with post-increment - -@item @@(@var{disp}, R@var{n}) -Register indirect with displacement - -@item @@(R0, R@var{n}) -Register indexed - -@item @@(@var{disp}, GBR) -@code{GBR} offset - -@item @@(R0, GBR) -GBR indexed - -@item @var{addr} -@itemx @@(@var{disp}, PC) -PC relative address (for branch or for addressing memory). The -@code{@value{AS}} implementation allows you to use the simpler form -@var{addr} anywhere a PC relative address is called for; the alternate -form is supported for compatibility with other assemblers. - -@item #@var{imm} -Immediate data -@end table - -@node SH Floating Point -@section Floating Point - -@cindex floating point, SH (@sc{ieee}) -@cindex SH floating point (@sc{ieee}) -The SH family has no hardware floating point, but the @code{.float} -directive generates @sc{ieee} floating-point numbers for compatibility -with other development tools. - -@node SH Directives -@section SH Machine Directives - -@cindex SH machine directives (none) -@cindex machine directives, SH (none) -@cindex @code{word} directive, SH -@cindex @code{int} directive, SH -@code{@value{AS}} has no machine-dependent directives for the SH. - -@node SH Opcodes -@section Opcodes - -@cindex SH opcode summary -@cindex opcode summary, SH -@cindex mnemonics, SH -@cindex instruction summary, SH -For detailed information on the SH machine instruction set, see -@cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.). - -@code{@value{AS}} implements all the standard SH opcodes. No additional -pseudo-instructions are needed on this family. Note, however, that -because @code{@value{AS}} supports a simpler form of PC-relative -addressing, you may simply write (for example) - -@example -mov.l bar,r0 -@end example - -@noindent -where other assemblers might require an explicit displacement to -@code{bar} from the program counter: - -@example -mov.l @@(@var{disp}, PC) -@end example - -@ifset SMALL -@c this table, due to the multi-col faking and hardcoded order, looks silly -@c except in smallbook. See comments below "@set SMALL" near top of this file. - -Here is a summary of SH opcodes: - -@page -@smallexample -@i{Legend:} -Rn @r{a numbered register} -Rm @r{another numbered register} -#imm @r{immediate data} -disp @r{displacement} -disp8 @r{8-bit displacement} -disp12 @r{12-bit displacement} - -add #imm,Rn lds.l @@Rn+,PR -add Rm,Rn mac.w @@Rm+,@@Rn+ -addc Rm,Rn mov #imm,Rn -addv Rm,Rn mov Rm,Rn -and #imm,R0 mov.b Rm,@@(R0,Rn) -and Rm,Rn mov.b Rm,@@-Rn -and.b #imm,@@(R0,GBR) mov.b Rm,@@Rn -bf disp8 mov.b @@(disp,Rm),R0 -bra disp12 mov.b @@(disp,GBR),R0 -bsr disp12 mov.b @@(R0,Rm),Rn -bt disp8 mov.b @@Rm+,Rn -clrmac mov.b @@Rm,Rn -clrt mov.b R0,@@(disp,Rm) -cmp/eq #imm,R0 mov.b R0,@@(disp,GBR) -cmp/eq Rm,Rn mov.l Rm,@@(disp,Rn) -cmp/ge Rm,Rn mov.l Rm,@@(R0,Rn) -cmp/gt Rm,Rn mov.l Rm,@@-Rn -cmp/hi Rm,Rn mov.l Rm,@@Rn -cmp/hs Rm,Rn mov.l @@(disp,Rn),Rm -cmp/pl Rn mov.l @@(disp,GBR),R0 -cmp/pz Rn mov.l @@(disp,PC),Rn -cmp/str Rm,Rn mov.l @@(R0,Rm),Rn -div0s Rm,Rn mov.l @@Rm+,Rn -div0u mov.l @@Rm,Rn -div1 Rm,Rn mov.l R0,@@(disp,GBR) -exts.b Rm,Rn mov.w Rm,@@(R0,Rn) -exts.w Rm,Rn mov.w Rm,@@-Rn -extu.b Rm,Rn mov.w Rm,@@Rn -extu.w Rm,Rn mov.w @@(disp,Rm),R0 -jmp @@Rn mov.w @@(disp,GBR),R0 -jsr @@Rn mov.w @@(disp,PC),Rn -ldc Rn,GBR mov.w @@(R0,Rm),Rn -ldc Rn,SR mov.w @@Rm+,Rn -ldc Rn,VBR mov.w @@Rm,Rn -ldc.l @@Rn+,GBR mov.w R0,@@(disp,Rm) -ldc.l @@Rn+,SR mov.w R0,@@(disp,GBR) -ldc.l @@Rn+,VBR mova @@(disp,PC),R0 -lds Rn,MACH movt Rn -lds Rn,MACL muls Rm,Rn -lds Rn,PR mulu Rm,Rn -lds.l @@Rn+,MACH neg Rm,Rn -lds.l @@Rn+,MACL negc Rm,Rn -@page -nop stc VBR,Rn -not Rm,Rn stc.l GBR,@@-Rn -or #imm,R0 stc.l SR,@@-Rn -or Rm,Rn stc.l VBR,@@-Rn -or.b #imm,@@(R0,GBR) sts MACH,Rn -rotcl Rn sts MACL,Rn -rotcr Rn sts PR,Rn -rotl Rn sts.l MACH,@@-Rn -rotr Rn sts.l MACL,@@-Rn -rte sts.l PR,@@-Rn -rts sub Rm,Rn -sett subc Rm,Rn -shal Rn subv Rm,Rn -shar Rn swap.b Rm,Rn -shll Rn swap.w Rm,Rn -shll16 Rn tas.b @@Rn -shll2 Rn trapa #imm -shll8 Rn tst #imm,R0 -shlr Rn tst Rm,Rn -shlr16 Rn tst.b #imm,@@(R0,GBR) -shlr2 Rn xor #imm,R0 -shlr8 Rn xor Rm,Rn -sleep xor.b #imm,@@(R0,GBR) -stc GBR,Rn xtrct Rm,Rn -stc SR,Rn -@end smallexample -@end ifset - -@ifset Hitachi-all -@ifclear GENERIC -@raisesections -@end ifclear -@end ifset - -@end ifset -@ifset I960 -@ifset GENERIC -@page -@node i960-Dependent -@chapter Intel 80960 Dependent Features -@end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter Intel 80960 Dependent Features -@end ifclear - -@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 - -@section 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 you do not specify any of these options, @code{@value{AS}} generates 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{@value{AS}} attempts 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{@value{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 -@need 2000 -@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 @sc{gnu} C compiler -generates these calls automatically when you give it a @samp{-b} option. -For further details, see the documentation of @samp{gbr960}. - -@item -no-relax -@cindex @code{-no-relax} 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{-no-relax} option to specify that -@code{@value{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{-no-relax}. -@end table - -@node Floating Point-i960 -@section Floating Point - -@cindex floating point, i960 (@sc{ieee}) -@cindex i960 floating point (@sc{ieee}) -@code{@value{AS}} generates @sc{ieee} floating-point numbers for the directives -@samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}. - -@node Directives-i960 -@section 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 -@section 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 -@subsection @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{@value{AS}} translates the -@code{callj}; if not, it simply emits the @code{callj}, leaving it -for the linker to resolve. - -@node Compare-and-branch-i960 -@subsection 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{@value{AS}} gives an error or expands the instruction depends -on two choices you can make: whether you use the @samp{-no-relax} 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{-no-relax}---in which case -@code{@value{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 -@end ifset - -@ifset M680X0 -@ifset GENERIC -@page -@node M68K-Dependent -@chapter M680x0 Dependent Features -@end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter M680x0 Dependent Features -@end ifclear - -@cindex M680x0 support -@menu -* M68K-Opts:: M680x0 Options -* M68K-Syntax:: Syntax -* M68K-Moto-Syntax:: Motorola Syntax -* M68K-Float:: Floating Point -* M68K-Directives:: 680x0 Machine Directives -* M68K-opcodes:: Opcodes -@end menu - -@node M68K-Opts -@section M680x0 Options - -@cindex options, M680x0 -@cindex M680x0 options -The Motorola 680x0 version of @code{@value{AS}} has two machine dependent options. -One shortens undefined references from 32 to 16 bits, while the -other is used to tell @code{@value{AS}} what kind of machine it is -assembling for. - -@cindex @code{-l} option, M680x0 -You can use the @samp{-l} option to shorten the size of references to undefined -symbols. If you do not use the @samp{-l} option, references to undefined -symbols are wide enough for a full @code{long} (32 bits). (Since -@code{@value{AS}} cannot know where these symbols end up, @code{@value{AS}} can -only allocate space for the linker to fill in later. Since @code{@value{AS}} -does not know how far away these symbols are, it allocates as much space as it -can.) If you use this option, the references are only 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 are always less than 17 bits away. - -@cindex @code{-m68000} and related options -@cindex architecture options, M680x0 -@cindex M680x0 architecture options -The 680x0 version of @code{@value{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{@value{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 -@section Syntax - -@cindex @sc{mit} -This syntax for the Motorola 680x0 was developed at @sc{mit}. - -@cindex M680x0 syntax -@cindex syntax, M680x0 -@cindex M680x0 size modifiers -@cindex size modifiers, M680x0 -The 680x0 version of @code{@value{AS}} uses syntax compatible with the Sun -assembler. Intervening periods are ignored; for example, @samp{movl} is -equivalent to @samp{move.l}. - -@ifset INTERNALS -If @code{@value{AS}} is compiled with SUN_ASM_SYNTAX defined, it -also allows Sun-style local labels of the form @samp{1$} through -@samp{$9}. -@end ifset - -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}@* -@samp{%a7} is also known as @samp{%sp}, i.e. the Stack Pointer. @code{%a6} -is also known as @samp{%fp}, the Frame Pointer. - -@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 - -For some configurations, especially those where the compiler normally does not -prepend an underscore to the names of user variables, the assembler requires a -@samp{%} before any use of a register name. This is intended to let the -assembler distinguish between C variables and registers named @samp{a0} through -@samp{a7}, and so on. The @samp{%} is always accepted, but is not required for -certain configurations, notably @samp{sun3}. - -@node M68K-Moto-Syntax -@section Motorola Syntax - -@cindex Motorola syntax for the 680x0 -@cindex alternate syntax for the 680x0 - -The standard Motorola syntax for this chip differs from the syntax already -discussed (@pxref{M68K-Syntax,,Syntax}). @code{@value{AS}} can accept some -forms of Motorola syntax for operands, even if @sc{mit} syntax is used for -other operands in the same instruction. The two kinds of syntax are fully -compatible; our support for Motorola syntax is simply incomplete at present. - -@cindex M680x0 syntax -@cindex syntax, M680x0 -In particular, you may write or generate M68K assembler with the -following conventions: - -(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 additional addressing modes are understood: -@table @dfn -@item Address Register Indirect -@samp{%a0} through @samp{%a7}@* -@samp{%a7} is also known as @samp{%sp}, i.e. the Stack Pointer. @code{%a6} -is also known as @samp{%fp}, the Frame Pointer. - -@item Address Register Postincrement -@samp{(%a0)+} through @samp{(%a7)+} - -@item Address Register Predecrement -@samp{-(%a0)} through @samp{-(%a7)} - -@item Indirect Plus Offset -@samp{@var{digits}(%@var{apc})} - -@item Index -@samp{@var{digits}(%@var{apc},(%@var{register}.@var{size}*@var{scale}))}@* -or @samp{(%@var{apc},%@var{register}.@var{size}*@var{scale})}@* -In either case, @var{size} and @var{scale} are optional -(@var{scale} defaults to @samp{1}, @var{size} defaults to @samp{l}). - @var{scale} can be @samp{1}, @samp{2}, @samp{4}, or @samp{8}. - @var{size} can be @samp{w} or @samp{l}. @var{scale} is only supported -on the 68020 and greater. -@end table - -Other, more complex addressing modes permitted in Motorola syntax are not -handled. - -@node M68K-Float -@section 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 -@section 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 - -@need 2000 -@node M68K-opcodes -@section 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 -@subsection 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 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{@value{AS}} issues 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{@value{AS}} emits -@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{@value{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 -@subsection 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. - -@end ifset -@ignore -@c FIXME! Stop ignoring when filled in. -@node 32x32 -@chapter 32x32 - -@section Options -The 32x32 version of @code{@value{AS}} accepts a @samp{-m32032} option to -specify thiat it is compiling for a 32032 processor, or a -@samp{-m32532} to specify that it is compiling for a 32532 option. -The default (if neither is specified) is chosen when the assembler -is compiled. - -@section Syntax -I don't know anything about the 32x32 syntax assembled by -@code{@value{AS}}. Someone who undersands the processor (I've never seen -one) and the possible syntaxes should write this section. - -@section Floating Point -The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{AS}} -only creates single or double precision values. I don't know if the -32x32 understands extended precision numbers. - -@section 32x32 Machine Directives -The 32x32 has no machine dependent directives. - -@end ignore -@ifset SPARC -@ifset GENERIC -@page -@node Sparc-Dependent -@chapter SPARC Dependent Features -@end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter SPARC Dependent Features -@end ifclear - -@cindex SPARC support -@menu -* Sparc-Opts:: Options -* Sparc-Float:: Floating Point -* Sparc-Directives:: Sparc Machine Directives -@end menu - -@node Sparc-Opts -@section Options - -@cindex options for SPARC -@cindex SPARC options -@cindex architectures, SPARC -@cindex SPARC architectures -The SPARC chip family includes several successive levels (or other -variants) of chip, using the same core instruction set, but including -a few additional instructions at each level. - -By default, @code{@value{AS}} assumes the core instruction set (SPARC -v6), but ``bumps'' the architecture level as needed: it switches to -successively higher architectures as it encounters instructions that -only exist in the higher levels. - -@table @code -@item -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite -@kindex -Av6 -@kindex Av7 -@kindex -Av8 -@kindex -Av9 -@kindex -Asparclite -Use one of the @samp{-A} options to select one of the SPARC -architectures explicitly. If you select an architecture explicitly, -@code{@value{AS}} reports a fatal error if it encounters an instruction -or feature requiring a higher level. - -@item -bump -Permit the assembler to ``bump'' the architecture level as required, but -warn whenever it is necessary to switch to another level. -@end table - -@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 -@section 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 -@section Sparc Machine Directives - -@cindex SPARC machine directives -@cindex machine directives, SPARC -The Sparc version of @code{@value{AS}} supports the following additional -machine directives: - -@table @code -@item .align -@cindex @code{align} directive, SPARC -This must be followed by the desired alignment in bytes. - -@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 @code{.word} directive produces 32 bit values, -instead of the 16 bit values it produces on many other machines. - -@item .xword -@cindex @code{xword} directive, SPARC -On the Sparc V9 processor, the @code{.xword} directive produces -64 bit values. -@end table - -@end ifset -@ifset I80386 -@ifset GENERIC -@page -@node i386-Dependent -@chapter 80386 Dependent Features -@end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter 80386 Dependent Features -@end ifclear - -@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-16bit:: Writing 16-bit Code -* i386-Notes:: Notes -@end menu - -@node i386-Options -@section Options - -@cindex options for i386 (none) -@cindex i386 options (none) -The 80386 has no machine dependent options. - -@node i386-Syntax -@section AT&T Syntax versus Intel Syntax - -@cindex i386 syntax compatibility -@cindex syntax compatibility, i386 -In order to maintain compatibility with the output of @code{@value{GCC}}, -@code{@value{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 -@section 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{@value{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{@value{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 -@section 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 -@section 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 -@section 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{@value{AS}} does @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{@value{AS}} -always chooses 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 -@section 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 if you use these instructions (@code{@value{GCC}} does -not use them) you may get an error message (and 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 -@section 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{@value{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-16bit -@section Writing 16-bit Code - -@cindex i386 16-bit code -@cindex 16-bit code, i386 -@cindex real-mode code, i386 -@cindex @code{code16} directive, i386 -@cindex @code{code32} directive, i386 -While GAS normally writes only ``pure'' 32-bit i386 code, it has limited -support for writing code to run in real mode or in 16-bit protected mode -code segments. To do this, insert a @samp{.code16} directive before the -assembly language instructions to be run in 16-bit mode. You can switch -GAS back to writing normal 32-bit code with the @samp{.code32} directive. - -GAS understands exactly the same assembly language syntax in 16-bit mode as -in 32-bit mode. The function of any given instruction is exactly the same -regardless of mode, as long as the resulting object code is executed in the -mode for which GAS wrote it. So, for example, the @samp{ret} mnemonic -produces a 32-bit return instruction regardless of whether it is to be run -in 16-bit or 32-bit mode. (If GAS is in 16-bit mode, it will add an -operand size prefix to the instruction to force it to be a 32-bit return.) - -This means, for one thing, that you can use GNU CC to write code to be run -in real mode or 16-bit protected mode. Just insert the statement -@samp{asm(".code16");} at the beginning of your C source file, and while -GNU CC will still be generating 32-bit code, GAS will automatically add all -the necessary size prefixes to make that code run in 16-bit mode. Of -course, since GNU CC only writes small-model code (it doesn't know how to -attach segment selectors to pointers like native x86 compilers do), any -16-bit code you write with GNU CC will essentially be limited to a 64K -address space. Also, there will be a code size and performance penalty -due to all the extra address and operand size prefixes GAS has to add to -the instructions. - -Note that placing GAS in 16-bit mode does not mean that the resulting -code will necessarily run on a 16-bit pre-80386 processor. To write code -that runs on such a processor, you would have to refrain from using -@emph{any} 32-bit constructs which require GAS to output address or -operand size prefixes. At the moment this would be rather difficult, -because GAS currently supports @emph{only} 32-bit addressing modes: when -writing 16-bit code, it @emph{always} outputs address size prefixes for any -instruction that uses a non-register addressing mode. So you can write -code that runs on 16-bit processors, but only if that code never references -memory. - -@node i386-Notes -@section 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{@value{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}. - -@end ifset -@ifset Z8000 -@ifset GENERIC -@page -@node Z8000-Dependent -@chapter Z8000 Dependent Features -@end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter Z8000 Dependent Features -@end ifclear - -@cindex Z8000 support -The Z8000 @value{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 takes 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 -@section Options - -@cindex Z8000 options -@cindex options, Z8000 -@code{@value{AS}} has no additional command-line options for the Zilog -Z8000 family. - -@node Z8000 Syntax -@section Syntax -@menu -* Z8000-Chars:: Special Characters -* Z8000-Regs:: Register Names -* Z8000-Addressing:: Addressing Modes -@end menu - -@node Z8000-Chars -@subsection 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 -@subsection 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 -@subsection Addressing Modes - -@cindex addressing modes, Z8000 -@cindex Z800 addressing modes -@value{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 -@section Assembler Directives for the Z8000 - -@cindex Z8000 directives -@cindex directives, Z8000 -The Z8000 port of @value{AS} includes these additional assembler directives, -for compatibility with other Z8000 assemblers. As shown, these do not -begin with @samp{.} (unlike the ordinary @value{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 -@section 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}. - -@ifset SMALL -@c this table, due to the multi-col faking and hardcoded order, looks silly -@c except in smallbook. See comments below "@set SMALL" near top of this file. - -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 -@end ifset - -@end ifset - -@ifset MIPS -@ifset GENERIC -@page -@node MIPS-Dependent -@chapter MIPS Dependent Features -@end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter MIPS Dependent Features -@end ifclear - -@cindex MIPS R2000 -@cindex MIPS R3000 -@cindex MIPS R4000 -@cindex MIPS R6000 -@sc{gnu} @code{@value{AS}} for @sc{mips} architectures supports the @sc{mips} -@sc{r2000}, @sc{r3000}, @sc{r4000} and @sc{r6000} processors. For information -about the @sc{mips} instruction set, see @cite{MIPS RISC Architecture}, by Kane -and Heindrich (Prentice-Hall). For an overview of @sc{mips} assembly -conventions, see ``Appendix D: Assembly Language Programming'' in the same -work. - -@menu -* MIPS Opts:: Assembler options -* MIPS Object:: ECOFF object code -* MIPS Stabs:: Directives for debugging information -* MIPS ISA:: Directives to override the ISA level -@end menu - -@node MIPS Opts -@section Assembler options - -The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support these -special options: - -@table @code -@cindex @code{-G} option (MIPS) -@item -G @var{num} -This option sets the largest size of an object that can be referenced -implicitly with the @code{gp} register. It is only accepted for targets -that use @sc{ecoff} format. The default value is 8. - -@cindex @code{-EB} option (MIPS) -@cindex @code{-EL} option (MIPS) -@cindex MIPS big-endian output -@cindex MIPS little-endian output -@cindex big-endian output, MIPS -@cindex little-endian output, MIPS -@item -EB -@itemx -EL -Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or -little-endian output at run time (unlike the other @sc{gnu} development -tools, which must be configured for one or the other). Use @samp{-EB} -to select big-endian output, and @samp{-EL} for little-endian. - -@cindex MIPS architecture options -@item -mips1 -@itemx -mips2 -@itemx -mips3 -Generate code for a particular MIPS Instruction Set Architecture level. -@samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors, -@samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000} -processor. You can also switch instruction sets during the assembly; see -@ref{MIPS ISA,, Directives to override the ISA level}. - -@item -m4650 -@item -no-m4650 -Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept -the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop} -instructions around accesses to the @samp{HI} and @samp{LO} registers. -@samp{-no-m4650} turns off this option. - -@item -mcpu=@var{CPU} -Generate code for a particular MIPS cpu. This has little effect on the -assembler, but it is passed by @code{@value{GCC}}. - -@cindex @code{-nocpp} ignored (MIPS) -@item -nocpp -This option is ignored. It is accepted for command-line compatibility with -other assemblers, which use it to turn off C style preprocessing. With -@sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the -@sc{gnu} assembler itself never runs the C preprocessor. - -@item --trap -@itemx --no-break -@c FIXME! (1) reflect these options (next item too) in option summaries; -@c (2) stop teasing, say _which_ instructions expanded _how_. -@code{@value{AS}} automatically macro expands certain division and -multiplication instructions to check for overflow and division by zero. This -option causes @code{@value{AS}} to generate code to take a trap exception -rather than a break exception when an error is detected. The trap instructions -are only supported at Instruction Set Architecture level 2 and higher. - -@item --break -@itemx --no-trap -Generate code to take a break exception rather than a trap exception when an -error is detected. This is the default. -@end table - -@node MIPS Object -@section MIPS ECOFF object code - -@cindex ECOFF sections -@cindex MIPS ECOFF sections -Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections -besides the usual @code{.text}, @code{.data} and @code{.bss}. The -additional sections are @code{.rdata}, used for read-only data, -@code{.sdata}, used for small data, and @code{.sbss}, used for small -common objects. - -@cindex small objects, MIPS ECOFF -@cindex @code{gp} register, MIPS -When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28}) -register to form the address of a ``small object''. Any object in the -@code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense. -For external objects, or for objects in the @code{.bss} section, you can use -the @code{@value{GCC}} @samp{-G} option to control the size of objects addressed via -@code{$gp}; the default value is 8, meaning that a reference to any object -eight bytes or smaller uses @code{$gp}. Passing @samp{-G 0} to -@code{@value{AS}} prevents it from using the @code{$gp} register on the basis -of object size (but the assembler uses @code{$gp} for objects in @code{.sdata} -or @code{sbss} in any case). The size of an object in the @code{.bss} section -is set by the @code{.comm} or @code{.lcomm} directive that defines it. The -size of an external object may be set with the @code{.extern} directive. For -example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes -in length, whie leaving @code{sym} otherwise undefined. - -Using small @sc{ecoff} objects requires linker support, and assumes that the -@code{$gp} register is correctly initialized (normally done automatically by -the startup code). @sc{mips} @sc{ecoff} assembly code must not modify the -@code{$gp} register. - -@node MIPS Stabs -@section Directives for debugging information - -@cindex MIPS debugging directives -@sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for -generating debugging information which are not support by traditional @sc{mips} -assemblers. These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file}, -@code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val}, -@code{.stabd}, @code{.stabn}, and @code{.stabs}. The debugging information -generated by the three @code{.stab} directives can only be read by @sc{gdb}, -not by traditional @sc{mips} debuggers (this enhancement is required to fully -support C++ debugging). These directives are primarily used by compilers, not -assembly language programmers! - -@node MIPS ISA -@section Directives to override the ISA level - -@cindex MIPS ISA override -@kindex @code{.set mips@var{n}} -@sc{gnu} @code{@value{AS}} supports an additional directive to change the -@sc{mips} Instruction Set Architecture level on the fly: @code{.set -mips@var{n}}. @var{n} should be a number from 0 to 3. A value from 1 to 3 -makes the assembler accept instructions for the corresponding @sc{isa} level, -from that point on in the assembly. @code{.set mips@var{n}} affects not only -which instructions are permitted, but also how certain macros are expanded. -@code{.set mips0} restores the @sc{isa} level to its original level: either the -level you selected with command line options, or the default for your -configuration. You can use this feature to permit specific @sc{r4000} -instructions while assembling in 32 bit mode. Use this directive with care! - -Traditional @sc{mips} assemblers do not support this directive. -@end ifset - -@ifset GENERIC -@c reverse effect of @down at top of generic Machine-Dep chapter -@raisesections -@end ifset - -@node Acknowledgements -@chapter Acknowledgements - -If you have contributed to @code{@value{AS}} and your name isn't listed here, -it is not meant as a slight. We just don't know about it. Send mail to the -maintainer, and we'll correct the situation. Currently (January 1994), the -maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}). - -Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any more -details?} - -Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug -information and the 68k series machines, most of the preprocessing pass, and -extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}. - -K. Richard Pixley maintained GAS for a while, adding various enhancements and -many bug fixes, including merging support for several processors, breaking GAS -up to handle multiple object file format back ends (including heavy rewrite, -testing, an integration of the coff and b.out back ends), adding configuration -including heavy testing and verification of cross assemblers and file splits -and renaming, converted GAS to strictly ANSI C including full prototypes, added -support for m680[34]0 and cpu32, did considerable work on i960 including a COFF -port (including considerable amounts of reverse engineering), a SPARC opcode -file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know'' -assertions and made them work, much other reorganization, cleanup, and lint. - -Ken Raeburn wrote the high-level BFD interface code to replace most of the code -in format-specific I/O modules. - -The original VMS support was contributed by David L. Kashtan. Eric Youngdale -has done much work with it since. - -The Intel 80386 machine description was written by Eliot Dresselhaus. - -Minh Tran-Le at IntelliCorp contributed some AIX 386 support. - -The Motorola 88k machine description was contributed by Devon Bowen of Buffalo -University and Torbjorn Granlund of the Swedish Institute of Computer Science. - -Keith Knowles at the Open Software Foundation wrote the original MIPS back end -(@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support -(which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to -support a.out format. - -Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k, -tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by -Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to -use BFD for some low-level operations, for use with the H8/300 and AMD 29k -targets. +Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k, +tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by +Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to +use BFD for some low-level operations, for use with the H8/300 and AMD 29k +targets. John Gilmore built the AMD 29000 support, added @code{.include} support, and simplified the configuration of which versions accept which directives. He @@ -7607,8 +5753,8 @@ required the proverbial one-bit fix. Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix), -added support for MIPS ECOFF and ELF targets, and made a few other minor -patches. +added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and +PowerPC assembler, and made a few other minor patches. Steve Chamberlain made @code{@value{AS}} able to generate listings. @@ -7625,6 +5771,14 @@ Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc, and some initial 64-bit support). +Linas Vepstas added GAS support for the ESA/390 "IBM 370" architecture. + +Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD +support for openVMS/Alpha. + +Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic* +flavors. + Several engineers at Cygnus Support have also provided many small bug fixes and configuration enhancements. @@ -7633,6 +5787,369 @@ you have contributed significant work and are not mentioned on this list, and want to be, let us know. Some of the history has been lost; we are not intentionally leaving anyone out. +@node GNU Free Documentation License +@chapter GNU Free Documentation License + + GNU Free Documentation License + + Version 1.1, March 2000 + + Copyright (C) 2000 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document "free" in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The "Document", below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as "you". + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section entitled "History", and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section as "Endorsements" + or to conflict in title with any Invariant Section. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled "History" +in the various original documents, forming one section entitled +"History"; likewise combine any sections entitled "Acknowledgements", +and any sections entitled "Dedications". You must delete all sections +entitled "Endorsements." + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an "aggregate", and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document 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. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation 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. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +@end smallexample + +If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write "no Front-Cover Texts" instead of +"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + @node Index @unnumbered Index