diff options
Diffstat (limited to 'gas/doc/as.texinfo')
| -rw-r--r-- | gas/doc/as.texinfo | 5322 |
1 files changed, 5322 insertions, 0 deletions
diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo new file mode 100644 index 0000000000..afe362a7fb --- /dev/null +++ b/gas/doc/as.texinfo @@ -0,0 +1,5322 @@ +\input texinfo @c -*-Texinfo-*- +@c Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 1998 +@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 +@c (2) for platform-specific directives, examine md_pseudo_op +@c in config/tc-*.c +@c (3) for object-format specific directives, examine obj_pseudo_op +@c in config/obj-*.c +@c (4) portable directives in potable[] in read.c +@c %**start of header +@setfilename as.info +@c ---config--- +@c defaults, config file may override: +@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 +@ifset H8/300 +@set H8 +@end ifset +@ifset H8/500 +@set H8 +@end ifset +@ifset SH +@set H8 +@end ifset +@ifset HPPA +@set abnormal-separator +@end ifset +@c ------------ +@ifset GENERIC +@settitle Using @value{AS} +@end ifset +@ifclear GENERIC +@settitle Using @value{AS} (@value{TARGET}) +@end ifclear +@setchapternewpage odd +@c %**end of header + +@c @smallbook +@c @set SMALL +@c WARE! Some of the machine-dependent sections contain tables of machine +@c instructions. Except in multi-column format, these tables look silly. +@c Unfortunately, Texinfo doesn't have a general-purpose multi-col format, so +@c the multi-col format is faked within @example sections. +@c +@c Again unfortunately, the natural size that fits on a page, for these tables, +@c is different depending on whether or not smallbook is turned on. +@c This matters, because of order: text flow switches columns at each page +@c break. +@c +@c The format faked in this source works reasonably well for smallbook, +@c not well for the default large-page format. This manual expects that if you +@c turn on @smallbook, you will also uncomment the "@set SMALL" to enable the +@c tables in question. You can turn on one without the other at your +@c discretion, of course. +@ifinfo +@set SMALL +@c the insn tables look just as silly in info files regardless of smallbook, +@c might as well show 'em anyways. +@end ifinfo + +@ifinfo +@format +START-INFO-DIR-ENTRY +* As: (as). The GNU assembler. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@finalout +@syncodeindex ky cp + +@ifinfo +This file documents the GNU Assembler "@value{AS}". + +Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this manual +under the conditions for verbatim copying, provided 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 @sc{gnu} Assembler +@ifclear GENERIC +@subtitle for the @value{TARGET} family +@end ifclear +@sp 1 +@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 @sc{gnu}. +The proprietors, management and staff of TNCCA thank FSF for +distracting the boss while they got some work +done. +@sp 3 +@author Dean Elsner, Jay Fenlason & friends +@page +@tex +{\parskip=0pt +\hfill {\it Using {\tt @value{AS}}}\par +\hfill Edited by Cygnus Support\par +} +%"boxit" macro for figures: +%Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3) +\gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt + \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil +#2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline +\gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box +@end tex + +@vskip 0pt plus 1filll +Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this manual +under the conditions for verbatim copying, provided 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}} version +@value{VERSION}. +@ifclear GENERIC +This version of the file describes @code{@value{AS}} configured to generate +code for @value{TARGET} architectures. +@end ifclear +@menu +* Overview:: Overview +* Invoking:: Command-Line Options +* Syntax:: Syntax +* Sections:: Sections and Relocation +* Symbols:: Symbols +* Expressions:: Expressions +* Pseudo Ops:: Assembler Directives +* Machine Dependencies:: Machine Dependent Features +* Reporting Bugs:: Reporting Bugs +* Acknowledgements:: Who Did What +* Index:: Index +@end menu +@end ifinfo + +@node Overview +@chapter Overview +@iftex +This manual is a user guide to the @sc{gnu} assembler @code{@value{AS}}. +@ifclear GENERIC +This version of the manual describes @code{@value{AS}} configured to generate +code for @value{TARGET} architectures. +@end ifclear +@end iftex + +@cindex invocation summary +@cindex option summary +@cindex summary of options +Here is a brief summary of how to invoke @code{@value{AS}}. For details, +@pxref{Invoking,,Comand-Line Options}. + +@c We don't use deffn and friends for the following because they seem +@c to be limited to one line for the header. +@smallexample +@value{AS} [ -a[cdhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ] + [ -f ] [ --gstabs ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ] + [ --keep-locals ] [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ] + [ -version ] [ --version ] [ -W ] [ -w ] [ -x ] [ -Z ] +@ifset A29K +@c am29k has no machine-dependent assembler options +@end ifset +@ifset ARC + [ -mbig-endian | -mlittle-endian ] +@end ifset +@ifset ARM + [ -m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 | -m[arm]6 | -m[arm]7[t][[d]m[i]] ] + [ -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m | -m[arm]v4 | -m[arm]v4t ] + [ -mthumb | -mall ] + [ -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu ] + [ -EB | -EL ] + [ -mapcs-32 | -mapcs-26 ] +@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 SPARC +@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 Z8000 +@c Z8000 has no machine-dependent assembler options +@end ifset +@ifset I960 +@c see md_parse_option in tc-i960.c + [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ] + [ -b ] [ -no-relax ] +@end ifset +@ifset M680X0 + [ -l ] [ -m68000 | -m68010 | -m68020 | ... ] +@end ifset +@ifset MCORE + [ -jsri2bsr ] [ -sifilter ] [ -relax ] +@end ifset +@ifset MIPS + [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ] + [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ] + [ --trap ] [ --break ] + [ --emulation=@var{name} ] +@end ifset + [ -- | @var{files} @dots{} ] +@end smallexample + +@table @code +@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 + +@item -ah +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. 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 --help +Print a summary of the command line options and exit. + +@item -I @var{dir} +Add directory @var{dir} to the search list for @code{.include} directives. + +@item -J +Don't warn about signed overflow. + +@item -K +@ifclear DIFF-TBL-KLUGE +This option is accepted but has no effect on the @value{TARGET} family. +@end ifclear +@ifset DIFF-TBL-KLUGE +Issue warnings when difference tables altered for long displacements. +@end ifset + +@item -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}. + +@item -R +Fold the data section into the text section. + +@item --statistics +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. + +@item --version +Print the @code{as} version and exit. + +@item -W +Suppress warning messages. + +@item -w +Ignored. + +@item -x +Ignored. + +@item -Z +Generate an object file even after errors. + +@item -- | @var{files} @dots{} +Standard input, or source files to assemble. + +@end table + +@ifset ARC +The following options are available when @value{AS} is configured for +an ARC processor. + +@table @code + +@cindex ARC endianness +@cindex endianness, ARC +@cindex big endian output, ARC +@item -mbig-endian +Generate ``big endian'' format output. + +@cindex little endian output, ARC +@item -mlittle-endian +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 | -m[arm]2 | -m[arm]250 | -m[arm]3 | -m[arm]6 | -m[arm]7[t][[d]m] | -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m | -m[arm]v4 | -m[arm]v4t +Specify which variant of the ARM architecture is 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 +Select which procedure calling convention is in use. +@item -EB | -EL +Select either big-endian (-EB) or little-endian (-EL) output. +@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. + +@table @code +@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC +Specify which variant of the 960 architecture is the target. + +@item -b +Add code to collect statistics about branches taken. + +@item -no-relax +Do not alter compare-and-branch instructions for long displacements; +error if necessary. + +@end table +@end ifset + + +@ifset M680X0 +The following options are available when @value{AS} is configured for the +Motorola 68000 series. + +@table @code + +@item -l +Shorten references to undefined symbols, to one word instead of two. + +@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -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. + +@item -m68881 | -m68882 | -mno-68881 | -mno-68882 +The target machine does (or does not) have a floating-point coprocessor. +The default is to assume a coprocessor for 68020, 68030, and cpu32. Although +the basic 68000 is not compatible with the 68881, a combination of the +two can be specified, since it's possible to do emulation of the +coprocessor instructions with the main processor. + +@item -m68851 | -mno-68851 +The target machine does (or does not) have a memory-management +unit coprocessor. The default is to assume an MMU for 68020 and up. + +@end table +@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 | -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 MIPS +The following options are available when @value{AS} is configured for +a MIPS processor. + +@table @code +@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 ECOFF format, such as a DECstation running Ultrix. The default value is 8. + +@cindex MIPS endianness +@cindex endianness, MIPS +@cindex big endian output, MIPS +@item -EB +Generate ``big endian'' format output. + +@cindex little endian output, MIPS +@item -EL +Generate ``little endian'' format output. + +@cindex MIPS ISA +@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. + +@item -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. +@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 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 +@itemx --no-break +Control how to deal with multiplication overflow and division by zero. +@samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception +(and only work for Instruction Set Architecture level 2 and higher); +@samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a +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. + + +@end table +@end ifset + +@menu +* Manual:: Structure of this Manual +* GNU Assembler:: The GNU Assembler +* Object Formats:: Object File Formats +* Command Line:: Command Line +* Input Files:: Input Files +* Object:: Output (Object) File +* Errors:: Error and Warning Messages +@end menu + +@node Manual +@section Structure of this Manual + +@cindex manual, structure and purpose +This manual is intended to describe what you need to know to use +@sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including +notation for symbols, constants, and expressions; the directives that +@code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}. + +@ifclear GENERIC +We also cover special features in the @value{TARGET} +configuration of @code{@value{AS}}, including assembler directives. +@end ifclear +@ifset GENERIC +This manual also describes some of the machine-dependent features of +various flavors of the assembler. +@end ifset + +@cindex machine instructions (not covered) +On the other hand, this manual is @emph{not} intended as an introduction +to programming in assembly language---let alone programming in general! +In a similar vein, we make no attempt to introduce the machine +architecture; we do @emph{not} describe the instruction set, standard +mnemonics, registers or addressing modes that are standard to a +particular architecture. +@ifset GENERIC +You may want to consult the manufacturer's +machine architecture manual for this information. +@end ifset +@ifclear GENERIC +@ifset H8/300 +For information on the H8/300 machine instruction set, see @cite{H8/300 +Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H, +see @cite{H8/300H Series Programming Manual} (Hitachi). +@end ifset +@ifset H8/500 +For information on the H8/500 machine instruction set, see @cite{H8/500 +Series Programming Manual} (Hitachi M21T001). +@end ifset +@ifset SH +For information on the Hitachi SH machine instruction set, see +@cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.). +@end ifset +@ifset Z8000 +For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual} +@end ifset +@end ifclear + +@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 +Foundation, Inc.}. This restricts our attention to certain kinds of +computer (in particular, the kinds of computers that @sc{gnu} can run on); +once this assumption is granted examples and definitions need less +qualification. + +@code{@value{AS}} is part of a team of programs that turn a high-level +human-readable series of instructions into a low-level +computer-readable series of instructions. Different versions of +@code{@value{AS}} are used for different kinds of computer. +@end ignore + +@c There used to be a section "Terminology" here, which defined +@c "contents", "byte", "word", and "long". Defining "word" to any +@c particular size is confusing when the .word directive may generate 16 +@c bits on one machine and 32 bits on another; in general, for the user +@c version of this manual, none of these terms seem essential to define. +@c They were used very little even in the former draft of the manual; +@c this draft makes an effort to avoid them (except in names of +@c directives). + +@node GNU Assembler +@section The GNU Assembler + +@sc{gnu} @code{as} is really a family of assemblers. +@ifclear GENERIC +This manual describes @code{@value{AS}}, a member of that family which is +configured for the @value{TARGET} architectures. +@end ifclear +If you use (or have used) the @sc{gnu} assembler on one architecture, you +should find a fairly similar environment when you use it on another +architecture. Each version has much in common with the others, +including object file formats, most assembler directives (often called +@dfn{pseudo-ops}) and assembler syntax.@refill + +@cindex purpose of @sc{gnu} 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}} +assemble correctly everything that other assemblers for the same +machine would assemble. +@ifset VAX +Any exceptions are documented explicitly (@pxref{Machine Dependencies}). +@end ifset +@ifset M680X0 +@c This remark should appear in generic version of manual; assumption +@c here is that generic version sets M680x0. +This doesn't mean @code{@value{AS}} always uses the same syntax as another +assembler for the same architecture; for example, we know of several +incompatible versions of 680x0 assembly language syntax. +@end ifset + +Unlike older assemblers, @code{@value{AS}} is designed to assemble a source +program in one pass of the source file. This has a subtle impact on the +@kbd{.org} directive (@pxref{Org,,@code{.org}}). + +@node Object Formats +@section Object File Formats + +@cindex object file format +The @sc{gnu} assembler can be configured to produce several alternative +object file formats. For the most part, this does not affect how you +write assembly language programs; but directives for debugging symbols +are typically different in different file formats. @xref{Symbol +Attributes,,Symbol Attributes}. +@ifclear GENERIC +@ifclear MULTI-OBJ +On the @value{TARGET}, @code{@value{AS}} is configured to produce +@value{OBJ-NAME} format object files. +@end ifclear +@c The following should exhaust all configs that set MULTI-OBJ, ideally +@ifset A29K +On the @value{TARGET}, @code{@value{AS}} can be configured to produce either +@code{a.out} or COFF format object files. +@end ifset +@ifset I960 +On the @value{TARGET}, @code{@value{AS}} can be configured to produce either +@code{b.out} or COFF format object files. +@end ifset +@ifset HPPA +On the @value{TARGET}, @code{@value{AS}} can be configured to produce either +SOM or ELF format object files. +@end ifset +@end ifclear + +@node Command Line +@section Command Line + +@cindex command line conventions +After the program name @code{@value{AS}}, the command line may contain +options and file names. Options may appear in any order, and may be +before, after, or between file names. The order of file names is +significant. + +@cindex standard input, as input file +@kindex -- +@file{--} (two hyphens) by itself names the standard input file +explicitly, as one of the files for @code{@value{AS}} to assemble. + +@cindex options, command line +Except for @samp{--} any command line argument that begins with a +hyphen (@samp{-}) is an option. Each option changes the behavior of +@code{@value{AS}}. No option changes the way another option works. An +option is a @samp{-} followed by one or more letters; the case of +the letter is important. All options are optional. + +Some options expect exactly one file name to follow them. The file +name may either immediately follow the option's letter (compatible +with older assemblers) or it may be the next command argument (@sc{gnu} +standard). These two command lines are equivalent: + +@smallexample +@value{AS} -o my-object-file.o mumble.s +@value{AS} -omy-object-file.o mumble.s +@end smallexample + +@node Input Files +@section Input Files + +@cindex input +@cindex source program +@cindex files, input +We use the phrase @dfn{source program}, abbreviated @dfn{source}, to +describe the program input to one run of @code{@value{AS}}. The program may +be in one or more files; how the source is partitioned into files +doesn't change the meaning of the source. + +@c I added "con" prefix to "catenation" just to prove I can overcome my +@c APL training... doc@cygnus.com +The source program is a concatenation of the text in all the files, in the +order specified. + +Each time you run @code{@value{AS}} it assembles exactly one source +program. The source program is made up of one or more files. +(The standard input is also a file.) + +You give @code{@value{AS}} a command line that has zero or more input file +names. The input files are read (from left file name to right). A +command line argument (in any position) that has no special meaning +is taken to be an input file name. + +If you give @code{@value{AS}} no file names it attempts to read one input file +from the @code{@value{AS}} standard input, which is normally your terminal. You +may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program +to assemble. + +Use @samp{--} if you need to explicitly name the standard input file +in your command line. + +If the source is empty, @code{@value{AS}} produces a small, empty object +file. + +@subheading Filenames and Line-numbers + +@cindex input file linenumbers +@cindex line numbers, in input files +There are two ways of locating a line in the input file (or files) and +either may be used in reporting error messages. One way refers to a line +number in a physical file; the other refers to a line number in a +``logical'' file. @xref{Errors, ,Error and Warning Messages}. + +@dfn{Physical files} are those files named in the command line given +to @code{@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. @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 + +@cindex object file +@cindex output file +@kindex a.out +@kindex .o +Every time you run @code{@value{AS}} it produces an output file, which is +your assembly language program translated into numbers. This file +is the object file. Its default name is +@ifclear BOUT +@code{a.out}. +@end ifclear +@ifset BOUT +@ifset GENERIC +@code{a.out}, or +@end ifset +@code{b.out} when @code{@value{AS}} is configured for the Intel 80960. +@end ifset +You can give it another name by using the @code{-o} option. Conventionally, +object file names end with @file{.o}. The default name is used for historical +reasons: older assemblers were capable of assembling self-contained programs +directly into a runnable program. (For some formats, this isn't currently +possible, but it can be done for the @code{a.out} format.) + +@cindex linker +@kindex ld +The object file is meant for input to the linker @code{@value{LD}}. It contains +assembled program code, information to help @code{@value{LD}} integrate +the assembled program into a runnable file, and (optionally) symbolic +information for the debugger. + +@c link above to some info file(s) like the description of a.out. +@c don't forget to describe @sc{gnu} info as well as Unix lossage. + +@node Errors +@section Error and Warning Messages + +@cindex error messsages +@cindex warning messages +@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 +that @code{@value{AS}} could keep assembling a flawed program; errors report a +grave problem that stops the assembly. + +@cindex format of warning messages +Warning messages have the format + +@smallexample +file_name:@b{NNN}:Warning Message Text +@end smallexample + +@noindent +@cindex line numbers, in warnings/errors +(where @b{NNN} is a line number). If a logical file name has been given +(@pxref{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 +@ifclear GENERIC +@ifclear A29K +(@pxref{Line,,@code{.line}}) +@end ifclear +@ifset A29K +(@pxref{Ln,,@code{.ln}}) +@end ifset +@end ifclear +then it is used to calculate the number printed, +otherwise the actual line in the current source file is printed. The +message text is intended to be self explanatory (in the grand Unix +tradition). + +@cindex format of error messages +Error messages have the format +@smallexample +file_name:@b{NNN}:FATAL:Error Message Text +@end smallexample +The file name and line number are derived as for warning +messages. The actual message text may be rather less explanatory +because many of them aren't supposed to happen. + +@node Invoking +@chapter Command-Line Options + +@cindex options, all versions of 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 +to the @value{TARGET}. +@end ifclear +@ifset GENERIC +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: + +@smallexample +gcc -c -g -O -Wa,-alh,-L file.c +@end smallexample + +@noindent +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. +(You can call the @sc{gnu} compiler driver with the @samp{-v} option to see +precisely what options it passes to each compilation pass, including the +assembler.) + +@menu +* a:: -a[cdhlns] enable listings +* D:: -D for compatibility +* f:: -f to work faster +* I:: -I for .include search path +@ifclear DIFF-TBL-KLUGE +* K:: -K for compatibility +@end ifclear +@ifset DIFF-TBL-KLUGE +* K:: -K for difference tables +@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 +* Z:: -Z to make object file even after errors +@end menu + +@node a +@section Enable Listings: @code{-a[cdhlns]} + +@kindex -a +@kindex -ac +@kindex -ad +@kindex -ah +@kindex -al +@kindex -an +@kindex -as +@cindex listings, enabling +@cindex assembly listings, enabling + +These options enable listing output from the assembler. By itself, +@samp{-a} requests high-level, assembly, and symbols listing. +You can use other letters to select specific options for the list: +@samp{-ah} requests a high-level language listing, +@samp{-al} requests an output-program assembly listing, and +@samp{-as} requests a symbol table listing. +High-level listings require that a compiler debugging option like +@samp{-g} be used, and that assembly listings (@samp{-al}) be requested +also. + +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. + +Once you have specified one of these options, you can further control +listing output and its appearance using the directives @code{.list}, +@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and +@code{.sbttl}. +The @samp{-an} option turns off all forms processing. +If you do not request listing output with one of the @samp{-a} options, the +listing-control directives have no effect. + +The letters after @samp{-a} may be combined into one option, +@emph{e.g.}, @samp{-aln}. + +@node D +@section @code{-D} + +@kindex -D +This option has no effect whatsoever, but it is accepted to make it more +likely that scripts written for other assemblers also work with +@code{@value{AS}}. + +@node f +@section Work Faster: @code{-f} + +@kindex -f +@cindex trusted compiler +@cindex faster processing (@code{-f}) +@samp{-f} should only be used when assembling programs written by a +(trusted) compiler. @samp{-f} stops the assembler from doing whitespace +and comment preprocessing on +the input file(s) before assembling them. @xref{Preprocessing, +,Preprocessing}. + +@quotation +@emph{Warning:} if you use @samp{-f} when the files actually need to be +preprocessed (if they contain comments, for example), @code{@value{AS}} does +not work correctly. +@end quotation + +@node I +@section @code{.include} search path: @code{-I} @var{path} + +@kindex -I @var{path} +@cindex paths for @code{.include} +@cindex search path for @code{.include} +@cindex @code{include} directive search path +Use this option to add a @var{path} to the list of directories +@code{@value{AS}} searches for files specified in @code{.include} +directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as +many times as necessary to include a variety of paths. The current +working directory is always searched first; after that, @code{@value{AS}} +searches any @samp{-I} directories in the same order as they were +specified (left to right) on the command line. + +@node K +@section Difference Tables: @code{-K} + +@kindex -K +@ifclear DIFF-TBL-KLUGE +On the @value{TARGET} family, this option is allowed, but has no effect. It is +permitted for compatibility with the @sc{gnu} assembler on other platforms, +where it can be used to warn when the assembler alters the machine code +generated for @samp{.word} directives in difference tables. The @value{TARGET} +family does not have the addressing limitations that sometimes lead to this +alteration on other platforms. +@end ifclear + +@ifset DIFF-TBL-KLUGE +@cindex difference tables, warning +@cindex warning for altered difference tables +@code{@value{AS}} sometimes alters the code emitted for directives of the form +@samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}. +You can use the @samp{-K} option if you want a warning issued when this +is done. +@end ifset + +@node L +@section Include Local Labels: @code{-L} + +@kindex -L +@cindex local labels, retaining in output +Labels beginning with @samp{L} (upper case only) are called @dfn{local +labels}. @xref{Symbol Names}. Normally you do not see such labels when +debugging, because they are intended for the use of programs (like +compilers) that compose assembler programs, not for your notice. +Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not +normally debug with them. + +This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols +in the object file. Usually if you do this you also tell the linker +@code{@value{LD}} to preserve symbols whose names begin with @samp{L}. + +By default, a local label is any label beginning with @samp{L}, but each +target is allowed to redefine the local label prefix. +@ifset HPPA +On the HPPA local labels begin with @samp{L$}. +@end ifset +@ifset ARM +@samp{;} for the ARM family; +@end ifset + +@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} + +@kindex -o +@cindex naming object file +@cindex object file name +There is always one object file output when you run @code{@value{AS}}. By +default it has the name +@ifset GENERIC +@ifset I960 +@file{a.out} (or @file{b.out}, for Intel 960 targets only). +@end ifset +@ifclear I960 +@file{a.out}. +@end ifclear +@end ifset +@ifclear GENERIC +@ifset I960 +@file{b.out}. +@end ifset +@ifclear I960 +@file{a.out}. +@end ifclear +@end ifclear +You use this option (which takes exactly one filename) to give the +object file a different name. + +Whatever the object file is called, @code{@value{AS}} overwrites any +existing file of the same name. + +@node R +@section Join Data and Text Sections: @code{-R} + +@kindex -R +@cindex data and text sections, joining +@cindex text and data sections, joining +@cindex joining text and data sections +@cindex merging text and data sections +@code{-R} tells @code{@value{AS}} to write the object file as if all +data-section data lives in the text section. This is only done at +the very last moment: your binary data are the same, but data +section parts are relocated differently. The data section part of +your object file is zero bytes long because all its bytes are +appended to the text section. (@xref{Sections,,Sections and Relocation}.) + +When you specify @code{-R} it would be possible to generate shorter +address displacements (because we do not have to cross between text and +data section). We refrain from doing this simply for compatibility with +older versions of @code{@value{AS}}. In future, @code{-R} may work this way. + +@ifset COFF +When @code{@value{AS}} is configured for COFF output, +this option is only useful if you use sections named @samp{.text} and +@samp{.data}. +@end ifset + +@ifset HPPA +@code{-R} is not supported for any of the HPPA targets. Using +@code{-R} generates a warning from @code{@value{AS}}. +@end ifset + +@node statistics +@section Display Assembly Statistics: @code{--statistics} + +@kindex --statistics +@cindex statistics, about assembly +@cindex time, total for assembly +@cindex space used, maximum for assembly +Use @samp{--statistics} to display two statistics about the resources used by +@code{@value{AS}}: the maximum amount of space allocated during the assembly +(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 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} + +@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. + +@node Z +@section Generate Object File in Spite of Errors: @code{-Z} +@cindex object file, after errors +@cindex errors, continuing after +After an error message, @code{@value{AS}} normally produces no output. If for +some reason you are interested in object file output even after +@code{@value{AS}} gives an error message on your program, use the @samp{-Z} +option. If there are any errors, @code{@value{AS}} continues anyways, and +writes an object file after a final warning message of the form @samp{@var{n} +errors, @var{m} warnings, generating bad object file.} + +@node Syntax +@chapter Syntax + +@cindex machine-independent syntax +@cindex syntax, machine-independent +This chapter describes the machine-independent syntax allowed in a +source file. @code{@value{AS}} syntax is similar to what many other +assemblers use; it is inspired by the BSD 4.2 +@ifclear VAX +assembler. +@end ifclear +@ifset VAX +assembler, except that @code{@value{AS}} does not assemble Vax bit-fields. +@end ifset + +@menu +* Preprocessing:: Preprocessing +* Whitespace:: Whitespace +* Comments:: Comments +* Symbol Intro:: Symbols +* Statements:: Statements +* Constants:: Constants +@end menu + +@node Preprocessing +@section Preprocessing + +@cindex preprocessing +The @code{@value{AS}} internal preprocessor: +@itemize @bullet +@cindex whitespace, removed by preprocessor +@item +adjusts and removes extra whitespace. It leaves one space or tab before +the keywords on a line, and turns any other whitespace on the line into +a single space. + +@cindex comments, removed by preprocessor +@item +removes all comments, replacing them with a single space, or an +appropriate number of newlines. + +@cindex constants, converted by preprocessor +@item +converts character constants into the appropriate numeric values. +@end itemize + +It does not do macro processing, include file handling, or +anything else you may get from your C compiler's preprocessor. You can +do include file processing with the @code{.include} directive +(@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver +to get other ``CPP'' style preprocessing, by giving the input file a +@samp{.S} suffix. @xref{Overall Options,, Options Controlling the Kind of +Output, gcc.info, Using GNU CC}. + +Excess whitespace, comments, and character constants +cannot be used in the portions of the input text that are not +preprocessed. + +@cindex turning preprocessing on and off +@cindex preprocessing, turning on and off +@kindex #NO_APP +@kindex #APP +If the first line of an input file is @code{#NO_APP} or if you use the +@samp{-f} option, whitespace and comments are not removed from the input file. +Within an input file, you can ask for whitespace and comment removal in +specific portions of the by putting a line that says @code{#APP} before the +text that may contain whitespace or comments, and putting a line that says +@code{#NO_APP} after this text. This feature is mainly intend to support +@code{asm} statements in compilers whose output is otherwise free of comments +and whitespace. + +@node Whitespace +@section Whitespace + +@cindex whitespace +@dfn{Whitespace} is one or more blanks or tabs, in any order. +Whitespace is used to separate symbols, and to make programs neater for +people to read. Unless within character constants +(@pxref{Characters,,Character Constants}), any whitespace means the same +as exactly one space. + +@node Comments +@section Comments + +@cindex comments +There are two ways of rendering comments to @code{@value{AS}}. In both +cases the comment is equivalent to one space. + +Anything from @samp{/*} through the next @samp{*/} is a comment. +This means you may not nest these comments. + +@smallexample +/* + The only way to include a newline ('\n') in a comment + is to use this sort of comment. +*/ + +/* This sort of comment does not nest. */ +@end smallexample + +@cindex line comment character +Anything from the @dfn{line comment} character to the next newline +is considered a comment and is ignored. The line comment character is +@ifset A29K +@samp{;} for the AMD 29K family; +@end ifset +@ifset ARC +@samp{;} on the ARC; +@end ifset +@ifset H8/300 +@samp{;} for the H8/300 family; +@end ifset +@ifset H8/500 +@samp{!} for the H8/500 family; +@end ifset +@ifset HPPA +@samp{;} for the HPPA; +@end ifset +@ifset I960 +@samp{#} on the i960; +@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 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? + +@ifset GENERIC +On some machines there are two different line comment characters. One +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 +To be compatible with past assemblers, lines that begin with @samp{#} have a +special interpretation. Following the @samp{#} should be an absolute +expression (@pxref{Expressions}): the logical line number of the @emph{next} +line. Then a string (@pxref{Strings,, Strings}) is allowed: if present it is a +new logical file name. The rest of the line, if any, should be whitespace. + +If the first non-whitespace characters on the line are not numeric, +the line is ignored. (Just like a comment.) + +@smallexample + # This is an ordinary comment. +# 42-6 "new_file_name" # New logical file name + # This is logical line # 36. +@end smallexample +This feature is deprecated, and may disappear from future versions +of @code{@value{AS}}. + +@node Symbol Intro +@section Symbols + +@cindex characters used in symbols +@ifclear SPECIAL-SYMS +A @dfn{symbol} is one or more characters chosen from the set of all +letters (both upper and lower case), digits and the three characters +@samp{_.$}. +@end ifclear +@ifset SPECIAL-SYMS +@ifclear GENERIC +@ifset H8 +A @dfn{symbol} is one or more characters chosen from the set of all +letters (both upper and lower case), digits and the three characters +@samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in +symbol names.) +@end ifset +@end ifclear +@end ifset +@ifset GENERIC +On most machines, you can also use @code{$} in symbol names; exceptions +are noted in @ref{Machine Dependencies}. +@end ifset +No symbol may begin with a digit. Case is significant. +There is no length limit: all characters are significant. Symbols are +delimited by characters not in that set, or by the beginning of a file +(since the source program must end with a newline, the end of a file is +not a possible symbol delimiter). @xref{Symbols}. +@cindex length of symbols + +@node Statements +@section Statements + +@cindex statements, structure of +@cindex line separator character +@cindex statement separator character +@ifclear GENERIC +@ifclear abnormal-separator +A @dfn{statement} ends at a newline character (@samp{\n}) or at a +semicolon (@samp{;}). The newline or semicolon is considered part of +the preceding statement. Newlines and semicolons within character +constants are an exception: they do not end statements. +@end ifclear +@ifset abnormal-separator +@ifset A29K +A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at'' +sign (@samp{@@}). The newline or at sign is considered part of the +preceding statement. Newlines and at signs within character constants +are an exception: they do not end statements. +@end ifset +@ifset HPPA +A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation +point (@samp{!}). The newline or exclamation point is considered part of the +preceding statement. Newlines and exclamation points within character +constants are an exception: they do not end statements. +@end ifset +@ifset H8 +A @dfn{statement} ends at a newline character (@samp{\n}); or (for the +H8/300) a dollar sign (@samp{$}); or (for the +Hitachi-SH or the +H8/500) a semicolon +(@samp{;}). The newline or separator character is considered part of +the preceding statement. Newlines and separators within character +constants are an exception: they do not end statements. +@end ifset +@end ifset +@end ifclear +@ifset GENERIC +A @dfn{statement} ends at a newline character (@samp{\n}) or line +separator character. (The line separator is usually @samp{;}, unless +this conflicts with the comment character; @pxref{Machine Dependencies}.) The +newline or separator character is considered part of the preceding +statement. Newlines and separators within character constants are an +exception: they do not end statements. +@end ifset + +@cindex newline, required at file end +@cindex EOF, newline must precede +It is an error to end any statement with end-of-file: the last +character of any input file should be a newline.@refill + +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... 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 +symbol determines the syntax of the rest of the statement. If the +symbol begins with a dot @samp{.} then the statement is an assembler +directive: typically valid for any computer. If the symbol begins with +a letter the statement is an assembly language @dfn{instruction}: it +assembles into a machine language instruction. +@ifset GENERIC +Different versions of @code{@value{AS}} for different computers +recognize different instructions. In fact, the same symbol may +represent a different instruction in a different computer's assembly +language.@refill +@end ifset + +@cindex @code{:} (label) +@cindex label (@code{:}) +A label is a symbol immediately followed by a colon (@code{:}). +Whitespace before a label or after a colon is permitted, but you may not +have whitespace between a label's symbol and its colon. @xref{Labels}. + +@ifset HPPA +For HPPA targets, labels need not be immediately followed by a colon, but +the definition of a label must begin in column zero. This also implies that +only one label may be defined on each line. +@end ifset + +@smallexample +label: .directive followed by something +another_label: # This is an empty statement. + instruction operand_1, operand_2, @dots{} +@end smallexample + +@node Constants +@section Constants + +@cindex constants +A constant is a number, written so that its value is known by +inspection, without knowing any context. Like this: +@smallexample +@group +.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value. +.ascii "Ring the bell\7" # A string constant. +.octa 0x123456789abcdef0123456789ABCDEF0 # A bignum. +.float 0f-314159265358979323846264338327\ +95028841971.693993751E-40 # - pi, a flonum. +@end group +@end smallexample + +@menu +* Characters:: Character Constants +* Numbers:: Number Constants +@end menu + +@node Characters +@subsection Character Constants + +@cindex character constants +@cindex constants, character +There are two kinds of character constants. A @dfn{character} stands +for one character in one byte and its value may be used in +numeric expressions. String constants (properly called string +@emph{literals}) are potentially many bytes and their values may not be +used in arithmetic expressions. + +@menu +* Strings:: Strings +* Chars:: Characters +@end menu + +@node Strings +@subsubsection Strings + +@cindex string constants +@cindex constants, string +A @dfn{string} is written between double-quotes. It may contain +double-quotes or null characters. The way to get special characters +into a string is to @dfn{escape} these characters: precede them with +a backslash @samp{\} character. For example @samp{\\} represents +one backslash: the first @code{\} is an escape which tells +@code{@value{AS}} to interpret the second character literally as a backslash +(which prevents @code{@value{AS}} from recognizing the second @code{\} as an +escape character). The complete list of escapes follows. + +@cindex escape codes, character +@cindex character escape codes +@table @kbd +@c @item \a +@c Mnemonic for ACKnowledge; for ASCII this is octal code 007. +@c +@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 +@cindex @code{\f} (formfeed character) +@cindex formfeed (@code{\f}) +@item \f +Mnemonic for FormFeed; for ASCII this is octal code 014. + +@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 +@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 +@cindex @code{\t} (tab) +@cindex tab (@code{\t}) +@item \t +Mnemonic for horizontal Tab; for ASCII this is octal code 011. + +@c @item \v +@c Mnemonic for Vertical tab; for ASCII this is octal code 013. +@c @item \x @var{digit} @var{digit} @var{digit} +@c A hexadecimal character code. The numeric code is 3 hexadecimal digits. +@c +@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. + +@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. + +@cindex @code{\\} (@samp{\} character) +@cindex backslash (@code{\\}) +@item \\ +Represents one @samp{\} character. + +@c @item \' +@c Represents one @samp{'} (accent acute) character. +@c This is needed in single character literals +@c (@xref{Characters,,Character Constants}.) to represent +@c a @samp{'}. +@c +@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. + +@item \ @var{anything-else} +Any other character when escaped by @kbd{\} gives a warning, but +assembles as if the @samp{\} was not present. The idea is that if +you used an escape sequence you clearly didn't want the literal +interpretation of the following character. However @code{@value{AS}} has no +other interpretation, so @code{@value{AS}} knows it is giving you the wrong +code and warns you of the fact. +@end table + +Which characters are escapable, and what those escapes represent, +varies widely among assemblers. The current set is what we think +the BSD 4.2 assembler recognizes, and is a subset of what most C +compilers recognize. If you are in doubt, do not use an escape +sequence. + +@node Chars +@subsubsection Characters + +@cindex single character constant +@cindex character, single +@cindex constant, single character +A single character may be written as a single quote immediately +followed by that character. The same escapes apply to characters as +to strings. So if you want to write the character backslash, you +must write @kbd{'\\} where the first @code{\} escapes the second +@code{\}. As you can see, the quote is an acute accent, not a +grave accent. A newline +@ifclear GENERIC +@ifclear abnormal-separator +(or semicolon @samp{;}) +@end ifclear +@ifset abnormal-separator +@ifset A29K +(or at sign @samp{@@}) +@end ifset +@ifset H8 +(or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the +Hitachi SH or +H8/500) +@end ifset +@end ifset +@end ifclear +immediately following an acute accent is taken as a literal character +and does not count as the end of a statement. The value of a character +constant in a numeric expression is the machine's byte-wide code for +that character. @code{@value{AS}} assumes your character code is ASCII: +@kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill + +@node Numbers +@subsection Number Constants + +@cindex constants, number +@cindex number constants +@code{@value{AS}} distinguishes three kinds of numbers according to how they +are stored in the target machine. @emph{Integers} are numbers that +would fit into an @code{int} in the C language. @emph{Bignums} are +integers, but they are stored in more than 32 bits. @emph{Flonums} +are floating point numbers, described below. + +@menu +* Integers:: Integers +* Bignums:: Bignums +* Flonums:: Flonums +@ifclear GENERIC +@ifset I960 +* Bit Fields:: Bit Fields +@end ifset +@end ifclear +@end menu + +@node Integers +@subsubsection Integers +@cindex integers +@cindex constants, integer + +@cindex binary integers +@cindex integers, binary +A binary integer is @samp{0b} or @samp{0B} followed by zero or more of +the binary digits @samp{01}. + +@cindex octal integers +@cindex integers, octal +An octal integer is @samp{0} followed by zero or more of the octal +digits (@samp{01234567}). + +@cindex decimal integers +@cindex integers, decimal +A decimal integer starts with a non-zero digit followed by zero or +more digits (@samp{0123456789}). + +@cindex hexadecimal integers +@cindex integers, hexadecimal +A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or +more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}. + +Integers have the usual values. To denote a negative integer, use +the prefix operator @samp{-} discussed under expressions +(@pxref{Prefix Ops,,Prefix Operators}). + +@node Bignums +@subsubsection Bignums + +@cindex bignums +@cindex constants, bignum +A @dfn{bignum} has the same syntax and semantics as an integer +except that the number (or its negative) takes more than 32 bits to +represent in binary. The distinction is made because in some places +integers are permitted while bignums are not. + +@node Flonums +@subsubsection Flonums +@cindex flonums +@cindex floating point numbers +@cindex constants, floating point + +@cindex precision, floating point +A @dfn{flonum} represents a floating point number. The translation is +indirect: a decimal floating point number from the text is converted by +@code{@value{AS}} to a generic binary floating point number of more than +sufficient precision. This generic floating point number is converted +to a particular computer's floating point format (or formats) by a +portion of @code{@value{AS}} specialized to that computer. + +A flonum is written by writing (in order) +@itemize @bullet +@item +The digit @samp{0}. +@ifset HPPA +(@samp{0} is optional on the HPPA.) +@end ifset + +@item +A letter, to tell @code{@value{AS}} the rest of the number is a flonum. +@ifset GENERIC +@kbd{e} is recommended. Case is not important. +@ignore +@c FIXME: verify if flonum syntax really this vague for most cases +(Any otherwise illegal letter works here, but that might be changed. Vax BSD +4.2 assembler seems to allow any of @samp{defghDEFGH}.) +@end ignore + +On the H8/300, H8/500, +Hitachi SH, +and AMD 29K architectures, the letter must be +one of the letters @samp{DFPRSX} (in upper or lower case). + +On the ARC, the letter must be one of the letters @samp{DFRS} +(in upper or lower case). + +On the Intel 960 architecture, the letter must be +one of the letters @samp{DFT} (in upper or lower case). + +On the HPPA architecture, the letter must be @samp{E} (upper case only). +@end ifset +@ifclear GENERIC +@ifset A29K +One of the letters @samp{DFPRSX} (in upper or lower case). +@end ifset +@ifset ARC +One of the letters @samp{DFRS} (in upper or lower case). +@end ifset +@ifset H8 +One of the letters @samp{DFPRSX} (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 +An optional sign: either @samp{+} or @samp{-}. + +@item +An optional @dfn{integer part}: zero or more decimal digits. + +@item +An optional @dfn{fractional part}: @samp{.} followed by zero +or more decimal digits. + +@item +An optional exponent, consisting of: + +@itemize @bullet +@item +An @samp{E} or @samp{e}. +@c I can't find a config where "EXP_CHARS" is other than 'eE', but in +@c principle this can perfectly well be different on different targets. +@item +Optional sign: either @samp{+} or @samp{-}. +@item +One or more decimal digits. +@end itemize + +@end itemize + +At least one of the integer part or the fractional part must be +present. The floating point number has the usual base-10 value. + +@code{@value{AS}} does all processing using integers. Flonums are computed +independently of any floating point hardware in the computer running +@code{@value{AS}}. + +@ifclear GENERIC +@ifset I960 +@c Bit fields are written as a general facility but are also controlled +@c by a conditional-compilation flag---which is as of now (21mar91) +@c turned on only by the i960 config of GAS. +@node Bit Fields +@subsubsection Bit Fields + +@cindex bit fields +@cindex constants, bit field +You can also define numeric constants as @dfn{bit fields}. +specify two numbers separated by a colon--- +@example +@var{mask}:@var{value} +@end example +@noindent +@code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and +@var{value}. + +The resulting number is then packed +@ifset GENERIC +@c this conditional paren in case bit fields turned on elsewhere than 960 +(in host-dependent byte order) +@end ifset +into a field whose width depends on which assembler directive has the +bit-field as its argument. Overflow (a result from the bitwise and +requiring more binary digits to represent) is not an error; instead, +more constants are generated, of the specified width, beginning with the +least significant digits.@refill + +The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long}, +@code{.short}, and @code{.word} accept bit-field arguments. +@end ifset +@end ifclear + +@node Sections +@chapter Sections and Relocation +@cindex sections +@cindex relocation + +@menu +* Secs Background:: Background +* Ld Sections:: Linker Sections +* As Sections:: Assembler Internal Sections +* Sub-Sections:: Sub-Sections +* bss:: bss Section +@end menu + +@node Secs Background +@section Background + +Roughly, a section is a range of addresses, with no gaps; all data +``in'' those addresses is treated the same for some particular purpose. +For example there may be a ``read only'' section. + +@cindex linker, and assembler +@cindex assembler, and linker +The linker @code{@value{LD}} reads many object files (partial programs) and +combines their contents to form a runnable program. When @code{@value{AS}} +emits an object file, the partial program is assumed to start at address 0. +@code{@value{LD}} assigns the final addresses for the partial program, so that +different partial programs do not overlap. This is actually an +oversimplification, but it suffices to explain how @code{@value{AS}} uses +sections. + +@code{@value{LD}} moves blocks of bytes of your program to their run-time +addresses. These blocks slide to their run-time addresses as rigid +units; their length does not change and neither does the order of bytes +within them. Such a rigid unit is called a @emph{section}. Assigning +run-time addresses to sections is called @dfn{relocation}. It includes +the task of adjusting mentions of object-file addresses so they refer to +the proper run-time addresses. +@ifset H8 +For the H8/300 and H8/500, +and for the Hitachi SH, +@code{@value{AS}} pads sections if needed to +ensure they end on a word (sixteen bit) boundary. +@end ifset + +@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. + +@ifset COFF +@ifset GENERIC +When it generates COFF output, +@end ifset +@code{@value{AS}} can also generate whatever other named sections you specify +using the @samp{.section} directive (@pxref{Section,,@code{.section}}). +If you do not use any directives that place output in the @samp{.text} +or @samp{.data} sections, these sections still exist, but are empty. +@end ifset + +@ifset HPPA +@ifset GENERIC +When @code{@value{AS}} generates SOM or ELF output for the HPPA, +@end ifset +@code{@value{AS}} can also generate whatever other named sections you +specify using the @samp{.space} and @samp{.subspace} directives. See +@cite{HP9000 Series 800 Assembly Language Reference Manual} +(HP 92432-90001) for details on the @samp{.space} and @samp{.subspace} +assembler directives. + +@ifset SOM +Additionally, @code{@value{AS}} uses different names for the standard +text, data, and bss sections when generating SOM output. Program text +is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and +BSS into @samp{$BSS$}. +@end ifset +@end ifset + +Within the object file, the text section starts at address @code{0}, the +data section follows, and the bss section follows the data section. + +@ifset HPPA +When generating either SOM or ELF output files on the HPPA, the text +section starts at address @code{0}, the data section at address +@code{0x4000000}, and the bss section follows the data section. +@end ifset + +To let @code{@value{LD}} know which data changes when the sections are +relocated, and how to change that data, @code{@value{AS}} also writes to the +object file details of the relocation needed. To perform relocation +@code{@value{LD}} must know, each time an address in the object +file is mentioned: +@itemize @bullet +@item +Where in the object file is the beginning of this reference to +an address? +@item +How long (in bytes) is this reference? +@item +Which section does the address refer to? What is the numeric value of +@display +(@var{address}) @minus{} (@var{start-address of section})? +@end display +@item +Is the reference to an address ``Program-Counter relative''? +@end itemize + +@cindex addresses, format of +@cindex section-relative addressing +In fact, every address @code{@value{AS}} ever uses is expressed as +@display +(@var{section}) + (@var{offset into section}) +@end display +@noindent +Further, most expressions @code{@value{AS}} computes have this section-relative +nature. +@ifset SOM +(For some object formats, such as SOM for the HPPA, some expressions are +symbol-relative instead.) +@end ifset + +In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset +@var{N} into section @var{secname}.'' + +Apart from text, data and bss sections you need to know about the +@dfn{absolute} section. When @code{@value{LD}} mixes partial programs, +addresses in the absolute section remain unchanged. For example, address +@code{@{absolute 0@}} is ``relocated'' to run-time address 0 by +@code{@value{LD}}. Although the linker never arranges two partial programs' +data sections with overlapping addresses after linking, @emph{by definition} +their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one +part of a program is always the same address when the program is running as +address @code{@{absolute@ 239@}} in any other part of the program. + +The idea of sections is extended to the @dfn{undefined} section. Any +address whose section is unknown at assembly time is by definition +rendered @{undefined @var{U}@}---where @var{U} is filled in later. +Since numbers are always defined, the only way to generate an undefined +address is to mention an undefined symbol. A reference to a named +common block would be such a symbol: its value is unknown at assembly +time so it has section @emph{undefined}. + +By analogy the word @emph{section} is used to describe groups of sections in +the linked program. @code{@value{LD}} puts all partial programs' text +sections in contiguous addresses in the linked program. It is +customary to refer to the @emph{text section} of a program, meaning all +the addresses of all partial programs' text sections. Likewise for +data and bss sections. + +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 Linker Sections +@code{@value{LD}} deals with just four kinds of sections, summarized below. + +@table @strong + +@ifset COFF +@cindex named sections +@cindex sections, named +@item named sections +@end ifset +@ifset aout-bout +@cindex text section +@cindex data section +@itemx text section +@itemx data section +@end ifset +These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as +separate but equal sections. Anything you can say of one section is +true another. +@ifset aout-bout +When the program is running, however, it is +customary for the text section to be unalterable. The +text section is often shared among processes: it contains +instructions, constants and the like. The data section of a running +program is usually alterable: for example, C variables would be stored +in the data section. +@end ifset + +@cindex bss section +@item bss section +This section contains zeroed bytes when your program begins running. It +is used to hold unitialized variables or common storage. The length of +each partial program's bss section is important, but because it starts +out containing zeroed bytes there is no need to store explicit zero +bytes in the object file. The bss section was invented to eliminate +those explicit zeros from object files. + +@cindex absolute section +@item absolute section +Address 0 of this section is always ``relocated'' to runtime address 0. +This is useful if you want to refer to an address that @code{@value{LD}} must +not change when relocating. In this sense we speak of absolute +addresses being ``unrelocatable'': they do not change during relocation. + +@cindex undefined section +@item undefined section +This ``section'' is a catch-all for address references to objects not in +the preceding sections. +@c FIXME: ref to some other doc on obj-file formats could go here. +@end table + +@cindex relocation example +An idealized example of three relocatable sections follows. +@ifset COFF +The example uses the traditional section names @samp{.text} and @samp{.data}. +@end ifset +Memory addresses are on the horizontal axis. + +@c TEXI2ROFF-KILL +@ifinfo +@c END TEXI2ROFF-KILL +@smallexample + +-----+----+--+ +partial program # 1: |ttttt|dddd|00| + +-----+----+--+ + + text data bss + seg. seg. seg. + + +---+---+---+ +partial program # 2: |TTT|DDD|000| + +---+---+---+ + + +--+---+-----+--+----+---+-----+~~ +linked program: | |TTT|ttttt| |dddd|DDD|00000| + +--+---+-----+--+----+---+-----+~~ + + addresses: 0 @dots{} +@end smallexample +@c TEXI2ROFF-KILL +@end ifinfo +@need 5000 +@tex + +\line{\it Partial program \#1: \hfil} +\line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} +\line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil} + +\line{\it Partial program \#2: \hfil} +\line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} +\line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil} + +\line{\it linked program: \hfil} +\line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil} +\line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt +ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt +DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil} + +\line{\it addresses: \hfil} +\line{0\dots\hfil} + +@end tex +@c END TEXI2ROFF-KILL + +@node As Sections +@section Assembler Internal 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 +sections for most purposes; but they can be mentioned in @code{@value{AS}} +warning messages, so it might be helpful to have an idea of their +meanings to @code{@value{AS}}. These sections are used to permit the +value of every expression in your assembly language program to be a +section-relative address. + +@table @b +@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. + +@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. +@c FIXME item debug +@c FIXME item transfer[t] vector preload +@c FIXME item transfer[t] vector postload +@c FIXME item register +@end table + +@node Sub-Sections +@section Sub-Sections + +@cindex numbered subsections +@cindex grouping data +@ifset aout-bout +Assembled bytes +@ifset COFF +conventionally +@end ifset +fall into two sections: text and data. +@end ifset +You may have separate groups of +@ifset GENERIC +data in named sections +@end ifset +@ifclear GENERIC +@ifclear aout-bout +data in named sections +@end ifclear +@ifset aout-bout +text or data +@end ifset +@end ifclear +that you want to end up near to each other in the object file, even though they +are not contiguous in the assembler source. @code{@value{AS}} allows you to +use @dfn{subsections} for this purpose. Within each section, there can be +numbered subsections with values from 0 to 8192. Objects assembled into the +same subsection go into the object file together with other objects in the same +subsection. For example, a compiler might want to store constants in the text +section, but might not want to have them interspersed with the program being +assembled. In this case, the compiler could issue a @samp{.text 0} before each +section of code being output, and a @samp{.text 1} before each group of +constants being output. + +Subsections are optional. If you do not use subsections, everything +goes in subsection number zero. + +@ifset GENERIC +Each subsection is zero-padded up to a multiple of four bytes. +(Subsections may be padded a different amount on different flavors +of @code{@value{AS}}.) +@end ifset +@ifclear GENERIC +@ifset H8 +On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word +boundary (two bytes). +The same is true on the Hitachi SH. +@end ifset +@ifset I960 +@c FIXME section padding (alignment)? +@c Rich Pixley says padding here depends on target obj code format; that +@c doesn't seem particularly useful to say without further elaboration, +@c so for now I say nothing about it. If this is a generic BFD issue, +@c these paragraphs might need to vanish from this manual, and be +@c discussed in BFD chapter of binutils (or some such). +@end ifset +@ifset A29K +On the AMD 29K family, no particular padding is added to section or +subsection sizes; @value{AS} forces no alignment on this platform. +@end ifset +@end ifclear + +Subsections appear in your object file in numeric order, lowest numbered +to highest. (All this to be compatible with other people's assemblers.) +The object file contains no representation of subsections; @code{@value{LD}} and +other programs that manipulate object files see no trace of them. +They just see all your text subsections as a text section, and all your +data subsections as a data section. + +To specify which subsection you want subsequent statements assembled +into, use a numeric argument to specify it, in a @samp{.text +@var{expression}} or a @samp{.data @var{expression}} statement. +@ifset COFF +@ifset GENERIC +When generating COFF output, you +@end ifset +@ifclear GENERIC +You +@end ifclear +can also use an extra subsection +argument with arbitrary named sections: @samp{.section @var{name}, +@var{expression}}. +@end ifset +@var{Expression} should be an absolute expression. +(@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0} +is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly +begins in @code{text 0}. For instance: +@smallexample +.text 0 # The default subsection is text 0 anyway. +.ascii "This lives in the first text subsection. *" +.text 1 +.ascii "But this lives in the second text subsection." +.data 0 +.ascii "This lives in the data section," +.ascii "in the first data subsection." +.text 0 +.ascii "This lives in the first text section," +.ascii "immediately following the asterisk (*)." +@end smallexample + +Each section has a @dfn{location counter} incremented by one for every byte +assembled into that section. Because subsections are merely a convenience +restricted to @code{@value{AS}} there is no concept of a subsection location +counter. There is no way to directly manipulate a location counter---but the +@code{.align} directive changes it, and any label definition captures its +current value. The location counter of the section where statements are being +assembled is said to be the @dfn{active} location counter. + +@node bss +@section bss Section + +@cindex bss section +@cindex common variable storage +The bss section is used for local common variable storage. +You may allocate address space in the bss section, but you may +not dictate data to load into it before your program executes. When +your program starts running, all the contents of the bss +section are zeroed bytes. + +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 + +@cindex symbols +Symbols are a central concept: the programmer uses symbols to name +things, the linker uses symbols to link, and the debugger uses symbols +to debug. + +@quotation +@cindex debuggers, and symbol order +@emph{Warning:} @code{@value{AS}} does not place symbols in the object file in +the same order they were declared. This may break some debuggers. +@end quotation + +@menu +* Labels:: Labels +* Setting Symbols:: Giving Symbols Other Values +* Symbol Names:: Symbol Names +* Dot:: The Special Dot Symbol +* Symbol Attributes:: Symbol Attributes +@end menu + +@node Labels +@section Labels + +@cindex labels +A @dfn{label} is written as a symbol immediately followed by a colon +@samp{:}. The symbol then represents the current value of the +active location counter, and is, for example, a suitable instruction +operand. You are warned if you use the same symbol to represent two +different locations: the first definition overrides any other +definitions. + +@ifset HPPA +On the HPPA, the usual form for a label need not be immediately followed by a +colon, but instead must start in column zero. Only one label may be defined on +a single line. To work around this, the HPPA version of @code{@value{AS}} also +provides a special directive @code{.label} for defining labels more flexibly. +@end ifset + +@node Setting Symbols +@section Giving Symbols Other Values + +@cindex assigning values to symbols +@cindex symbol values, assigning +A symbol can be given an arbitrary value by writing a symbol, followed +by an equals sign @samp{=}, followed by an expression +(@pxref{Expressions}). This is equivalent to using the @code{.set} +directive. @xref{Set,,@code{.set}}. + +@node Symbol Names +@section Symbol Names + +@cindex symbol names +@cindex names, symbol +@ifclear SPECIAL-SYMS +Symbol names begin with a letter or with one of @samp{._}. On most +machines, you can also use @code{$} in symbol names; exceptions are +noted in @ref{Machine Dependencies}. That character may be followed by any +string of digits, letters, dollar signs (unless otherwise noted in +@ref{Machine Dependencies}), and underscores. +@end ifclear +@ifset A29K +For the AMD 29K family, @samp{?} is also allowed in the +body of a symbol name, though not at its beginning. +@end ifset + +@ifset SPECIAL-SYMS +@ifset H8 +Symbol names begin with a letter or with one of @samp{._}. On the +Hitachi SH or the +H8/500, you can also use @code{$} in symbol names. That character may +be followed by any string of digits, letters, dollar signs (save on the +H8/300), and underscores. +@end ifset +@end ifset + +Case of letters is significant: @code{foo} is a different symbol name +than @code{Foo}. + +Each symbol has exactly one name. Each name in an assembly language program +refers to exactly one symbol. You may use that symbol name any number of times +in a program. + +@subheading Local Symbol Names + +@cindex local symbol names +@cindex symbol names, local +@cindex temporary symbol names +@cindex symbol names, temporary +Local symbols help compilers and programmers use names temporarily. +There are ten local symbol names, which are re-used throughout the +program. You may refer to them using the names @samp{0} @samp{1} +@dots{} @samp{9}. To define a local symbol, write a label of the form +@samp{@b{N}:} (where @b{N} represents any digit). To refer to the most +recent previous definition of that symbol write @samp{@b{N}b}, using the +same digit as when you defined the label. To refer to the next +definition of a local label, write @samp{@b{N}f}---where @b{N} gives you +a choice of 10 forward references. The @samp{b} stands for +``backwards'' and the @samp{f} stands for ``forwards''. + +Local symbols are not emitted by the current @sc{gnu} C compiler. + +There is no restriction on how you can use these labels, but +remember that at any point in the assembly you can refer to at most +10 prior local labels and to at most 10 forward local labels. + +Local symbol names are only a notation device. They are immediately +transformed into more conventional symbol names before the assembler +uses them. The symbol names stored in the symbol table, appearing in +error messages and optionally emitted to the object file have these +parts: + +@table @code +@item L +All local labels begin with @samp{L}. Normally both @code{@value{AS}} and +@code{@value{LD}} forget symbols that start with @samp{L}. These labels are +used for symbols you are never intended to see. If you use the +@samp{-L} option then @code{@value{AS}} retains these symbols in the +object file. If you also instruct @code{@value{LD}} to retain these symbols, +you may use them in debugging. + +@item @var{digit} +If the label is written @samp{0:} then the digit is @samp{0}. +If the label is written @samp{1:} then the digit is @samp{1}. +And so on up through @samp{9:}. + +@item @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}. + +@item @emph{ordinal number} +This is a serial number to keep the labels distinct. The first +@samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the +number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:} +through @samp{9:}. +@end table + +For instance, the first @code{1:} is named @code{L1@kbd{C-A}1}, the 44th +@code{3:} is named @code{L3@kbd{C-A}44}. + +@node Dot +@section The Special Dot Symbol + +@cindex dot (symbol) +@cindex @code{.} (symbol) +@cindex current address +@cindex location counter +The special symbol @samp{.} refers to the current address that +@code{@value{AS}} is assembling into. Thus, the expression @samp{melvin: +.long .} defines @code{melvin} to contain its own address. +Assigning a value to @code{.} is treated the same as a @code{.org} +directive. Thus, the expression @samp{.=.+4} is the same as saying +@ifclear no-space-dir +@samp{.space 4}. +@end ifclear +@ifset no-space-dir +@ifset A29K +@samp{.block 4}. +@end ifset +@end ifset + +@node Symbol Attributes +@section Symbol Attributes + +@cindex symbol attributes +@cindex attributes, symbol +Every symbol has, as well as its name, the attributes ``Value'' and +``Type''. Depending on output format, symbols can also have auxiliary +attributes. +@ifset INTERNALS +The detailed definitions are in @file{a.out.h}. +@end ifset + +If you use a symbol without defining it, @code{@value{AS}} assumes zero for +all these attributes, and probably won't warn you. This makes the +symbol an externally defined symbol, which is generally what you +would want. + +@menu +* Symbol Value:: Value +* Symbol Type:: Type +@ifset aout-bout +@ifset GENERIC +* a.out Symbols:: Symbol Attributes: @code{a.out} +@end ifset +@ifclear GENERIC +@ifclear BOUT +* a.out Symbols:: Symbol Attributes: @code{a.out} +@end ifclear +@ifset BOUT +* a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out} +@end ifset +@end ifclear +@end ifset +@ifset COFF +* COFF Symbols:: Symbol Attributes for COFF +@end ifset +@ifset SOM +* SOM Symbols:: Symbol Attributes for SOM +@end ifset +@end menu + +@node Symbol Value +@subsection Value + +@cindex value of a symbol +@cindex symbol value +The value of a symbol is (usually) 32 bits. For a symbol which labels a +location in the text, data, bss or absolute sections the value is the +number of addresses from the start of that section to the label. +Naturally for text, data and bss sections the value of a symbol changes +as @code{@value{LD}} changes section base addresses during linking. Absolute +symbols' values do not change during linking: that is why they are +called absolute. + +The value of an undefined symbol is treated in a special way. If it is +0 then the symbol is not defined in this assembler source file, and +@code{@value{LD}} tries to determine its value from other files linked into the +same program. You make this kind of symbol simply by mentioning a symbol +name without defining it. A non-zero value represents a @code{.comm} +common declaration. The value is how much common storage to reserve, in +bytes (addresses). The symbol refers to the first address of the +allocated storage. + +@node Symbol Type +@subsection Type + +@cindex type of a symbol +@cindex symbol type +The type attribute of a symbol contains relocation (section) +information, any flag settings indicating that a symbol is external, and +(optionally), other information for linkers and debuggers. The exact +format depends on the object-code output format in use. + +@ifset aout-bout +@ifclear GENERIC +@ifset BOUT +@c The following avoids a "widow" subsection title. @group would be +@c better if it were available outside examples. +@need 1000 +@node a.out Symbols +@subsection Symbol Attributes: @code{a.out}, @code{b.out} + +@cindex @code{b.out} symbol attributes +@cindex symbol attributes, @code{b.out} +These symbol attributes appear only when @code{@value{AS}} is configured for +one of the Berkeley-descended object output formats---@code{a.out} or +@code{b.out}. + +@end ifset +@ifclear BOUT +@node a.out Symbols +@subsection Symbol Attributes: @code{a.out} + +@cindex @code{a.out} symbol attributes +@cindex symbol attributes, @code{a.out} + +@end ifclear +@end ifclear +@ifset GENERIC +@node a.out Symbols +@subsection Symbol Attributes: @code{a.out} + +@cindex @code{a.out} symbol attributes +@cindex symbol attributes, @code{a.out} + +@end ifset +@menu +* Symbol Desc:: Descriptor +* Symbol Other:: Other +@end menu + +@node Symbol Desc +@subsubsection Descriptor + +@cindex descriptor, of @code{a.out} symbol +This is an arbitrary 16-bit value. You may establish a symbol's +descriptor value by using a @code{.desc} statement +(@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to +@code{@value{AS}}. + +@node Symbol Other +@subsubsection Other + +@cindex other attribute, of @code{a.out} symbol +This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}. +@end ifset + +@ifset COFF +@node COFF Symbols +@subsection Symbol Attributes for COFF + +@cindex COFF symbol attributes +@cindex symbol attributes, COFF + +The COFF format supports a multitude of auxiliary symbol attributes; +like the primary symbol attributes, they are set between @code{.def} and +@code{.endef} directives. + +@subsubsection Primary Attributes + +@cindex primary attributes, COFF symbols +The symbol name is set with @code{.def}; the value and type, +respectively, with @code{.val} and @code{.type}. + +@subsubsection Auxiliary Attributes + +@cindex auxiliary attributes, COFF symbols +The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl}, +@code{.size}, and @code{.tag} can generate auxiliary symbol table +information for COFF. +@end ifset + +@ifset SOM +@node SOM Symbols +@subsection Symbol Attributes for SOM + +@cindex SOM symbol attributes +@cindex symbol attributes, SOM + +The SOM format for the HPPA supports a multitude of symbol attributes set with +the @code{.EXPORT} and @code{.IMPORT} directives. + +The attributes are described in @cite{HP9000 Series 800 Assembly +Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and +@code{EXPORT} assembler directive documentation. +@end ifset + +@node Expressions +@chapter Expressions + +@cindex expressions +@cindex addresses +@cindex numeric values +An @dfn{expression} specifies an address or numeric value. +Whitespace may precede and/or follow an expression. + +The result of an expression must be an absolute number, or else an offset into +a particular section. If an expression is not absolute, and there is not +enough information when @code{@value{AS}} sees the expression to know its +section, a second pass over the source program might be necessary to interpret +the expression---but the second pass is currently not implemented. +@code{@value{AS}} aborts with an error message in this situation. + +@menu +* Empty Exprs:: Empty Expressions +* Integer Exprs:: Integer Expressions +@end menu + +@node Empty Exprs +@section Empty Expressions + +@cindex empty expressions +@cindex expressions, empty +An empty expression has no value: it is just whitespace or null. +Wherever an absolute expression is required, you may omit the +expression, and @code{@value{AS}} assumes a value of (absolute) 0. This +is compatible with other assemblers. + +@node Integer Exprs +@section Integer Expressions + +@cindex integer expressions +@cindex expressions, integer +An @dfn{integer expression} is one or more @emph{arguments} delimited +by @emph{operators}. + +@menu +* Arguments:: Arguments +* Operators:: Operators +* Prefix Ops:: Prefix Operators +* Infix Ops:: Infix Operators +@end menu + +@node Arguments +@subsection Arguments + +@cindex expression arguments +@cindex arguments in expressions +@cindex operands in expressions +@cindex arithmetic operands +@dfn{Arguments} are symbols, numbers or subexpressions. In other +contexts arguments are sometimes called ``arithmetic operands''. In +this manual, to avoid confusing them with the ``instruction operands'' of +the machine language, we use the term ``argument'' to refer to parts of +expressions only, reserving the word ``operand'' to refer only to machine +instruction operands. + +Symbols are evaluated to yield @{@var{section} @var{NNN}@} where +@var{section} is one of text, data, bss, absolute, +or undefined. @var{NNN} is a signed, 2's complement 32 bit +integer. + +Numbers are usually integers. + +A number can be a flonum or bignum. In this case, you are warned +that only the low order 32 bits are used, and @code{@value{AS}} pretends +these 32 bits are an integer. You may write integer-manipulating +instructions that act on exotic constants, compatible with other +assemblers. + +@cindex subexpressions +Subexpressions are a left parenthesis @samp{(} followed by an integer +expression, followed by a right parenthesis @samp{)}; or a prefix +operator followed by an argument. + +@node Operators +@subsection Operators + +@cindex operators, in expressions +@cindex arithmetic functions +@cindex functions, in expressions +@dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix +operators are followed by an argument. Infix operators appear +between their arguments. Operators may be preceded and/or followed by +whitespace. + +@node Prefix Ops +@subsection Prefix Operator + +@cindex prefix operators +@code{@value{AS}} has the following @dfn{prefix operators}. They each take +one argument, which must be absolute. + +@c the tex/end tex stuff surrounding this small table is meant to make +@c it align, on the printed page, with the similar table in the next +@c section (which is inside an enumerate). +@tex +\global\advance\leftskip by \itemindent +@end tex + +@table @code +@item - +@dfn{Negation}. Two's complement negation. +@item ~ +@dfn{Complementation}. Bitwise not. +@end table + +@tex +\global\advance\leftskip by -\itemindent +@end tex + +@node Infix Ops +@subsection Infix Operators + +@cindex infix operators +@cindex operators, permitted arguments +@dfn{Infix operators} take two arguments, one on either side. Operators +have precedence, but operations with equal precedence are performed left +to right. Apart from @code{+} or @code{-}, both arguments must be +absolute, and the result is absolute. + +@enumerate +@cindex operator precedence +@cindex precedence of operators + +@item +Highest Precedence + +@table @code +@item * +@dfn{Multiplication}. + +@item / +@dfn{Division}. Truncation is the same as the C operator @samp{/} + +@item % +@dfn{Remainder}. + +@item < +@itemx << +@dfn{Shift Left}. Same as the C operator @samp{<<}. + +@item > +@itemx >> +@dfn{Shift Right}. Same as the C operator @samp{>>}. +@end table + +@item +Intermediate precedence + +@table @code +@item | + +@dfn{Bitwise Inclusive Or}. + +@item & +@dfn{Bitwise And}. + +@item ^ +@dfn{Bitwise Exclusive Or}. + +@item ! +@dfn{Bitwise Or Not}. +@end table + +@item +Lowest Precedence + +@table @code +@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. + +@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. +You may not subtract arguments from different sections. +@c FIXME is there still something useful to say about undefined - undefined ? +@end table +@end enumerate + +In short, it's only meaningful to add or subtract the @emph{offsets} in an +address; you can only have a defined section in one of the two arguments. + +@node Pseudo Ops +@chapter Assembler Directives + +@cindex directives, machine independent +@cindex pseudo-ops, machine independent +@cindex machine independent directives +All assembler directives have names that begin with a period (@samp{.}). +The rest of the name is letters, usually in lower case. + +This chapter discusses directives that are available regardless of the +target machine configuration for the @sc{gnu} assembler. +@ifset GENERIC +Some machine configurations provide additional directives. +@xref{Machine Dependencies}. +@end ifset +@ifclear GENERIC +@ifset machine-directives +@xref{Machine Dependencies} for additional directives. +@end ifset +@end ifclear + +@menu +* Abort:: @code{.abort} +@ifset COFF +* ABORT:: @code{.ABORT} +@end ifset + +* Align:: @code{.align @var{abs-expr} , @var{abs-expr}} +* Ascii:: @code{.ascii "@var{string}"}@dots{} +* Asciz:: @code{.asciz "@var{string}"}@dots{} +* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}} +* Byte:: @code{.byte @var{expressions}} +* Comm:: @code{.comm @var{symbol} , @var{length} } +* Data:: @code{.data @var{subsection}} +@ifset COFF +* Def:: @code{.def @var{name}} +@end ifset +@ifset aout-bout +* Desc:: @code{.desc @var{symbol}, @var{abs-expression}} +@end ifset +@ifset COFF +* Dim:: @code{.dim} +@end ifset + +* Double:: @code{.double @var{flonums}} +* Eject:: @code{.eject} +* Else:: @code{.else} +* 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}} +* hword:: @code{.hword @var{expressions}} +* Ident:: @code{.ident} +* If:: @code{.if @var{absolute expression}} +* Include:: @code{.include "@var{file}"} +* Int:: @code{.int @var{expressions}} +* 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 +* Line:: @code{.line @var{line-number}} +@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}} +* Print:: @code{.print @var{string}} +* Psize:: @code{.psize @var{lines}, @var{columns}} +* Purgem:: @code{.purgem @var{name}} +* Quad:: @code{.quad @var{bignums}} +* Rept:: @code{.rept @var{count}} +* Sbttl:: @code{.sbttl "@var{subheading}"} +@ifset COFF +* Scl:: @code{.scl @var{class}} +* 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 + +* 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 +* 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}"} +@ifset COFF +* Type:: @code{.type @var{int}} +* Val:: @code{.val @var{addr}} +@end ifset + +* Uleb128:: @code{.uleb128 @var{expressions}} +* Word:: @code{.word @var{expressions}} +* Deprecated:: Deprecated Directives +@end menu + +@node Abort +@section @code{.abort} + +@cindex @code{abort} directive +@cindex stopping the assembly +This directive stops the assembly immediately. It is for +compatibility with other assemblers. The original idea was that the +assembly language source would be piped into the assembler. If the sender +of the source quit, it could use this directive tells @code{@value{AS}} to +quit also. One day @code{.abort} will not be supported. + +@ifset COFF +@node ABORT +@section @code{.ABORT} + +@cindex @code{ABORT} directive +When producing COFF output, @code{@value{AS}} accepts this directive as a +synonym for @samp{.abort}. + +@ifset BOUT +When producing @code{b.out} output, @code{@value{AS}} accepts this directive, +but ignores it. +@end ifset +@end ifset + +@node Align +@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 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, 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 +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 +multiple of 8, no change is needed. + +This inconsistency is due to the different behaviors of the various +native assemblers for these systems which GAS must emulate. +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 Ascii +@section @code{.ascii "@var{string}"}@dots{} + +@cindex @code{ascii} directive +@cindex string literals +@code{.ascii} expects zero or more string literals (@pxref{Strings}) +separated by commas. It assembles each string (with no automatic +trailing zero byte) into consecutive addresses. + +@node Asciz +@section @code{.asciz "@var{string}"}@dots{} + +@cindex @code{asciz} directive +@cindex zero-terminated strings +@cindex null-terminated strings +@code{.asciz} is just like @code{.ascii}, but each string is followed by +a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''. + +@node Balign +@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 +Pad the location counter (in the current subsection) to a particular +storage boundary. The first expression (which must be absolute) is the +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 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}} + +@cindex @code{byte} directive +@cindex integers, one byte +@code{.byte} expects zero or more expressions, separated by commas. +Each expression is assembled into the next byte. + +@node Comm +@section @code{.comm @var{symbol} , @var{length} } + +@cindex @code{comm} directive +@cindex symbol, common +@code{.comm} declares a 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 +@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional. +@end ifset + +@node Data +@section @code{.data @var{subsection}} + +@cindex @code{data} directive +@code{.data} tells @code{@value{AS}} to assemble the following statements onto the +end of the data subsection numbered @var{subsection} (which is an +absolute expression). If @var{subsection} is omitted, it defaults +to zero. + +@ifset COFF +@node Def +@section @code{.def @var{name}} + +@cindex @code{def} directive +@cindex COFF symbols, debugging +@cindex debugging COFF symbols +Begin defining debugging information for a symbol @var{name}; the +definition extends until the @code{.endef} directive is encountered. +@ifset BOUT + +This directive is only observed when @code{@value{AS}} is configured for COFF +format output; when producing @code{b.out}, @samp{.def} is recognized, +but ignored. +@end ifset +@end ifset + +@ifset aout-bout +@node Desc +@section @code{.desc @var{symbol}, @var{abs-expression}} + +@cindex @code{desc} directive +@cindex COFF symbol descriptor +@cindex symbol descriptor, COFF +This directive sets the descriptor of the symbol (@pxref{Symbol Attributes}) +to the low 16 bits of an absolute expression. + +@ifset COFF +The @samp{.desc} directive is not available when @code{@value{AS}} is +configured for COFF output; it is only for @code{a.out} or @code{b.out} +object format. For the sake of compatibility, @code{@value{AS}} accepts +it, but produces no output, when configured for COFF. +@end ifset +@end ifset + +@ifset COFF +@node Dim +@section @code{.dim} + +@cindex @code{dim} directive +@cindex COFF auxiliary symbol information +@cindex auxiliary symbol information, COFF +This directive is generated by compilers to include auxiliary debugging +information in the symbol table. It is only permitted inside +@code{.def}/@code{.endef} pairs. +@ifset BOUT + +@samp{.dim} 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 + +@node Double +@section @code{.double @var{flonums}} + +@cindex @code{double} directive +@cindex floating point numbers (double) +@code{.double} expects zero or more flonums, separated by commas. It +assembles floating point numbers. +@ifset GENERIC +The exact kind of floating point numbers emitted depends on how +@code{@value{AS}} is configured. @xref{Machine Dependencies}. +@end ifset +@ifclear GENERIC +@ifset IEEEFLOAT +On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers +in @sc{ieee} format. +@end ifset +@end ifclear + +@node Eject +@section @code{.eject} + +@cindex @code{eject} directive +@cindex new page, in listings +@cindex page, in listings +@cindex listing control: new page +Force a page break at this point, when generating assembly listings. + +@node Else +@section @code{.else} + +@cindex @code{else} directive +@code{.else} is part of the @code{@value{AS}} support for conditional +assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section +of code to be assembled if the condition for the preceding @code{.if} +was false. + +@node End +@section @code{.end} + +@cindex @code{end} directive +@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 +@section @code{.endef} + +@cindex @code{endef} directive +This directive flags the end of a symbol definition begun with +@code{.def}. +@ifset BOUT + +@samp{.endef} is only meaningful when generating COFF format output; if +@code{@value{AS}} is configured to generate @code{b.out}, it accepts this +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} + +@cindex @code{endif} directive +@code{.endif} is part of the @code{@value{AS}} support for conditional assembly; +it marks the end of a block of code that is only assembled +conditionally. @xref{If,,@code{.if}}. + +@node Equ +@section @code{.equ @var{symbol}, @var{expression}} + +@cindex @code{equ} directive +@cindex assigning values to symbols +@cindex symbols, assigning values to +This directive sets the value of @var{symbol} to @var{expression}. +It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}. + +@ifset HPPA +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} + +@cindex @code{extern} directive +@code{.extern} is accepted in the source program---for compatibility +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}} + +@cindex @code{file} directive +@cindex logical file name +@cindex file name, logical +@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}. +@end ifset +@end ifclear + +@node Fill +@section @code{.fill @var{repeat} , @var{size} , @var{value}} + +@cindex @code{fill} directive +@cindex writing patterns in memory +@cindex patterns, writing in memory +@var{result}, @var{size} and @var{value} are absolute expressions. +This emits @var{repeat} copies of @var{size} bytes. @var{Repeat} +may be zero or more. @var{Size} may be zero or more, but if it is +more than 8, then it is deemed to have the value 8, compatible with +other people's assemblers. The contents of each @var{repeat} bytes +is taken from an 8-byte number. The highest order 4 bytes are +zero. The lowest order 4 bytes are @var{value} rendered in the +byte-order of an integer on the computer @code{@value{AS}} is assembling for. +Each @var{size} bytes in a repetition is taken from the lowest order +@var{size} bytes of this number. Again, this bizarre behavior is +compatible with other people's assemblers. + +@var{size} and @var{value} are optional. +If the second comma and @var{value} are absent, @var{value} is +assumed zero. If the first comma and following tokens are absent, +@var{size} is assumed to be 1. + +@node Float +@section @code{.float @var{flonums}} + +@cindex floating point numbers (single) +@cindex @code{float} directive +This directive assembles zero or more flonums, separated by commas. It +has the same effect as @code{.single}. +@ifset GENERIC +The exact kind of floating point numbers emitted depends on how +@code{@value{AS}} is configured. +@xref{Machine Dependencies}. +@end ifset +@ifclear GENERIC +@ifset IEEEFLOAT +On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers +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}} + +@cindex @code{global} directive +@cindex symbol, making visible to linker +@code{.global} makes the symbol visible to @code{@value{LD}}. If you define +@var{symbol} in your partial program, its value is made available to +other partial programs that are linked with it. Otherwise, +@var{symbol} takes its attributes from a symbol of the same name +from another file linked into the same program. + +Both spellings (@samp{.globl} and @samp{.global}) are accepted, for +compatibility with other assemblers. + +@ifset HPPA +On the HPPA, @code{.global} is not always enough to make it accessible to other +partial programs. You may need the HPPA-only @code{.EXPORT} directive as well. +@xref{HPPA Directives,, HPPA Assembler Directives}. +@end ifset + +@node hword +@section @code{.hword @var{expressions}} + +@cindex @code{hword} directive +@cindex integers, 16-bit +@cindex numbers, 16-bit +@cindex sixteen bit integers +This expects zero or more @var{expressions}, and emits +a 16 bit number for each. + +@ifset GENERIC +This directive is a synonym for @samp{.short}; depending on the target +architecture, it may also be a synonym for @samp{.word}. +@end ifset +@ifclear GENERIC +@ifset W32 +This directive is a synonym for @samp{.short}. +@end ifset +@ifset W16 +This directive is a synonym for both @samp{.short} and @samp{.word}. +@end ifset +@end ifclear + +@node Ident +@section @code{.ident} + +@cindex @code{ident} directive +This directive is used by some assemblers to place tags in object files. +@code{@value{AS}} simply accepts the directive for source-file +compatibility with such assemblers, but does not actually emit anything +for it. + +@node If +@section @code{.if @var{absolute expression}} + +@cindex conditional assembly +@cindex @code{if} directive +@code{.if} marks the beginning of a section of code which is only +considered part of the source program being assembled if the argument +(which must be an @var{absolute expression}) is non-zero. The end of +the conditional section of code must be marked by @code{.endif} +(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the +alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}). + +The following variants of @code{.if} are also supported: +@table @code +@cindex @code{ifdef} directive +@item .ifdef @var{symbol} +Assembles the following section of code if the specified @var{symbol} +has been defined. + +@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 +@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. + +@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. + +@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 +@section @code{.include "@var{file}"} + +@cindex @code{include} directive +@cindex supporting files, including +@cindex files, including +This directive provides a way to include supporting files at specified +points in your source program. The code from @var{file} is assembled as +if it followed the point of the @code{.include}; when the end of the +included file is reached, assembly of the original file continues. You +can control the search paths used with the @samp{-I} command-line option +(@pxref{Invoking,,Command-Line Options}). Quotation marks are required +around @var{file}. + +@node Int +@section @code{.int @var{expressions}} + +@cindex @code{int} directive +@cindex integers, 32-bit +Expect zero or more @var{expressions}, of any section, separated by commas. +For each expression, emit a number that, at run time, is the value of that +expression. The byte order and bit size of the number depends on what kind +of target the assembly is for. + +@ifclear GENERIC +@ifset H8 +On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit +integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits +32-bit integers. +@end ifset +@end ifclear + +@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}} + +@cindex @code{lcomm} directive +@cindex local common symbols +@cindex symbols, local common +Reserve @var{length} (an absolute expression) bytes for a local common +denoted by @var{symbol}. The section and value of @var{symbol} are +those of the new local common. The addresses are allocated in the bss +section, so 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. +@end ifset + +@node Lflags +@section @code{.lflags} + +@cindex @code{lflags} directive (ignored) +@code{@value{AS}} accepts this directive, for compatibility with other +assemblers, but ignores it. + +@ifclear no-line-dir +@node Line +@section @code{.line @var{line-number}} + +@cindex @code{line} directive +@end ifclear +@ifset no-line-dir +@node Ln +@section @code{.ln @var{line-number}} + +@cindex @code{ln} directive +@end ifset +@cindex logical line number +@ifset aout-bout +Change the logical line number. @var{line-number} must be an absolute +expression. The next line has that logical line number. Therefore any other +statements on the current line (after a statement separator character) are +reported as on logical line number @var{line-number} @minus{} 1. One day +@code{@value{AS}} will no longer support this directive: it is recognized only +for compatibility with existing assembler programs. + +@ifset GENERIC +@ifset A29K +@emph{Warning:} In the AMD29K configuration of @value{AS}, this command is +not available; use the synonym @code{.ln} in that context. +@end ifset +@end ifset +@end ifset + +@ifclear no-line-dir +Even though this is a directive associated with the @code{a.out} or +@code{b.out} object-code formats, @code{@value{AS}} still recognizes it +when producing COFF output, and treats @samp{.line} as though it +were the COFF @samp{.ln} @emph{if} it is found outside a +@code{.def}/@code{.endef} pair. + +Inside a @code{.def}, @samp{.line} is, instead, one of the directives +used by compilers to generate auxiliary symbol information for +debugging. +@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}} + +@cindex @code{ln} directive +@ifclear no-line-dir +@samp{.ln} is a synonym for @samp{.line}. +@end ifclear +@ifset no-line-dir +Tell @code{@value{AS}} to change the logical line number. @var{line-number} +must be an absolute expression. The next line has that logical +line number, so any other statements on the current line (after a +statement separator character @code{;}) are reported as on logical +line number @var{line-number} @minus{} 1. +@ifset BOUT + +This directive is accepted, but ignored, when @code{@value{AS}} is +configured for @code{b.out}; its effect is only associated with COFF +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} + +@cindex @code{list} directive +@cindex listing control, turning on +Control (in conjunction with the @code{.nolist} directive) whether or +not assembly listings are generated. These two directives maintain an +internal counter (which is zero initially). @code{.list} increments the +counter, and @code{.nolist} decrements it. Assembly listings are +generated whenever the counter is greater than zero. + +By default, listings are disabled. When you enable them (with the +@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}), +the initial value of the listing counter is one. + +@node Long +@section @code{.long @var{expressions}} + +@cindex @code{long} directive +@code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}. + +@ignore +@c no one seems to know what this is for or whether this description is +@c what it really ought to do +@node Lsym +@section @code{.lsym @var{symbol}, @var{expression}} + +@cindex @code{lsym} directive +@cindex symbol, not referenced in assembly +@code{.lsym} creates a new symbol named @var{symbol}, but does not put it in +the hash table, ensuring it cannot be referenced by name during the +rest of the assembly. This sets the attributes of the symbol to be +the same as the expression value: +@smallexample +@var{other} = @var{descriptor} = 0 +@var{type} = @r{(section of @var{expression})} +@var{value} = @var{expression} +@end smallexample +@noindent +The new symbol is not flagged as external. +@end ignore + +@node 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} + +@cindex @code{nolist} directive +@cindex listing control, turning off +Control (in conjunction with the @code{.list} directive) whether or +not assembly listings are generated. These two directives maintain an +internal counter (which is zero initially). @code{.list} increments the +counter, and @code{.nolist} decrements it. Assembly listings are +generated whenever the counter is greater than zero. + +@node Octa +@section @code{.octa @var{bignums}} + +@c FIXME: double size emitted for "octa" on i960, others? Or warn? +@cindex @code{octa} directive +@cindex integer, 16-byte +@cindex sixteen byte integer +This directive expects zero or more bignums, separated by commas. For each +bignum, it emits a 16-byte integer. + +The term ``octa'' comes from contexts in which a ``word'' is two bytes; +hence @emph{octa}-word for 16 bytes. + +@node Org +@section @code{.org @var{new-lc} , @var{fill}} + +@cindex @code{org} directive +@cindex location counter, advancing +@cindex advancing location counter +@cindex current address, advancing +Advance the location counter of the current section to +@var{new-lc}. @var{new-lc} is either an absolute expression or an +expression with the same section as the current subsection. That is, +you can't use @code{.org} to cross sections: if @var{new-lc} has the +wrong section, the @code{.org} directive is ignored. To be compatible +with former assemblers, if the section of @var{new-lc} is absolute, +@code{@value{AS}} issues a warning, then pretends the section of @var{new-lc} +is the same as the current subsection. + +@code{.org} may only increase the location counter, or leave it +unchanged; you cannot use @code{.org} to move the location counter +backwards. + +@c double negative used below "not undefined" because this is a specific +@c reference to "undefined" (as SEG_UNKNOWN is called in this manual) +@c section. 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. + +Beware that the origin is relative to the start of the section, not +to the start of the subsection. This is compatible with other +people's assemblers. + +When the location counter (of the current subsection) is advanced, the +intervening bytes are filled with @var{fill} which should be an +absolute expression. If the comma and @var{fill} are omitted, +@var{fill} defaults to zero. + +@node P2align +@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 +Pad the location counter (in the current subsection) to a particular +storage boundary. The first expression (which must be absolute) is the +number of low-order zero bits the location counter must have after +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 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. + +@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. + +@node Psize +@section @code{.psize @var{lines} , @var{columns}} + +@cindex @code{psize} directive +@cindex listing control: paper size +@cindex paper size, for listings +Use this directive to declare the number of lines---and, optionally, the +number of columns---to use for each page, when generating listings. + +If you do not use @code{.psize}, listings use a default line-count +of 60. You may omit the comma and @var{columns} specification; the +default width is 200 columns. + +@code{@value{AS}} generates formfeeds whenever the specified number of +lines is exceeded (or whenever you explicitly request one, using +@code{.eject}). + +If you specify @var{lines} as @code{0}, no formfeeds are generated save +those explicitly specified with @code{.eject}. + +@node 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}. + +@node Quad +@section @code{.quad @var{bignums}} + +@cindex @code{quad} directive +@code{.quad} expects zero or more bignums, separated by commas. For +each bignum, it emits +@ifclear bignum-16 +an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a +warning message; and just takes the lowest order 8 bytes of the bignum. +@cindex eight-byte integer +@cindex integer, 8-byte + +The term ``quad'' comes from contexts in which a ``word'' is two bytes; +hence @emph{quad}-word for 8 bytes. +@end ifclear +@ifset bignum-16 +a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a +warning message; and just takes the lowest order 16 bytes of the bignum. +@cindex sixteen-byte integer +@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}"} + +@cindex @code{sbttl} directive +@cindex subtitles for listings +@cindex listing control: subtitle +Use @var{subheading} as the title (third line, immediately after the +title line) when generating assembly listings. + +This directive affects subsequent pages, as well as the current page if +it appears within ten lines of the top of a page. + +@ifset COFF +@node Scl +@section @code{.scl @var{class}} + +@cindex @code{scl} directive +@cindex symbol storage class (COFF) +@cindex COFF symbol storage class +Set the storage-class value for a symbol. This directive may only be +used inside a @code{.def}/@code{.endef} pair. Storage class may flag +whether a symbol is static or external, or it may record further +symbolic debugging information. +@ifset BOUT + +The @samp{.scl} directive is primarily associated with COFF output; when +configured to generate @code{b.out} output format, @code{@value{AS}} +accepts this directive but ignores it. +@end ifset +@end ifset + +@node Section +@section @code{.section @var{name}} + +@cindex @code{section} directive +@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. + +@ifset COFF +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 +@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}). +@end ifset + +@ifset ELF +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 +@end ifset + +@node Set +@section @code{.set @var{symbol}, @var{expression}} + +@cindex @code{set} directive +@cindex symbol value, setting +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 (@pxref{Symbol Attributes}). + +You may @code{.set} a symbol many times in the same assembly. + +If you @code{.set} a global symbol, the value stored in the object +file is the last value stored into it. + +@ifset HPPA +The syntax for @code{set} on the HPPA is +@samp{@var{symbol} .set @var{expression}}. +@end ifset + +@node Short +@section @code{.short @var{expressions}} + +@cindex @code{short} directive +@ifset GENERIC +@code{.short} is normally the same as @samp{.word}. +@xref{Word,,@code{.word}}. + +In some configurations, however, @code{.short} and @code{.word} generate +numbers of different lengths; @pxref{Machine Dependencies}. +@end ifset +@ifclear GENERIC +@ifset W16 +@code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}. +@end ifset +@ifset W32 +This expects zero or more @var{expressions}, and emits +a 16 bit number for each. +@end ifset +@end ifclear + +@node Single +@section @code{.single @var{flonums}} + +@cindex @code{single} directive +@cindex floating point numbers (single) +This directive assembles zero or more flonums, separated by commas. It +has the same effect as @code{.float}. +@ifset GENERIC +The exact kind of floating point numbers emitted depends on how +@code{@value{AS}} is configured. @xref{Machine Dependencies}. +@end ifset +@ifclear GENERIC +@ifset IEEEFLOAT +On the @value{TARGET} family, @code{.single} emits 32-bit floating point +numbers in @sc{ieee} format. +@end ifset +@end ifclear + +@ifset COFF +@node Size +@section @code{.size} + +@cindex @code{size} directive +This directive is generated by compilers to include auxiliary debugging +information in the symbol table. It is only permitted inside +@code{.def}/@code{.endef} pairs. +@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 + +@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}} + +@cindex @code{space} directive +@cindex filling memory +This directive emits @var{size} bytes, each of value @var{fill}. Both +@var{size} and @var{fill} are absolute expressions. If the comma +and @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same +as @samp{.skip}. + +@ifset HPPA +@quotation +@emph{Warning:} @code{.space} has a completely different meaning for HPPA +targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800 +Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the +@code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives}, +for a summary. +@end quotation +@end ifset +@end ifclear + +@ifset A29K +@ifclear GENERIC +@node Space +@section @code{.space} +@cindex @code{space} directive +@end ifclear +On the AMD 29K, this directive is ignored; it is accepted for +compatibility with other AMD 29K assemblers. + +@quotation +@emph{Warning:} In most versions of the @sc{gnu} assembler, the directive +@code{.space} has the effect of @code{.block} @xref{Machine Dependencies}. +@end quotation +@end ifset + +@ifset have-stabs +@node Stab +@section @code{.stabd, .stabn, .stabs} + +@cindex symbolic debuggers, information for +@cindex @code{stab@var{x}} directives +There are three directives that begin @samp{.stab}. +All emit symbols (@pxref{Symbols}), for use by symbolic debuggers. +The symbols are not entered in the @code{@value{AS}} hash table: they +cannot be referenced elsewhere in the source file. +Up to five fields are required: + +@table @var +@item string +This is the symbol's name. It may contain any character except +@samp{\000}, so is more general than ordinary symbol names. Some +debuggers used to code arbitrarily complex structures into symbol names +using this field. + +@item type +An absolute expression. The symbol's type is set to the low 8 bits of +this expression. Any bit pattern is permitted, but @code{@value{LD}} +and debuggers choke on silly bit patterns. + +@item other +An absolute expression. The symbol's ``other'' attribute is set to the +low 8 bits of this expression. + +@item desc +An absolute expression. The symbol's descriptor is set to the low 16 +bits of this expression. + +@item value +An absolute expression which becomes the symbol's value. +@end table + +If a warning is detected while reading a @code{.stabd}, @code{.stabn}, +or @code{.stabs} statement, the symbol has probably already been created; +you get a half-formed symbol in your object file. This is +compatible with earlier assemblers! + +@table @code +@cindex @code{stabd} directive +@item .stabd @var{type} , @var{other} , @var{desc} + +The ``name'' of the symbol generated is not even an empty string. +It is a null pointer, for compatibility. Older assemblers used a +null pointer so they didn't waste space in object files with empty +strings. + +The symbol's value is set to the location counter, +relocatably. When your program is linked, the value of this symbol +is the address of the location counter when the @code{.stabd} was +assembled. + +@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{""}. + +@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 +@c end have-stabs + +@node String +@section @code{.string} "@var{str}" + +@cindex string, copying to object file +@cindex @code{string} directive + +Copy the characters in @var{str} to the object file. You may specify more than +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 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 is used like this: +@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. The @code{.versym} 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. +@end ifset + +@ifset COFF +@node Tag +@section @code{.tag @var{structname}} + +@cindex COFF structure debugging +@cindex structure debugging, COFF +@cindex @code{tag} directive +This directive is generated by compilers to include auxiliary debugging +information in the symbol table. It is only permitted inside +@code{.def}/@code{.endef} pairs. Tags are used to link structure +definitions in the symbol table with instances of those structures. +@ifset BOUT + +@samp{.tag} is only used 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 + +@node Text +@section @code{.text @var{subsection}} + +@cindex @code{text} directive +Tells @code{@value{AS}} to assemble the following statements onto the end of +the text subsection numbered @var{subsection}, which is an absolute +expression. If @var{subsection} is omitted, subsection number zero +is used. + +@node Title +@section @code{.title "@var{heading}"} + +@cindex @code{title} directive +@cindex listing control: title line +Use @var{heading} as the title (second line, immediately after the +source file name and pagenumber) when generating assembly listings. + +This directive affects subsequent pages, as well as the current page if +it appears within ten lines of the top of a page. + +@ifset COFF +@node Type +@section @code{.type @var{int}} + +@cindex COFF symbol type +@cindex symbol type, COFF +@cindex @code{type} directive +This directive, permitted only within @code{.def}/@code{.endef} pairs, +records the integer @var{int} as the type attribute of a symbol table entry. +@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 + +@ifset COFF +@node Val +@section @code{.val @var{addr}} + +@cindex @code{val} directive +@cindex COFF value attribute +@cindex value attribute, COFF +This directive, permitted only within @code{.def}/@code{.endef} pairs, +records the address @var{addr} as the value attribute of a symbol table +entry. +@ifset BOUT + +@samp{.val} is used only for COFF output; when @code{@value{AS}} is +configured for @code{b.out}, it accepts this directive but ignores it. +@end ifset +@end ifset + +@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}}. + +@node Word +@section @code{.word @var{expressions}} + +@cindex @code{word} directive +This directive expects zero or more @var{expressions}, of any section, +separated by commas. +@ifclear GENERIC +@ifset W32 +For each expression, @code{@value{AS}} emits a 32-bit number. +@end ifset +@ifset W16 +For each expression, @code{@value{AS}} emits a 16-bit number. +@end ifset +@end ifclear +@ifset GENERIC + +The size of the number emitted, and its byte order, +depend on what target computer the assembly is for. +@end ifset + +@c on amd29k, i960, sparc the "special treatment to support compilers" doesn't +@c happen---32-bit addressability, period; no long/short jumps. +@ifset DIFF-TBL-KLUGE +@cindex difference tables altered +@cindex altered difference tables +@quotation +@emph{Warning: Special Treatment to support Compilers} +@end quotation + +@ifset GENERIC +Machines with a 32-bit address space, but that do less than 32-bit +addressing, require the following special treatment. If the machine of +interest to you does 32-bit addressing (or doesn't require it; +@pxref{Machine Dependencies}), you can ignore this issue. + +@end ifset +In order to assemble compiler output into something that works, +@code{@value{AS}} occasionlly does strange things to @samp{.word} directives. +Directives of the form @samp{.word sym1-sym2} are often emitted by +compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a +directive of the form @samp{.word sym1-sym2}, and the difference between +@code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}} +creates a @dfn{secondary jump table}, immediately before the next label. +This secondary jump table is preceded by a short-jump to the +first byte after the secondary table. This short-jump prevents the flow +of control from accidentally falling into the new table. Inside the +table is a long-jump to @code{sym2}. The original @samp{.word} +contains @code{sym1} minus the address of the long-jump to +@code{sym2}. + +If there were several occurrences of @samp{.word sym1-sym2} before the +secondary jump table, all of them are adjusted. If there was a +@samp{.word sym3-sym4}, that also did not fit in sixteen bits, a +long-jump to @code{sym4} is included in the secondary jump table, +and the @code{.word} directives are adjusted to contain @code{sym3} +minus the address of the long-jump to @code{sym4}; and so on, for as many +entries in the original jump table as necessary. + +@ifset INTERNALS +@emph{This feature may be disabled by compiling @code{@value{AS}} with the +@samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse +assembly language programmers. +@end ifset +@end ifset +@c end DIFF-TBL-KLUGE + +@node Deprecated +@section Deprecated Directives + +@cindex deprecated directives +@cindex obsolescent directives +One day these directives won't work. +They are included for compatibility with older assemblers. +@table @t +@item .abort +@item .line +@end table + +@ifset GENERIC +@node Machine Dependencies +@chapter Machine Dependent Features + +@cindex machine dependencies +The machine instruction sets are (almost by definition) different on +each machine where @code{@value{AS}} runs. Floating point representations +vary as well, and @code{@value{AS}} often supports a few additional +directives or command-line options for compatibility with other +assemblers on a particular platform. Finally, some versions of +@code{@value{AS}} support special pseudo-instructions for branch +optimization. + +This chapter discusses most of these differences, though it does not +include details on any machine's instruction set. For details on that +subject, see the hardware manufacturer's manual. + +@menu +@ifset A29K +* AMD29K-Dependent:: AMD 29K Dependent Features +@end ifset +@ifset ARC +* ARC-Dependent:: ARC Dependent Features +@end ifset +@ifset ARM +* ARM-Dependent:: ARM Dependent Features +@end ifset +@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 +@end ifset +@ifset H8/500 +* H8/500-Dependent:: Hitachi H8/500 Dependent Features +@end ifset +@ifset HPPA +* HPPA-Dependent:: HPPA Dependent Features +@end ifset +@ifset I80386 +* i386-Dependent:: Intel 80386 Dependent Features +@end ifset +@ifset I960 +* i960-Dependent:: Intel 80960 Dependent Features +@end ifset +@ifset M680X0 +* M68K-Dependent:: M680x0 Dependent Features +@end ifset +@ifset MIPS +* MIPS-Dependent:: MIPS Dependent Features +@end ifset +@ifset SH +* SH-Dependent:: Hitachi SH Dependent Features +@end ifset +@ifset SPARC +* Sparc-Dependent:: SPARC Dependent Features +@end ifset +@ifset V850 +* V850-Dependent:: V850 Dependent Features +@end ifset +@ifset Z8000 +* Z8000-Dependent:: Z8000 Dependent Features +@end ifset +@ifset VAX +* Vax-Dependent:: VAX Dependent Features +@end ifset +@end menu + +@lowersections +@end ifset + +@c The following major nodes are *sections* in the GENERIC version, *chapters* +@c in single-cpu versions. This is mainly achieved by @lowersections. There is a +@c peculiarity: to preserve cross-references, there must be a node called +@c "Machine Dependencies". Hence the conditional nodenames in each +@c major node below. Node defaulting in makeinfo requires adjacency of +@c node and sectioning commands; hence the repetition of @chapter BLAH +@c in both conditional blocks. + +@ifset ARC +@ifset GENERIC +@page +@node ARC-Dependent +@chapter ARC Dependent Features +@end ifset +@ifclear GENERIC +@node Machine Dependencies +@chapter ARC Dependent Features +@end ifclear + +@cindex ARC support +@menu +* ARC-Opts:: Options +* ARC-Float:: Floating Point +* ARC-Directives:: Sparc Machine Directives +@end menu + +@node ARC-Opts +@section Options + +@cindex options for ARC +@cindex ARC options +@cindex architectures, ARC +@cindex ARC architectures +The ARC 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 (ARC +base). The @code{.cpu} pseudo-op is intended to be used to select +the variant. + +@table @code +@cindex @code{-mbig-endian} option (ARC) +@cindex @code{-mlittle-endian} option (ARC) +@cindex ARC big-endian output +@cindex ARC little-endian output +@cindex big-endian output, ARC +@cindex little-endian output, ARC +@item -mbig-endian +@itemx -mlittle-endian +Any @sc{arc} configuration of @code{@value{AS}} can select big-endian or +little-endian output at run time (unlike most other @sc{gnu} development +tools, which must be configured for one or the other). Use +@samp{-mbig-endian} to select big-endian output, and @samp{-mlittle-endian} +for little-endian. +@end table + +@node ARC-Float +@section Floating Point + +@cindex floating point, ARC (@sc{ieee}) +@cindex ARC floating point (@sc{ieee}) +The ARC cpu family currently does not have hardware floating point +support. Software floating point support is provided by @code{GCC} +and uses @sc{ieee} floating-point numbers. + +@node ARC-Directives +@section ARC Machine Directives + +@cindex ARC machine directives +@cindex machine directives, ARC +The ARC version of @code{@value{AS}} supports the following additional +machine directives: + +@table @code +@item .cpu +@cindex @code{cpu} directive, SPARC +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 table + +@end ifset + +@ifset A29K +@include c-a29k.texi +@end ifset + +@ifset ARM +@include c-arm.texi +@end ifset + +@ifset Hitachi-all +@ifclear GENERIC +@node Machine Dependencies +@chapter Machine Dependent Features + +The machine instruction sets are different on each Hitachi chip family, +and there are also some syntax differences among the families. This +chapter describes the specific @code{@value{AS}} features for each +family. + +@menu +* H8/300-Dependent:: Hitachi H8/300 Dependent Features +* H8/500-Dependent:: Hitachi H8/500 Dependent Features +* SH-Dependent:: Hitachi SH Dependent Features +@end menu +@lowersections +@end ifclear +@end ifset + +@ifset D10V +@include c-d10v.texi +@end ifset + +@ifset D30V +@include c-d30v.texi +@end ifset + +@ifset H8/300 +@include c-h8300.texi +@end ifset + +@ifset H8/500 +@include c-h8500.texi +@end ifset + +@ifset HPPA +@include c-hppa.texi +@end ifset + +@ifset I80386 +@include c-i386.texi +@end ifset + +@ifset I960 +@include c-i960.texi +@end ifset + + +@ifset M680X0 +@include c-m68k.texi +@end ifset + +@ifset MIPS +@include c-mips.texi +@end ifset + +@ifset NS32K +@include c-ns32k.texi +@end ifset + +@ifset SH +@include c-sh.texi +@end ifset + +@ifset SPARC +@include c-sparc.texi +@end ifset + +@ifset Z8000 +@include c-z8k.texi +@end ifset + +@ifset VAX +@include c-vax.texi +@end ifset + +@ifset V850 +@include c-v850.texi +@end ifset + +@ifset GENERIC +@c reverse effect of @down at top of generic Machine-Dep chapter +@raisesections +@end ifset + +@node Reporting Bugs +@chapter Reporting Bugs +@cindex bugs in assembler +@cindex reporting bugs in assembler + +Your bug reports play an essential role in making @code{@value{AS}} reliable. + +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}}. + +In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +@menu +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs +@end menu + +@node Bug Criteria +@section Have you found a bug? +@cindex bug criteria + +If you are not sure whether you have found a bug, here are some guidelines: + +@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. + +@cindex error on valid input +@item +If @code{@value{AS}} produces an error message for valid input, that is a bug. + +@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''. + +@item +If you are an experienced user of assemblers, your suggestions for improvement +of @code{@value{AS}} are welcome in any case. +@end itemize + +@node Bug Reporting +@section How to report bugs +@cindex bug reports +@cindex assembler bugs, reporting + +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. + +You can find contact information for many support companies and +individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs +distribution. + +In any event, we also recommend that you send bug reports for @code{@value{AS}} +to @samp{bug-gnu-utils@@gnu.org}. + +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! + +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. + +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. + +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. + +To enable us to fix the bug, you should include all these things: + +@itemize @bullet +@item +The version of @code{@value{AS}}. @code{@value{AS}} announces it if you start +it with the @samp{--version} argument. + +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 +Any patches you may have applied to the @code{@value{AS}} source. + +@item +The type of machine you are using, and the operating system name and +version number. + +@item +What compiler (and its version) was used to compile @code{@value{AS}}---e.g. +``@code{gcc-2.7}''. + +@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. + +If we were to try to guess the arguments, we would probably guess wrong +and then we might not encounter the bug. + +@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 +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 +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 + +Here are some things that are not necessary: + +@itemize @bullet +@item +A description of the envelope of the bug. + +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. + +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. + +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. + +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. + +@item +A patch for the bug. + +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. + +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. + +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. + +@item +A guess about what the bug is or what it depends on. + +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 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 +@c (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. + +John Gilmore built the AMD 29000 support, added @code{.include} support, and +simplified the configuration of which versions accept which directives. He +updated the 68k machine description so that Motorola's opcodes always produced +fixed-size instructions (e.g. @code{jsr}), while synthetic instructions +remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested +cross-compilation support, and one bug in relaxation that took a week and +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, 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. + +Hewlett-Packard contributed support for the HP9000/300. + +Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) +along with a fairly extensive HPPA testsuite (for both SOM and ELF object +formats). This work was supported by both the Center for Software Science at +the University of Utah and Cygnus Support. + +Support for ELF format files has been worked on by Mark Eichin of Cygnus +Support (original, incomplete implementation for SPARC), Pete Hoogenboom and +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). + +Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD +support for openVMS/Alpha. + +Several engineers at Cygnus Support have also provided many small bug fixes and +configuration enhancements. + +Many others have contributed large or small bugfixes and enhancements. If +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 Index +@unnumbered Index + +@printindex cp + +@contents +@bye +@c Local Variables: +@c fill-column: 79 +@c End: |