1 \input texinfo @c -*-Texinfo-*-
2 @c Copyright (c) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
3 @c UPDATE!! On future updates--
4 @c (1) check for new machine-dep cmdline options in
5 @c md_parse_option definitions in config/tc-*.c
6 @c (2) for platform-specific directives, examine md_pseudo_op
8 @c (3) for object-format specific directives, examine obj_pseudo_op
10 @c (4) portable directives in potable[] in read.c
14 @c defaults, config file may override:
17 @include asconfig.texi
19 @c common OR combinations of conditions
39 @set abnormal-separator
43 @settitle Using @value{AS}
46 @settitle Using @value{AS} (@value{TARGET})
48 @setchapternewpage odd
53 @c WARE! Some of the machine-dependent sections contain tables of machine
54 @c instructions. Except in multi-column format, these tables look silly.
55 @c Unfortunately, Texinfo doesn't have a general-purpose multi-col format, so
56 @c the multi-col format is faked within @example sections.
58 @c Again unfortunately, the natural size that fits on a page, for these tables,
59 @c is different depending on whether or not smallbook is turned on.
60 @c This matters, because of order: text flow switches columns at each page
63 @c The format faked in this source works reasonably well for smallbook,
64 @c not well for the default large-page format. This manual expects that if you
65 @c turn on @smallbook, you will also uncomment the "@set SMALL" to enable the
66 @c tables in question. You can turn on one without the other at your
67 @c discretion, of course.
70 @c the insn tables look just as silly in info files regardless of smallbook,
71 @c might as well show 'em anyways.
77 * As: (as). The GNU assembler.
86 This file documents the GNU Assembler "@value{AS}".
88 Copyright (C) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
90 Permission is granted to make and distribute verbatim copies of
91 this manual provided the copyright notice and this permission notice
92 are preserved on all copies.
95 Permission is granted to process this file through Tex and print the
96 results, provided the printed document carries copying permission
97 notice identical to this one except for the removal of this paragraph
98 (this paragraph not being relevant to the printed manual).
101 Permission is granted to copy and distribute modified versions of this manual
102 under the conditions for verbatim copying, provided that the entire resulting
103 derived work is distributed under the terms of a permission notice identical to
106 Permission is granted to copy and distribute translations of this manual
107 into another language, under the above conditions for modified versions.
111 @title Using @value{AS}
112 @subtitle The @sc{gnu} Assembler
114 @subtitle for the @value{TARGET} family
117 @subtitle January 1994
120 The Free Software Foundation Inc. thanks The Nice Computer
121 Company of Australia for loaning Dean Elsner to write the
122 first (Vax) version of @code{as} for Project @sc{gnu}.
123 The proprietors, management and staff of TNCCA thank FSF for
124 distracting the boss while they got some work
127 @author Dean Elsner, Jay Fenlason & friends
131 \hfill {\it Using {\tt @value{AS}}}\par
132 \hfill Edited by Cygnus Support\par
134 %"boxit" macro for figures:
135 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
136 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
137 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
138 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
139 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
142 @vskip 0pt plus 1filll
143 Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
145 Permission is granted to make and distribute verbatim copies of
146 this manual provided the copyright notice and this permission notice
147 are preserved on all copies.
149 Permission is granted to copy and distribute modified versions of this manual
150 under the conditions for verbatim copying, provided that the entire resulting
151 derived work is distributed under the terms of a permission notice identical to
154 Permission is granted to copy and distribute translations of this manual
155 into another language, under the above conditions for modified versions.
160 @top Using @value{AS}
162 This file is a user guide to the @sc{gnu} assembler @code{@value{AS}}.
164 This version of the file describes @code{@value{AS}} configured to generate
165 code for @value{TARGET} architectures.
168 * Overview:: Overview
169 * Invoking:: Command-Line Options
171 * Sections:: Sections and Relocation
173 * Expressions:: Expressions
174 * Pseudo Ops:: Assembler Directives
175 * Machine Dependencies:: Machine Dependent Features
176 * Reporting Bugs:: Reporting Bugs
177 * Acknowledgements:: Who Did What
185 This manual is a user guide to the @sc{gnu} assembler @code{@value{AS}}.
187 This version of the manual describes @code{@value{AS}} configured to generate
188 code for @value{TARGET} architectures.
192 @cindex invocation summary
193 @cindex option summary
194 @cindex summary of options
195 Here is a brief summary of how to invoke @code{@value{AS}}. For details,
196 @pxref{Invoking,,Comand-Line Options}.
198 @c We don't use deffn and friends for the following because they seem
199 @c to be limited to one line for the header.
201 @value{AS} [ -a[cdhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ]
202 [ -f ] [ --gstabs ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ]
203 [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ] [ -version ]
204 [ --version ] [ -W ] [ -w ] [ -x ] [ -Z ]
206 @c am29k has no machine-dependent assembler options
209 [ -mbig-endian | -mlittle-endian ]
212 [ -m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 | -m[arm]6 | -m[arm]7[t][[d]m[i]] ]
213 [ -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m | -m[arm]v4 | -m[arm]v4t ]
215 [ -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu ]
217 [ -mapcs-32 | -mapcs-26 ]
224 @c Hitachi family chips have no machine-dependent assembler options
227 @c HPPA has no machine-dependent assembler options (yet).
230 @c The order here is important. See c-sparc.texi.
231 [ -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
232 -Av8plus | -Av8plusa | -Av9 | -Av9a ]
233 [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ]
236 @c Z8000 has no machine-dependent assembler options
239 @c see md_parse_option in tc-i960.c
240 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
244 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
247 [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ]
248 [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ]
249 [ --trap ] [ --break ]
250 [ --emulation=@var{name} ]
252 [ -- | @var{files} @dots{} ]
257 Turn on listings, in any of a variety of ways:
261 omit false conditionals
264 omit debugging directives
267 include high-level source
273 include macro expansions
276 omit forms processing
282 set the name of the listing file
285 You may combine these options; for example, use @samp{-aln} for assembly
286 listing without forms processing. The @samp{=file} option, if used, must be
287 the last one. By itself, @samp{-a} defaults to @samp{-ahls}.
290 Ignored. This option is accepted for script compatibility with calls to
293 @item --defsym @var{sym}=@var{value}
294 Define the symbol @var{sym} to be @var{value} before assembling the input file.
295 @var{value} must be an integer constant. As in C, a leading @samp{0x}
296 indicates a hexadecimal value, and a leading @samp{0} indicates an octal value.
299 ``fast''---skip whitespace and comment preprocessing (assume source is
303 Generate stabs debugging information for each assembler line. This
304 may help debugging assembler code, if the debugger can handle it.
307 Print a summary of the command line options and exit.
310 Add directory @var{dir} to the search list for @code{.include} directives.
313 Don't warn about signed overflow.
316 @ifclear DIFF-TBL-KLUGE
317 This option is accepted but has no effect on the @value{TARGET} family.
319 @ifset DIFF-TBL-KLUGE
320 Issue warnings when difference tables altered for long displacements.
324 Keep (in the symbol table) local symbols, starting with @samp{L}.
326 @item -o @var{objfile}
327 Name the object-file output from @code{@value{AS}} @var{objfile}.
330 Fold the data section into the text section.
333 Print the maximum space (in bytes) and total time (in seconds) used by
338 Print the @code{as} version.
341 Print the @code{as} version and exit.
344 Suppress warning messages.
353 Generate an object file even after errors.
355 @item -- | @var{files} @dots{}
356 Standard input, or source files to assemble.
361 The following options are available when @value{AS} is configured for
366 @cindex ARC endianness
367 @cindex endianness, ARC
368 @cindex big endian output, ARC
370 Generate ``big endian'' format output.
372 @cindex little endian output, ARC
373 @item -mlittle-endian
374 Generate ``little endian'' format output.
380 The following options are available when @value{AS} is configured for the ARM
384 @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
385 Specify which variant of the ARM architecture is the target.
386 @item -mthumb | -mall
387 Enable or disable Thumb only instruction decoding.
388 @item -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu
389 Select which Floating Point architcture is the target.
390 @item -mapcs-32 | -mapcs-26
391 Select which procedure calling convention is in use.
393 Select either big-endian (-EB) or little-endian (-EL) output.
398 The following options are available when @value{AS} is configured for
401 @cindex D10V optimization
402 @cindex optimization, D10V
404 Optimize output by parallelizing instructions.
409 The following options are available when @value{AS} is configured for the
410 Intel 80960 processor.
413 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
414 Specify which variant of the 960 architecture is the target.
417 Add code to collect statistics about branches taken.
420 Do not alter compare-and-branch instructions for long displacements;
427 The following options are available when @value{AS} is configured for the
428 Motorola 68000 series.
433 Shorten references to undefined symbols, to one word instead of two.
435 @item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060
436 @itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200
437 Specify what processor in the 68000 family is the target. The default
438 is normally the 68020, but this can be changed at configuration time.
440 @item -m68881 | -m68882 | -mno-68881 | -mno-68882
441 The target machine does (or does not) have a floating-point coprocessor.
442 The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
443 the basic 68000 is not compatible with the 68881, a combination of the
444 two can be specified, since it's possible to do emulation of the
445 coprocessor instructions with the main processor.
447 @item -m68851 | -mno-68851
448 The target machine does (or does not) have a memory-management
449 unit coprocessor. The default is to assume an MMU for 68020 and up.
455 The following options are available when @code{@value{AS}} is configured
456 for the SPARC architecture:
459 @item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
460 @itemx -Av8plus | -Av8plusa | -Av9 | -Av9a
461 Explicitly select a variant of the SPARC architecture.
463 @samp{-Av8plus} and @samp{-Av8plusa} select a 32 bit environment.
464 @samp{-Av9} and @samp{-Av9a} select a 64 bit environment.
466 @samp{-Av8plusa} and @samp{-Av9a} enable the SPARC V9 instruction set with
467 UltraSPARC extensions.
469 @item -xarch=v8plus | -xarch=v8plusa
470 For compatibility with the Solaris v9 assembler. These options are
471 equivalent to -Av8plus and -Av8plusa, respectively.
474 Warn when the assembler switches to another architecture.
479 The following options are available when @value{AS} is configured for
484 This option sets the largest size of an object that can be referenced
485 implicitly with the @code{gp} register. It is only accepted for targets that
486 use ECOFF format, such as a DECstation running Ultrix. The default value is 8.
488 @cindex MIPS endianness
489 @cindex endianness, MIPS
490 @cindex big endian output, MIPS
492 Generate ``big endian'' format output.
494 @cindex little endian output, MIPS
496 Generate ``little endian'' format output.
502 Generate code for a particular MIPS Instruction Set Architecture level.
503 @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
504 @samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000}
509 Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept
510 the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
511 instructions around accesses to the @samp{HI} and @samp{LO} registers.
512 @samp{-no-m4650} turns off this option.
514 @item -mcpu=@var{CPU}
515 Generate code for a particular MIPS cpu. This has little effect on the
516 assembler, but it is passed by @code{@value{GCC}}.
519 @item --emulation=@var{name}
520 This option causes @code{@value{AS}} to emulate @code{@value{AS}} configured
521 for some other target, in all respects, including output format (choosing
522 between ELF and ECOFF only), handling of pseudo-opcodes which may generate
523 debugging information or store symbol table information, and default
524 endianness. The available configuration names are: @samp{mipsecoff},
525 @samp{mipself}, @samp{mipslecoff}, @samp{mipsbecoff}, @samp{mipslelf},
526 @samp{mipsbelf}. The first two do not alter the default endianness from that
527 of the primary target for which the assembler was configured; the others change
528 the default to little- or big-endian as indicated by the @samp{b} or @samp{l}
529 in the name. Using @samp{-EB} or @samp{-EL} will override the endianness
530 selection in any case.
532 This option is currently supported only when the primary target
533 @code{@value{AS}} is configured for is a MIPS ELF or ECOFF target.
534 Furthermore, the primary target or others specified with
535 @samp{--enable-targets=@dots{}} at configuration time must include support for
536 the other format, if both are to be available. For example, the Irix 5
537 configuration includes support for both.
539 Eventually, this option will support more configurations, with more
540 fine-grained control over the assembler's behavior, and will be supported for
544 @code{@value{AS}} ignores this option. It is accepted for compatibility with
552 Control how to deal with multiplication overflow and division by zero.
553 @samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception
554 (and only work for Instruction Set Architecture level 2 and higher);
555 @samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a
561 * Manual:: Structure of this Manual
562 * GNU Assembler:: The GNU Assembler
563 * Object Formats:: Object File Formats
564 * Command Line:: Command Line
565 * Input Files:: Input Files
566 * Object:: Output (Object) File
567 * Errors:: Error and Warning Messages
571 @section Structure of this Manual
573 @cindex manual, structure and purpose
574 This manual is intended to describe what you need to know to use
575 @sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including
576 notation for symbols, constants, and expressions; the directives that
577 @code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}.
580 We also cover special features in the @value{TARGET}
581 configuration of @code{@value{AS}}, including assembler directives.
584 This manual also describes some of the machine-dependent features of
585 various flavors of the assembler.
588 @cindex machine instructions (not covered)
589 On the other hand, this manual is @emph{not} intended as an introduction
590 to programming in assembly language---let alone programming in general!
591 In a similar vein, we make no attempt to introduce the machine
592 architecture; we do @emph{not} describe the instruction set, standard
593 mnemonics, registers or addressing modes that are standard to a
594 particular architecture.
596 You may want to consult the manufacturer's
597 machine architecture manual for this information.
601 For information on the H8/300 machine instruction set, see @cite{H8/300
602 Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H,
603 see @cite{H8/300H Series Programming Manual} (Hitachi).
606 For information on the H8/500 machine instruction set, see @cite{H8/500
607 Series Programming Manual} (Hitachi M21T001).
610 For information on the Hitachi SH machine instruction set, see
611 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
614 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
618 @c I think this is premature---doc@cygnus.com, 17jan1991
620 Throughout this manual, we assume that you are running @dfn{GNU},
621 the portable operating system from the @dfn{Free Software
622 Foundation, Inc.}. This restricts our attention to certain kinds of
623 computer (in particular, the kinds of computers that @sc{gnu} can run on);
624 once this assumption is granted examples and definitions need less
627 @code{@value{AS}} is part of a team of programs that turn a high-level
628 human-readable series of instructions into a low-level
629 computer-readable series of instructions. Different versions of
630 @code{@value{AS}} are used for different kinds of computer.
633 @c There used to be a section "Terminology" here, which defined
634 @c "contents", "byte", "word", and "long". Defining "word" to any
635 @c particular size is confusing when the .word directive may generate 16
636 @c bits on one machine and 32 bits on another; in general, for the user
637 @c version of this manual, none of these terms seem essential to define.
638 @c They were used very little even in the former draft of the manual;
639 @c this draft makes an effort to avoid them (except in names of
643 @section The GNU Assembler
645 @sc{gnu} @code{as} is really a family of assemblers.
647 This manual describes @code{@value{AS}}, a member of that family which is
648 configured for the @value{TARGET} architectures.
650 If you use (or have used) the @sc{gnu} assembler on one architecture, you
651 should find a fairly similar environment when you use it on another
652 architecture. Each version has much in common with the others,
653 including object file formats, most assembler directives (often called
654 @dfn{pseudo-ops}) and assembler syntax.@refill
656 @cindex purpose of @sc{gnu} assembler
657 @code{@value{AS}} is primarily intended to assemble the output of the
658 @sc{gnu} C compiler @code{@value{GCC}} for use by the linker
659 @code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}}
660 assemble correctly everything that other assemblers for the same
661 machine would assemble.
663 Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
666 @c This remark should appear in generic version of manual; assumption
667 @c here is that generic version sets M680x0.
668 This doesn't mean @code{@value{AS}} always uses the same syntax as another
669 assembler for the same architecture; for example, we know of several
670 incompatible versions of 680x0 assembly language syntax.
673 Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
674 program in one pass of the source file. This has a subtle impact on the
675 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
678 @section Object File Formats
680 @cindex object file format
681 The @sc{gnu} assembler can be configured to produce several alternative
682 object file formats. For the most part, this does not affect how you
683 write assembly language programs; but directives for debugging symbols
684 are typically different in different file formats. @xref{Symbol
685 Attributes,,Symbol Attributes}.
688 On the @value{TARGET}, @code{@value{AS}} is configured to produce
689 @value{OBJ-NAME} format object files.
691 @c The following should exhaust all configs that set MULTI-OBJ, ideally
693 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
694 @code{a.out} or COFF format object files.
697 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
698 @code{b.out} or COFF format object files.
701 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
702 SOM or ELF format object files.
707 @section Command Line
709 @cindex command line conventions
710 After the program name @code{@value{AS}}, the command line may contain
711 options and file names. Options may appear in any order, and may be
712 before, after, or between file names. The order of file names is
715 @cindex standard input, as input file
717 @file{--} (two hyphens) by itself names the standard input file
718 explicitly, as one of the files for @code{@value{AS}} to assemble.
720 @cindex options, command line
721 Except for @samp{--} any command line argument that begins with a
722 hyphen (@samp{-}) is an option. Each option changes the behavior of
723 @code{@value{AS}}. No option changes the way another option works. An
724 option is a @samp{-} followed by one or more letters; the case of
725 the letter is important. All options are optional.
727 Some options expect exactly one file name to follow them. The file
728 name may either immediately follow the option's letter (compatible
729 with older assemblers) or it may be the next command argument (@sc{gnu}
730 standard). These two command lines are equivalent:
733 @value{AS} -o my-object-file.o mumble.s
734 @value{AS} -omy-object-file.o mumble.s
741 @cindex source program
743 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
744 describe the program input to one run of @code{@value{AS}}. The program may
745 be in one or more files; how the source is partitioned into files
746 doesn't change the meaning of the source.
748 @c I added "con" prefix to "catenation" just to prove I can overcome my
749 @c APL training... doc@cygnus.com
750 The source program is a concatenation of the text in all the files, in the
753 Each time you run @code{@value{AS}} it assembles exactly one source
754 program. The source program is made up of one or more files.
755 (The standard input is also a file.)
757 You give @code{@value{AS}} a command line that has zero or more input file
758 names. The input files are read (from left file name to right). A
759 command line argument (in any position) that has no special meaning
760 is taken to be an input file name.
762 If you give @code{@value{AS}} no file names it attempts to read one input file
763 from the @code{@value{AS}} standard input, which is normally your terminal. You
764 may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program
767 Use @samp{--} if you need to explicitly name the standard input file
768 in your command line.
770 If the source is empty, @code{@value{AS}} produces a small, empty object
773 @subheading Filenames and Line-numbers
775 @cindex input file linenumbers
776 @cindex line numbers, in input files
777 There are two ways of locating a line in the input file (or files) and
778 either may be used in reporting error messages. One way refers to a line
779 number in a physical file; the other refers to a line number in a
780 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
782 @dfn{Physical files} are those files named in the command line given
783 to @code{@value{AS}}.
785 @dfn{Logical files} are simply names declared explicitly by assembler
786 directives; they bear no relation to physical files. Logical file names
787 help error messages reflect the original source file, when @code{@value{AS}}
788 source is itself synthesized from other files.
789 @xref{App-File,,@code{.app-file}}.
792 @section Output (Object) File
798 Every time you run @code{@value{AS}} it produces an output file, which is
799 your assembly language program translated into numbers. This file
800 is the object file. Its default name is
808 @code{b.out} when @code{@value{AS}} is configured for the Intel 80960.
810 You can give it another name by using the @code{-o} option. Conventionally,
811 object file names end with @file{.o}. The default name is used for historical
812 reasons: older assemblers were capable of assembling self-contained programs
813 directly into a runnable program. (For some formats, this isn't currently
814 possible, but it can be done for the @code{a.out} format.)
818 The object file is meant for input to the linker @code{@value{LD}}. It contains
819 assembled program code, information to help @code{@value{LD}} integrate
820 the assembled program into a runnable file, and (optionally) symbolic
821 information for the debugger.
823 @c link above to some info file(s) like the description of a.out.
824 @c don't forget to describe @sc{gnu} info as well as Unix lossage.
827 @section Error and Warning Messages
829 @cindex error messsages
830 @cindex warning messages
831 @cindex messages from assembler
832 @code{@value{AS}} may write warnings and error messages to the standard error
833 file (usually your terminal). This should not happen when a compiler
834 runs @code{@value{AS}} automatically. Warnings report an assumption made so
835 that @code{@value{AS}} could keep assembling a flawed program; errors report a
836 grave problem that stops the assembly.
838 @cindex format of warning messages
839 Warning messages have the format
842 file_name:@b{NNN}:Warning Message Text
846 @cindex line numbers, in warnings/errors
847 (where @b{NNN} is a line number). If a logical file name has been given
848 (@pxref{App-File,,@code{.app-file}}) it is used for the filename,
849 otherwise the name of the current input file is used. If a logical line
852 (@pxref{Line,,@code{.line}})
856 (@pxref{Line,,@code{.line}})
859 (@pxref{Ln,,@code{.ln}})
862 then it is used to calculate the number printed,
863 otherwise the actual line in the current source file is printed. The
864 message text is intended to be self explanatory (in the grand Unix
867 @cindex format of error messages
868 Error messages have the format
870 file_name:@b{NNN}:FATAL:Error Message Text
872 The file name and line number are derived as for warning
873 messages. The actual message text may be rather less explanatory
874 because many of them aren't supposed to happen.
877 @chapter Command-Line Options
879 @cindex options, all versions of assembler
880 This chapter describes command-line options available in @emph{all}
881 versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific
883 to the @value{TARGET}.
886 to particular machine architectures.
889 If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2), you
890 can use the @samp{-Wa} option to pass arguments through to the
891 assembler. The assembler arguments must be separated from each other
892 (and the @samp{-Wa}) by commas. For example:
895 gcc -c -g -O -Wa,-alh,-L file.c
899 emits a listing to standard output with high-level
902 Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
903 command-line options are automatically passed to the assembler by the compiler.
904 (You can call the @sc{gnu} compiler driver with the @samp{-v} option to see
905 precisely what options it passes to each compilation pass, including the
909 * a:: -a[cdhlns] enable listings
910 * D:: -D for compatibility
911 * f:: -f to work faster
912 * I:: -I for .include search path
913 @ifclear DIFF-TBL-KLUGE
914 * K:: -K for compatibility
916 @ifset DIFF-TBL-KLUGE
917 * K:: -K for difference tables
920 * L:: -L to retain local labels
921 * M:: -M or --mri to assemble in MRI compatibility mode
922 * MD:: --MD for dependency tracking
923 * o:: -o to name the object file
924 * R:: -R to join data and text sections
925 * statistics:: --statistics to see statistics about assembly
926 * v:: -v to announce version
927 * W:: -W to suppress warnings
928 * Z:: -Z to make object file even after errors
932 @section Enable Listings: @code{-a[cdhlns]}
941 @cindex listings, enabling
942 @cindex assembly listings, enabling
944 These options enable listing output from the assembler. By itself,
945 @samp{-a} requests high-level, assembly, and symbols listing.
946 You can use other letters to select specific options for the list:
947 @samp{-ah} requests a high-level language listing,
948 @samp{-al} requests an output-program assembly listing, and
949 @samp{-as} requests a symbol table listing.
950 High-level listings require that a compiler debugging option like
951 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
954 Use the @samp{-ac} option to omit false conditionals from a listing. Any lines
955 which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any
956 other conditional), or a true @code{.if} followed by an @code{.else}, will be
957 omitted from the listing.
959 Use the @samp{-ad} option to omit debugging directives from the
962 Once you have specified one of these options, you can further control
963 listing output and its appearance using the directives @code{.list},
964 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
966 The @samp{-an} option turns off all forms processing.
967 If you do not request listing output with one of the @samp{-a} options, the
968 listing-control directives have no effect.
970 The letters after @samp{-a} may be combined into one option,
971 @emph{e.g.}, @samp{-aln}.
977 This option has no effect whatsoever, but it is accepted to make it more
978 likely that scripts written for other assemblers also work with
982 @section Work Faster: @code{-f}
985 @cindex trusted compiler
986 @cindex faster processing (@code{-f})
987 @samp{-f} should only be used when assembling programs written by a
988 (trusted) compiler. @samp{-f} stops the assembler from doing whitespace
989 and comment preprocessing on
990 the input file(s) before assembling them. @xref{Preprocessing,
994 @emph{Warning:} if you use @samp{-f} when the files actually need to be
995 preprocessed (if they contain comments, for example), @code{@value{AS}} does
1000 @section @code{.include} search path: @code{-I} @var{path}
1002 @kindex -I @var{path}
1003 @cindex paths for @code{.include}
1004 @cindex search path for @code{.include}
1005 @cindex @code{include} directive search path
1006 Use this option to add a @var{path} to the list of directories
1007 @code{@value{AS}} searches for files specified in @code{.include}
1008 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
1009 many times as necessary to include a variety of paths. The current
1010 working directory is always searched first; after that, @code{@value{AS}}
1011 searches any @samp{-I} directories in the same order as they were
1012 specified (left to right) on the command line.
1015 @section Difference Tables: @code{-K}
1018 @ifclear DIFF-TBL-KLUGE
1019 On the @value{TARGET} family, this option is allowed, but has no effect. It is
1020 permitted for compatibility with the @sc{gnu} assembler on other platforms,
1021 where it can be used to warn when the assembler alters the machine code
1022 generated for @samp{.word} directives in difference tables. The @value{TARGET}
1023 family does not have the addressing limitations that sometimes lead to this
1024 alteration on other platforms.
1027 @ifset DIFF-TBL-KLUGE
1028 @cindex difference tables, warning
1029 @cindex warning for altered difference tables
1030 @code{@value{AS}} sometimes alters the code emitted for directives of the form
1031 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
1032 You can use the @samp{-K} option if you want a warning issued when this
1037 @section Include Local Labels: @code{-L}
1040 @cindex local labels, retaining in output
1041 Labels beginning with @samp{L} (upper case only) are called @dfn{local
1042 labels}. @xref{Symbol Names}. Normally you do not see such labels when
1043 debugging, because they are intended for the use of programs (like
1044 compilers) that compose assembler programs, not for your notice.
1045 Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not
1046 normally debug with them.
1048 This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols
1049 in the object file. Usually if you do this you also tell the linker
1050 @code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
1052 By default, a local label is any label beginning with @samp{L}, but each
1053 target is allowed to redefine the local label prefix.
1055 On the HPPA local labels begin with @samp{L$}.
1058 @samp{;} for the ARM family;
1062 @section Assemble in MRI Compatibility Mode: @code{-M}
1065 @cindex MRI compatibility mode
1066 The @code{-M} or @code{--mri} option selects MRI compatibility mode. This
1067 changes the syntax and pseudo-op handling of @code{@value{AS}} to make it
1068 compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the
1069 configured target) assembler from Microtec Research. The exact nature of the
1070 MRI syntax will not be documented here; see the MRI manuals for more
1071 information. Note in particular that the handling of macros and macro
1072 arguments is somewhat different. The purpose of this option is to permit
1073 assembling existing MRI assembler code using @code{@value{AS}}.
1075 The MRI compatibility is not complete. Certain operations of the MRI assembler
1076 depend upon its object file format, and can not be supported using other object
1077 file formats. Supporting these would require enhancing each object file format
1078 individually. These are:
1081 @item global symbols in common section
1083 The m68k MRI assembler supports common sections which are merged by the linker.
1084 Other object file formats do not support this. @code{@value{AS}} handles
1085 common sections by treating them as a single common symbol. It permits local
1086 symbols to be defined within a common section, but it can not support global
1087 symbols, since it has no way to describe them.
1089 @item complex relocations
1091 The MRI assemblers support relocations against a negated section address, and
1092 relocations which combine the start addresses of two or more sections. These
1093 are not support by other object file formats.
1095 @item @code{END} pseudo-op specifying start address
1097 The MRI @code{END} pseudo-op permits the specification of a start address.
1098 This is not supported by other object file formats. The start address may
1099 instead be specified using the @code{-e} option to the linker, or in a linker
1102 @item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops
1104 The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module
1105 name to the output file. This is not supported by other object file formats.
1107 @item @code{ORG} pseudo-op
1109 The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given
1110 address. This differs from the usual @code{@value{AS}} @code{.org} pseudo-op,
1111 which changes the location within the current section. Absolute sections are
1112 not supported by other object file formats. The address of a section may be
1113 assigned within a linker script.
1116 There are some other features of the MRI assembler which are not supported by
1117 @code{@value{AS}}, typically either because they are difficult or because they
1118 seem of little consequence. Some of these may be supported in future releases.
1122 @item EBCDIC strings
1124 EBCDIC strings are not supported.
1126 @item packed binary coded decimal
1128 Packed binary coded decimal is not supported. This means that the @code{DC.P}
1129 and @code{DCB.P} pseudo-ops are not supported.
1131 @item @code{FEQU} pseudo-op
1133 The m68k @code{FEQU} pseudo-op is not supported.
1135 @item @code{NOOBJ} pseudo-op
1137 The m68k @code{NOOBJ} pseudo-op is not supported.
1139 @item @code{OPT} branch control options
1141 The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB},
1142 @code{BRL}, and @code{BRW}---are ignored. @code{@value{AS}} automatically
1143 relaxes all branches, whether forward or backward, to an appropriate size, so
1144 these options serve no purpose.
1146 @item @code{OPT} list control options
1148 The following m68k @code{OPT} list control options are ignored: @code{C},
1149 @code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M},
1150 @code{MEX}, @code{MC}, @code{MD}, @code{X}.
1152 @item other @code{OPT} options
1154 The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O},
1155 @code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}.
1157 @item @code{OPT} @code{D} option is default
1159 The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler.
1160 @code{OPT NOD} may be used to turn it off.
1162 @item @code{XREF} pseudo-op.
1164 The m68k @code{XREF} pseudo-op is ignored.
1166 @item @code{.debug} pseudo-op
1168 The i960 @code{.debug} pseudo-op is not supported.
1170 @item @code{.extended} pseudo-op
1172 The i960 @code{.extended} pseudo-op is not supported.
1174 @item @code{.list} pseudo-op.
1176 The various options of the i960 @code{.list} pseudo-op are not supported.
1178 @item @code{.optimize} pseudo-op
1180 The i960 @code{.optimize} pseudo-op is not supported.
1182 @item @code{.output} pseudo-op
1184 The i960 @code{.output} pseudo-op is not supported.
1186 @item @code{.setreal} pseudo-op
1188 The i960 @code{.setreal} pseudo-op is not supported.
1193 @section Dependency tracking: @code{--MD}
1196 @cindex dependency tracking
1199 @code{@value{AS}} can generate a dependency file for the file it creates. This
1200 file consists of a single rule suitable for @code{make} describing the
1201 dependencies of the main source file.
1203 The rule is written to the file named in its argument.
1205 This feature is used in the automatic updating of makefiles.
1208 @section Name the Object File: @code{-o}
1211 @cindex naming object file
1212 @cindex object file name
1213 There is always one object file output when you run @code{@value{AS}}. By
1214 default it has the name
1217 @file{a.out} (or @file{b.out}, for Intel 960 targets only).
1231 You use this option (which takes exactly one filename) to give the
1232 object file a different name.
1234 Whatever the object file is called, @code{@value{AS}} overwrites any
1235 existing file of the same name.
1238 @section Join Data and Text Sections: @code{-R}
1241 @cindex data and text sections, joining
1242 @cindex text and data sections, joining
1243 @cindex joining text and data sections
1244 @cindex merging text and data sections
1245 @code{-R} tells @code{@value{AS}} to write the object file as if all
1246 data-section data lives in the text section. This is only done at
1247 the very last moment: your binary data are the same, but data
1248 section parts are relocated differently. The data section part of
1249 your object file is zero bytes long because all its bytes are
1250 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
1252 When you specify @code{-R} it would be possible to generate shorter
1253 address displacements (because we do not have to cross between text and
1254 data section). We refrain from doing this simply for compatibility with
1255 older versions of @code{@value{AS}}. In future, @code{-R} may work this way.
1258 When @code{@value{AS}} is configured for COFF output,
1259 this option is only useful if you use sections named @samp{.text} and
1264 @code{-R} is not supported for any of the HPPA targets. Using
1265 @code{-R} generates a warning from @code{@value{AS}}.
1269 @section Display Assembly Statistics: @code{--statistics}
1271 @kindex --statistics
1272 @cindex statistics, about assembly
1273 @cindex time, total for assembly
1274 @cindex space used, maximum for assembly
1275 Use @samp{--statistics} to display two statistics about the resources used by
1276 @code{@value{AS}}: the maximum amount of space allocated during the assembly
1277 (in bytes), and the total execution time taken for the assembly (in @sc{cpu}
1281 @section Announce Version: @code{-v}
1285 @cindex assembler version
1286 @cindex version of assembler
1287 You can find out what version of as is running by including the
1288 option @samp{-v} (which you can also spell as @samp{-version}) on the
1292 @section Suppress Warnings: @code{-W}
1295 @cindex suppressing warnings
1296 @cindex warnings, suppressing
1297 @code{@value{AS}} should never give a warning or error message when
1298 assembling compiler output. But programs written by people often
1299 cause @code{@value{AS}} to give a warning that a particular assumption was
1300 made. All such warnings are directed to the standard error file.
1301 If you use this option, no warnings are issued. This option only
1302 affects the warning messages: it does not change any particular of how
1303 @code{@value{AS}} assembles your file. Errors, which stop the assembly, are
1307 @section Generate Object File in Spite of Errors: @code{-Z}
1308 @cindex object file, after errors
1309 @cindex errors, continuing after
1310 After an error message, @code{@value{AS}} normally produces no output. If for
1311 some reason you are interested in object file output even after
1312 @code{@value{AS}} gives an error message on your program, use the @samp{-Z}
1313 option. If there are any errors, @code{@value{AS}} continues anyways, and
1314 writes an object file after a final warning message of the form @samp{@var{n}
1315 errors, @var{m} warnings, generating bad object file.}
1320 @cindex machine-independent syntax
1321 @cindex syntax, machine-independent
1322 This chapter describes the machine-independent syntax allowed in a
1323 source file. @code{@value{AS}} syntax is similar to what many other
1324 assemblers use; it is inspired by the BSD 4.2
1329 assembler, except that @code{@value{AS}} does not assemble Vax bit-fields.
1333 * Preprocessing:: Preprocessing
1334 * Whitespace:: Whitespace
1335 * Comments:: Comments
1336 * Symbol Intro:: Symbols
1337 * Statements:: Statements
1338 * Constants:: Constants
1342 @section Preprocessing
1344 @cindex preprocessing
1345 The @code{@value{AS}} internal preprocessor:
1347 @cindex whitespace, removed by preprocessor
1349 adjusts and removes extra whitespace. It leaves one space or tab before
1350 the keywords on a line, and turns any other whitespace on the line into
1353 @cindex comments, removed by preprocessor
1355 removes all comments, replacing them with a single space, or an
1356 appropriate number of newlines.
1358 @cindex constants, converted by preprocessor
1360 converts character constants into the appropriate numeric values.
1363 It does not do macro processing, include file handling, or
1364 anything else you may get from your C compiler's preprocessor. You can
1365 do include file processing with the @code{.include} directive
1366 (@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver
1367 to get other ``CPP'' style preprocessing, by giving the input file a
1368 @samp{.S} suffix. @xref{Overall Options,, Options Controlling the Kind of
1369 Output, gcc.info, Using GNU CC}.
1371 Excess whitespace, comments, and character constants
1372 cannot be used in the portions of the input text that are not
1375 @cindex turning preprocessing on and off
1376 @cindex preprocessing, turning on and off
1379 If the first line of an input file is @code{#NO_APP} or if you use the
1380 @samp{-f} option, whitespace and comments are not removed from the input file.
1381 Within an input file, you can ask for whitespace and comment removal in
1382 specific portions of the by putting a line that says @code{#APP} before the
1383 text that may contain whitespace or comments, and putting a line that says
1384 @code{#NO_APP} after this text. This feature is mainly intend to support
1385 @code{asm} statements in compilers whose output is otherwise free of comments
1392 @dfn{Whitespace} is one or more blanks or tabs, in any order.
1393 Whitespace is used to separate symbols, and to make programs neater for
1394 people to read. Unless within character constants
1395 (@pxref{Characters,,Character Constants}), any whitespace means the same
1396 as exactly one space.
1402 There are two ways of rendering comments to @code{@value{AS}}. In both
1403 cases the comment is equivalent to one space.
1405 Anything from @samp{/*} through the next @samp{*/} is a comment.
1406 This means you may not nest these comments.
1410 The only way to include a newline ('\n') in a comment
1411 is to use this sort of comment.
1414 /* This sort of comment does not nest. */
1417 @cindex line comment character
1418 Anything from the @dfn{line comment} character to the next newline
1419 is considered a comment and is ignored. The line comment character is
1421 @samp{;} for the AMD 29K family;
1424 @samp{;} on the ARC;
1427 @samp{;} for the H8/300 family;
1430 @samp{!} for the H8/500 family;
1433 @samp{;} for the HPPA;
1436 @samp{#} on the i960;
1439 @samp{!} for the Hitachi SH;
1442 @samp{!} on the SPARC;
1445 @samp{|} on the 680x0;
1448 @samp{#} on the Vax;
1451 @samp{!} for the Z8000;
1453 @c start-sanitize-v850
1455 @samp{#} on the V850;
1457 @c end-sanitize-v850
1458 see @ref{Machine Dependencies}. @refill
1459 @c FIXME What about i386, m88k, i860?
1462 On some machines there are two different line comment characters. One
1463 character only begins a comment if it is the first non-whitespace character on
1464 a line, while the other always begins a comment.
1467 @c start-sanitize-v850
1469 The V850 assembler also supports a double dash as starting a comment that
1470 extends to the end of the line.
1474 @c end-sanitize-v850
1477 @cindex lines starting with @code{#}
1478 @cindex logical line numbers
1479 To be compatible with past assemblers, lines that begin with @samp{#} have a
1480 special interpretation. Following the @samp{#} should be an absolute
1481 expression (@pxref{Expressions}): the logical line number of the @emph{next}
1482 line. Then a string (@pxref{Strings,, Strings}) is allowed: if present it is a
1483 new logical file name. The rest of the line, if any, should be whitespace.
1485 If the first non-whitespace characters on the line are not numeric,
1486 the line is ignored. (Just like a comment.)
1489 # This is an ordinary comment.
1490 # 42-6 "new_file_name" # New logical file name
1491 # This is logical line # 36.
1493 This feature is deprecated, and may disappear from future versions
1494 of @code{@value{AS}}.
1499 @cindex characters used in symbols
1500 @ifclear SPECIAL-SYMS
1501 A @dfn{symbol} is one or more characters chosen from the set of all
1502 letters (both upper and lower case), digits and the three characters
1508 A @dfn{symbol} is one or more characters chosen from the set of all
1509 letters (both upper and lower case), digits and the three characters
1510 @samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in
1516 On most machines, you can also use @code{$} in symbol names; exceptions
1517 are noted in @ref{Machine Dependencies}.
1519 No symbol may begin with a digit. Case is significant.
1520 There is no length limit: all characters are significant. Symbols are
1521 delimited by characters not in that set, or by the beginning of a file
1522 (since the source program must end with a newline, the end of a file is
1523 not a possible symbol delimiter). @xref{Symbols}.
1524 @cindex length of symbols
1529 @cindex statements, structure of
1530 @cindex line separator character
1531 @cindex statement separator character
1533 @ifclear abnormal-separator
1534 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
1535 semicolon (@samp{;}). The newline or semicolon is considered part of
1536 the preceding statement. Newlines and semicolons within character
1537 constants are an exception: they do not end statements.
1539 @ifset abnormal-separator
1541 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
1542 sign (@samp{@@}). The newline or at sign is considered part of the
1543 preceding statement. Newlines and at signs within character constants
1544 are an exception: they do not end statements.
1547 A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation
1548 point (@samp{!}). The newline or exclamation point is considered part of the
1549 preceding statement. Newlines and exclamation points within character
1550 constants are an exception: they do not end statements.
1553 A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
1554 H8/300) a dollar sign (@samp{$}); or (for the
1557 (@samp{;}). The newline or separator character is considered part of
1558 the preceding statement. Newlines and separators within character
1559 constants are an exception: they do not end statements.
1564 A @dfn{statement} ends at a newline character (@samp{\n}) or line
1565 separator character. (The line separator is usually @samp{;}, unless
1566 this conflicts with the comment character; @pxref{Machine Dependencies}.) The
1567 newline or separator character is considered part of the preceding
1568 statement. Newlines and separators within character constants are an
1569 exception: they do not end statements.
1572 @cindex newline, required at file end
1573 @cindex EOF, newline must precede
1574 It is an error to end any statement with end-of-file: the last
1575 character of any input file should be a newline.@refill
1577 @cindex continuing statements
1578 @cindex multi-line statements
1579 @cindex statement on multiple lines
1580 You may write a statement on more than one line if you put a
1581 backslash (@kbd{\}) immediately in front of any newlines within the
1582 statement. When @code{@value{AS}} reads a backslashed newline both
1583 characters are ignored. You can even put backslashed newlines in
1584 the middle of symbol names without changing the meaning of your
1587 An empty statement is allowed, and may include whitespace. It is ignored.
1589 @cindex instructions and directives
1590 @cindex directives and instructions
1591 @c "key symbol" is not used elsewhere in the document; seems pedantic to
1592 @c @defn{} it in that case, as was done previously... doc@cygnus.com,
1594 A statement begins with zero or more labels, optionally followed by a
1595 key symbol which determines what kind of statement it is. The key
1596 symbol determines the syntax of the rest of the statement. If the
1597 symbol begins with a dot @samp{.} then the statement is an assembler
1598 directive: typically valid for any computer. If the symbol begins with
1599 a letter the statement is an assembly language @dfn{instruction}: it
1600 assembles into a machine language instruction.
1602 Different versions of @code{@value{AS}} for different computers
1603 recognize different instructions. In fact, the same symbol may
1604 represent a different instruction in a different computer's assembly
1608 @cindex @code{:} (label)
1609 @cindex label (@code{:})
1610 A label is a symbol immediately followed by a colon (@code{:}).
1611 Whitespace before a label or after a colon is permitted, but you may not
1612 have whitespace between a label's symbol and its colon. @xref{Labels}.
1615 For HPPA targets, labels need not be immediately followed by a colon, but
1616 the definition of a label must begin in column zero. This also implies that
1617 only one label may be defined on each line.
1621 label: .directive followed by something
1622 another_label: # This is an empty statement.
1623 instruction operand_1, operand_2, @dots{}
1630 A constant is a number, written so that its value is known by
1631 inspection, without knowing any context. Like this:
1634 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
1635 .ascii "Ring the bell\7" # A string constant.
1636 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
1637 .float 0f-314159265358979323846264338327\
1638 95028841971.693993751E-40 # - pi, a flonum.
1643 * Characters:: Character Constants
1644 * Numbers:: Number Constants
1648 @subsection Character Constants
1650 @cindex character constants
1651 @cindex constants, character
1652 There are two kinds of character constants. A @dfn{character} stands
1653 for one character in one byte and its value may be used in
1654 numeric expressions. String constants (properly called string
1655 @emph{literals}) are potentially many bytes and their values may not be
1656 used in arithmetic expressions.
1660 * Chars:: Characters
1664 @subsubsection Strings
1666 @cindex string constants
1667 @cindex constants, string
1668 A @dfn{string} is written between double-quotes. It may contain
1669 double-quotes or null characters. The way to get special characters
1670 into a string is to @dfn{escape} these characters: precede them with
1671 a backslash @samp{\} character. For example @samp{\\} represents
1672 one backslash: the first @code{\} is an escape which tells
1673 @code{@value{AS}} to interpret the second character literally as a backslash
1674 (which prevents @code{@value{AS}} from recognizing the second @code{\} as an
1675 escape character). The complete list of escapes follows.
1677 @cindex escape codes, character
1678 @cindex character escape codes
1681 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1683 @cindex @code{\b} (backspace character)
1684 @cindex backspace (@code{\b})
1686 Mnemonic for backspace; for ASCII this is octal code 010.
1689 @c Mnemonic for EOText; for ASCII this is octal code 004.
1691 @cindex @code{\f} (formfeed character)
1692 @cindex formfeed (@code{\f})
1694 Mnemonic for FormFeed; for ASCII this is octal code 014.
1696 @cindex @code{\n} (newline character)
1697 @cindex newline (@code{\n})
1699 Mnemonic for newline; for ASCII this is octal code 012.
1702 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1704 @cindex @code{\r} (carriage return character)
1705 @cindex carriage return (@code{\r})
1707 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1710 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1711 @c other assemblers.
1713 @cindex @code{\t} (tab)
1714 @cindex tab (@code{\t})
1716 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1719 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1720 @c @item \x @var{digit} @var{digit} @var{digit}
1721 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1723 @cindex @code{\@var{ddd}} (octal character code)
1724 @cindex octal character code (@code{\@var{ddd}})
1725 @item \ @var{digit} @var{digit} @var{digit}
1726 An octal character code. The numeric code is 3 octal digits.
1727 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1728 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1730 @cindex @code{\@var{xd...}} (hex character code)
1731 @cindex hex character code (@code{\@var{xd...}})
1732 @item \@code{x} @var{hex-digits...}
1733 A hex character code. All trailing hex digits are combined. Either upper or
1734 lower case @code{x} works.
1736 @cindex @code{\\} (@samp{\} character)
1737 @cindex backslash (@code{\\})
1739 Represents one @samp{\} character.
1742 @c Represents one @samp{'} (accent acute) character.
1743 @c This is needed in single character literals
1744 @c (@xref{Characters,,Character Constants}.) to represent
1747 @cindex @code{\"} (doublequote character)
1748 @cindex doublequote (@code{\"})
1750 Represents one @samp{"} character. Needed in strings to represent
1751 this character, because an unescaped @samp{"} would end the string.
1753 @item \ @var{anything-else}
1754 Any other character when escaped by @kbd{\} gives a warning, but
1755 assembles as if the @samp{\} was not present. The idea is that if
1756 you used an escape sequence you clearly didn't want the literal
1757 interpretation of the following character. However @code{@value{AS}} has no
1758 other interpretation, so @code{@value{AS}} knows it is giving you the wrong
1759 code and warns you of the fact.
1762 Which characters are escapable, and what those escapes represent,
1763 varies widely among assemblers. The current set is what we think
1764 the BSD 4.2 assembler recognizes, and is a subset of what most C
1765 compilers recognize. If you are in doubt, do not use an escape
1769 @subsubsection Characters
1771 @cindex single character constant
1772 @cindex character, single
1773 @cindex constant, single character
1774 A single character may be written as a single quote immediately
1775 followed by that character. The same escapes apply to characters as
1776 to strings. So if you want to write the character backslash, you
1777 must write @kbd{'\\} where the first @code{\} escapes the second
1778 @code{\}. As you can see, the quote is an acute accent, not a
1779 grave accent. A newline
1781 @ifclear abnormal-separator
1782 (or semicolon @samp{;})
1784 @ifset abnormal-separator
1786 (or at sign @samp{@@})
1789 (or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
1795 immediately following an acute accent is taken as a literal character
1796 and does not count as the end of a statement. The value of a character
1797 constant in a numeric expression is the machine's byte-wide code for
1798 that character. @code{@value{AS}} assumes your character code is ASCII:
1799 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1802 @subsection Number Constants
1804 @cindex constants, number
1805 @cindex number constants
1806 @code{@value{AS}} distinguishes three kinds of numbers according to how they
1807 are stored in the target machine. @emph{Integers} are numbers that
1808 would fit into an @code{int} in the C language. @emph{Bignums} are
1809 integers, but they are stored in more than 32 bits. @emph{Flonums}
1810 are floating point numbers, described below.
1813 * Integers:: Integers
1818 * Bit Fields:: Bit Fields
1824 @subsubsection Integers
1826 @cindex constants, integer
1828 @cindex binary integers
1829 @cindex integers, binary
1830 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1831 the binary digits @samp{01}.
1833 @cindex octal integers
1834 @cindex integers, octal
1835 An octal integer is @samp{0} followed by zero or more of the octal
1836 digits (@samp{01234567}).
1838 @cindex decimal integers
1839 @cindex integers, decimal
1840 A decimal integer starts with a non-zero digit followed by zero or
1841 more digits (@samp{0123456789}).
1843 @cindex hexadecimal integers
1844 @cindex integers, hexadecimal
1845 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1846 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1848 Integers have the usual values. To denote a negative integer, use
1849 the prefix operator @samp{-} discussed under expressions
1850 (@pxref{Prefix Ops,,Prefix Operators}).
1853 @subsubsection Bignums
1856 @cindex constants, bignum
1857 A @dfn{bignum} has the same syntax and semantics as an integer
1858 except that the number (or its negative) takes more than 32 bits to
1859 represent in binary. The distinction is made because in some places
1860 integers are permitted while bignums are not.
1863 @subsubsection Flonums
1865 @cindex floating point numbers
1866 @cindex constants, floating point
1868 @cindex precision, floating point
1869 A @dfn{flonum} represents a floating point number. The translation is
1870 indirect: a decimal floating point number from the text is converted by
1871 @code{@value{AS}} to a generic binary floating point number of more than
1872 sufficient precision. This generic floating point number is converted
1873 to a particular computer's floating point format (or formats) by a
1874 portion of @code{@value{AS}} specialized to that computer.
1876 A flonum is written by writing (in order)
1881 (@samp{0} is optional on the HPPA.)
1885 A letter, to tell @code{@value{AS}} the rest of the number is a flonum.
1887 @kbd{e} is recommended. Case is not important.
1889 @c FIXME: verify if flonum syntax really this vague for most cases
1890 (Any otherwise illegal letter works here, but that might be changed. Vax BSD
1891 4.2 assembler seems to allow any of @samp{defghDEFGH}.)
1894 On the H8/300, H8/500,
1896 and AMD 29K architectures, the letter must be
1897 one of the letters @samp{DFPRSX} (in upper or lower case).
1899 On the ARC, the letter must be one of the letters @samp{DFRS}
1900 (in upper or lower case).
1902 On the Intel 960 architecture, the letter must be
1903 one of the letters @samp{DFT} (in upper or lower case).
1905 On the HPPA architecture, the letter must be @samp{E} (upper case only).
1909 One of the letters @samp{DFPRSX} (in upper or lower case).
1912 One of the letters @samp{DFRS} (in upper or lower case).
1915 One of the letters @samp{DFPRSX} (in upper or lower case).
1918 The letter @samp{E} (upper case only).
1921 One of the letters @samp{DFT} (in upper or lower case).
1926 An optional sign: either @samp{+} or @samp{-}.
1929 An optional @dfn{integer part}: zero or more decimal digits.
1932 An optional @dfn{fractional part}: @samp{.} followed by zero
1933 or more decimal digits.
1936 An optional exponent, consisting of:
1940 An @samp{E} or @samp{e}.
1941 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1942 @c principle this can perfectly well be different on different targets.
1944 Optional sign: either @samp{+} or @samp{-}.
1946 One or more decimal digits.
1951 At least one of the integer part or the fractional part must be
1952 present. The floating point number has the usual base-10 value.
1954 @code{@value{AS}} does all processing using integers. Flonums are computed
1955 independently of any floating point hardware in the computer running
1960 @c Bit fields are written as a general facility but are also controlled
1961 @c by a conditional-compilation flag---which is as of now (21mar91)
1962 @c turned on only by the i960 config of GAS.
1964 @subsubsection Bit Fields
1967 @cindex constants, bit field
1968 You can also define numeric constants as @dfn{bit fields}.
1969 specify two numbers separated by a colon---
1971 @var{mask}:@var{value}
1974 @code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
1977 The resulting number is then packed
1979 @c this conditional paren in case bit fields turned on elsewhere than 960
1980 (in host-dependent byte order)
1982 into a field whose width depends on which assembler directive has the
1983 bit-field as its argument. Overflow (a result from the bitwise and
1984 requiring more binary digits to represent) is not an error; instead,
1985 more constants are generated, of the specified width, beginning with the
1986 least significant digits.@refill
1988 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1989 @code{.short}, and @code{.word} accept bit-field arguments.
1994 @chapter Sections and Relocation
1999 * Secs Background:: Background
2000 * Ld Sections:: Linker Sections
2001 * As Sections:: Assembler Internal Sections
2002 * Sub-Sections:: Sub-Sections
2006 @node Secs Background
2009 Roughly, a section is a range of addresses, with no gaps; all data
2010 ``in'' those addresses is treated the same for some particular purpose.
2011 For example there may be a ``read only'' section.
2013 @cindex linker, and assembler
2014 @cindex assembler, and linker
2015 The linker @code{@value{LD}} reads many object files (partial programs) and
2016 combines their contents to form a runnable program. When @code{@value{AS}}
2017 emits an object file, the partial program is assumed to start at address 0.
2018 @code{@value{LD}} assigns the final addresses for the partial program, so that
2019 different partial programs do not overlap. This is actually an
2020 oversimplification, but it suffices to explain how @code{@value{AS}} uses
2023 @code{@value{LD}} moves blocks of bytes of your program to their run-time
2024 addresses. These blocks slide to their run-time addresses as rigid
2025 units; their length does not change and neither does the order of bytes
2026 within them. Such a rigid unit is called a @emph{section}. Assigning
2027 run-time addresses to sections is called @dfn{relocation}. It includes
2028 the task of adjusting mentions of object-file addresses so they refer to
2029 the proper run-time addresses.
2031 For the H8/300 and H8/500,
2032 and for the Hitachi SH,
2033 @code{@value{AS}} pads sections if needed to
2034 ensure they end on a word (sixteen bit) boundary.
2037 @cindex standard assembler sections
2038 An object file written by @code{@value{AS}} has at least three sections, any
2039 of which may be empty. These are named @dfn{text}, @dfn{data} and
2044 When it generates COFF output,
2046 @code{@value{AS}} can also generate whatever other named sections you specify
2047 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
2048 If you do not use any directives that place output in the @samp{.text}
2049 or @samp{.data} sections, these sections still exist, but are empty.
2054 When @code{@value{AS}} generates SOM or ELF output for the HPPA,
2056 @code{@value{AS}} can also generate whatever other named sections you
2057 specify using the @samp{.space} and @samp{.subspace} directives. See
2058 @cite{HP9000 Series 800 Assembly Language Reference Manual}
2059 (HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
2060 assembler directives.
2063 Additionally, @code{@value{AS}} uses different names for the standard
2064 text, data, and bss sections when generating SOM output. Program text
2065 is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
2066 BSS into @samp{$BSS$}.
2070 Within the object file, the text section starts at address @code{0}, the
2071 data section follows, and the bss section follows the data section.
2074 When generating either SOM or ELF output files on the HPPA, the text
2075 section starts at address @code{0}, the data section at address
2076 @code{0x4000000}, and the bss section follows the data section.
2079 To let @code{@value{LD}} know which data changes when the sections are
2080 relocated, and how to change that data, @code{@value{AS}} also writes to the
2081 object file details of the relocation needed. To perform relocation
2082 @code{@value{LD}} must know, each time an address in the object
2086 Where in the object file is the beginning of this reference to
2089 How long (in bytes) is this reference?
2091 Which section does the address refer to? What is the numeric value of
2093 (@var{address}) @minus{} (@var{start-address of section})?
2096 Is the reference to an address ``Program-Counter relative''?
2099 @cindex addresses, format of
2100 @cindex section-relative addressing
2101 In fact, every address @code{@value{AS}} ever uses is expressed as
2103 (@var{section}) + (@var{offset into section})
2106 Further, most expressions @code{@value{AS}} computes have this section-relative
2109 (For some object formats, such as SOM for the HPPA, some expressions are
2110 symbol-relative instead.)
2113 In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset
2114 @var{N} into section @var{secname}.''
2116 Apart from text, data and bss sections you need to know about the
2117 @dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
2118 addresses in the absolute section remain unchanged. For example, address
2119 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
2120 @code{@value{LD}}. Although the linker never arranges two partial programs'
2121 data sections with overlapping addresses after linking, @emph{by definition}
2122 their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one
2123 part of a program is always the same address when the program is running as
2124 address @code{@{absolute@ 239@}} in any other part of the program.
2126 The idea of sections is extended to the @dfn{undefined} section. Any
2127 address whose section is unknown at assembly time is by definition
2128 rendered @{undefined @var{U}@}---where @var{U} is filled in later.
2129 Since numbers are always defined, the only way to generate an undefined
2130 address is to mention an undefined symbol. A reference to a named
2131 common block would be such a symbol: its value is unknown at assembly
2132 time so it has section @emph{undefined}.
2134 By analogy the word @emph{section} is used to describe groups of sections in
2135 the linked program. @code{@value{LD}} puts all partial programs' text
2136 sections in contiguous addresses in the linked program. It is
2137 customary to refer to the @emph{text section} of a program, meaning all
2138 the addresses of all partial programs' text sections. Likewise for
2139 data and bss sections.
2141 Some sections are manipulated by @code{@value{LD}}; others are invented for
2142 use of @code{@value{AS}} and have no meaning except during assembly.
2145 @section Linker Sections
2146 @code{@value{LD}} deals with just four kinds of sections, summarized below.
2151 @cindex named sections
2152 @cindex sections, named
2153 @item named sections
2156 @cindex text section
2157 @cindex data section
2161 These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as
2162 separate but equal sections. Anything you can say of one section is
2165 When the program is running, however, it is
2166 customary for the text section to be unalterable. The
2167 text section is often shared among processes: it contains
2168 instructions, constants and the like. The data section of a running
2169 program is usually alterable: for example, C variables would be stored
2170 in the data section.
2175 This section contains zeroed bytes when your program begins running. It
2176 is used to hold unitialized variables or common storage. The length of
2177 each partial program's bss section is important, but because it starts
2178 out containing zeroed bytes there is no need to store explicit zero
2179 bytes in the object file. The bss section was invented to eliminate
2180 those explicit zeros from object files.
2182 @cindex absolute section
2183 @item absolute section
2184 Address 0 of this section is always ``relocated'' to runtime address 0.
2185 This is useful if you want to refer to an address that @code{@value{LD}} must
2186 not change when relocating. In this sense we speak of absolute
2187 addresses being ``unrelocatable'': they do not change during relocation.
2189 @cindex undefined section
2190 @item undefined section
2191 This ``section'' is a catch-all for address references to objects not in
2192 the preceding sections.
2193 @c FIXME: ref to some other doc on obj-file formats could go here.
2196 @cindex relocation example
2197 An idealized example of three relocatable sections follows.
2199 The example uses the traditional section names @samp{.text} and @samp{.data}.
2201 Memory addresses are on the horizontal axis.
2205 @c END TEXI2ROFF-KILL
2208 partial program # 1: |ttttt|dddd|00|
2215 partial program # 2: |TTT|DDD|000|
2218 +--+---+-----+--+----+---+-----+~~
2219 linked program: | |TTT|ttttt| |dddd|DDD|00000|
2220 +--+---+-----+--+----+---+-----+~~
2222 addresses: 0 @dots{}
2229 \line{\it Partial program \#1: \hfil}
2230 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
2231 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
2233 \line{\it Partial program \#2: \hfil}
2234 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
2235 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
2237 \line{\it linked program: \hfil}
2238 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
2239 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
2240 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
2241 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
2243 \line{\it addresses: \hfil}
2247 @c END TEXI2ROFF-KILL
2250 @section Assembler Internal Sections
2252 @cindex internal assembler sections
2253 @cindex sections in messages, internal
2254 These sections are meant only for the internal use of @code{@value{AS}}. They
2255 have no meaning at run-time. You do not really need to know about these
2256 sections for most purposes; but they can be mentioned in @code{@value{AS}}
2257 warning messages, so it might be helpful to have an idea of their
2258 meanings to @code{@value{AS}}. These sections are used to permit the
2259 value of every expression in your assembly language program to be a
2260 section-relative address.
2263 @cindex assembler internal logic error
2264 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
2265 An internal assembler logic error has been found. This means there is a
2266 bug in the assembler.
2268 @cindex expr (internal section)
2270 The assembler stores complex expression internally as combinations of
2271 symbols. When it needs to represent an expression as a symbol, it puts
2272 it in the expr section.
2274 @c FIXME item transfer[t] vector preload
2275 @c FIXME item transfer[t] vector postload
2276 @c FIXME item register
2280 @section Sub-Sections
2282 @cindex numbered subsections
2283 @cindex grouping data
2289 fall into two sections: text and data.
2291 You may have separate groups of
2293 data in named sections
2297 data in named sections
2303 that you want to end up near to each other in the object file, even though they
2304 are not contiguous in the assembler source. @code{@value{AS}} allows you to
2305 use @dfn{subsections} for this purpose. Within each section, there can be
2306 numbered subsections with values from 0 to 8192. Objects assembled into the
2307 same subsection go into the object file together with other objects in the same
2308 subsection. For example, a compiler might want to store constants in the text
2309 section, but might not want to have them interspersed with the program being
2310 assembled. In this case, the compiler could issue a @samp{.text 0} before each
2311 section of code being output, and a @samp{.text 1} before each group of
2312 constants being output.
2314 Subsections are optional. If you do not use subsections, everything
2315 goes in subsection number zero.
2318 Each subsection is zero-padded up to a multiple of four bytes.
2319 (Subsections may be padded a different amount on different flavors
2320 of @code{@value{AS}}.)
2324 On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
2325 boundary (two bytes).
2326 The same is true on the Hitachi SH.
2329 @c FIXME section padding (alignment)?
2330 @c Rich Pixley says padding here depends on target obj code format; that
2331 @c doesn't seem particularly useful to say without further elaboration,
2332 @c so for now I say nothing about it. If this is a generic BFD issue,
2333 @c these paragraphs might need to vanish from this manual, and be
2334 @c discussed in BFD chapter of binutils (or some such).
2337 On the AMD 29K family, no particular padding is added to section or
2338 subsection sizes; @value{AS} forces no alignment on this platform.
2342 Subsections appear in your object file in numeric order, lowest numbered
2343 to highest. (All this to be compatible with other people's assemblers.)
2344 The object file contains no representation of subsections; @code{@value{LD}} and
2345 other programs that manipulate object files see no trace of them.
2346 They just see all your text subsections as a text section, and all your
2347 data subsections as a data section.
2349 To specify which subsection you want subsequent statements assembled
2350 into, use a numeric argument to specify it, in a @samp{.text
2351 @var{expression}} or a @samp{.data @var{expression}} statement.
2354 When generating COFF output, you
2359 can also use an extra subsection
2360 argument with arbitrary named sections: @samp{.section @var{name},
2363 @var{Expression} should be an absolute expression.
2364 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
2365 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
2366 begins in @code{text 0}. For instance:
2368 .text 0 # The default subsection is text 0 anyway.
2369 .ascii "This lives in the first text subsection. *"
2371 .ascii "But this lives in the second text subsection."
2373 .ascii "This lives in the data section,"
2374 .ascii "in the first data subsection."
2376 .ascii "This lives in the first text section,"
2377 .ascii "immediately following the asterisk (*)."
2380 Each section has a @dfn{location counter} incremented by one for every byte
2381 assembled into that section. Because subsections are merely a convenience
2382 restricted to @code{@value{AS}} there is no concept of a subsection location
2383 counter. There is no way to directly manipulate a location counter---but the
2384 @code{.align} directive changes it, and any label definition captures its
2385 current value. The location counter of the section where statements are being
2386 assembled is said to be the @dfn{active} location counter.
2389 @section bss Section
2392 @cindex common variable storage
2393 The bss section is used for local common variable storage.
2394 You may allocate address space in the bss section, but you may
2395 not dictate data to load into it before your program executes. When
2396 your program starts running, all the contents of the bss
2397 section are zeroed bytes.
2399 The @code{.lcomm} pseudo-op defines a symbol in the bss section; see
2400 @ref{Lcomm,,@code{.lcomm}}.
2402 The @code{.comm} pseudo-op may be used to declare a common symbol, which is
2403 another form of uninitialized symbol; see @xref{Comm,,@code{.comm}}.
2406 When assembling for a target which supports multiple sections, such as ELF or
2407 COFF, you may switch into the @code{.bss} section and define symbols as usual;
2408 see @ref{Section,,@code{.section}}. You may only assemble zero values into the
2409 section. Typically the section will only contain symbol definitions and
2410 @code{.skip} directives (@pxref{Skip,,@code{.skip}}).
2417 Symbols are a central concept: the programmer uses symbols to name
2418 things, the linker uses symbols to link, and the debugger uses symbols
2422 @cindex debuggers, and symbol order
2423 @emph{Warning:} @code{@value{AS}} does not place symbols in the object file in
2424 the same order they were declared. This may break some debuggers.
2429 * Setting Symbols:: Giving Symbols Other Values
2430 * Symbol Names:: Symbol Names
2431 * Dot:: The Special Dot Symbol
2432 * Symbol Attributes:: Symbol Attributes
2439 A @dfn{label} is written as a symbol immediately followed by a colon
2440 @samp{:}. The symbol then represents the current value of the
2441 active location counter, and is, for example, a suitable instruction
2442 operand. You are warned if you use the same symbol to represent two
2443 different locations: the first definition overrides any other
2447 On the HPPA, the usual form for a label need not be immediately followed by a
2448 colon, but instead must start in column zero. Only one label may be defined on
2449 a single line. To work around this, the HPPA version of @code{@value{AS}} also
2450 provides a special directive @code{.label} for defining labels more flexibly.
2453 @node Setting Symbols
2454 @section Giving Symbols Other Values
2456 @cindex assigning values to symbols
2457 @cindex symbol values, assigning
2458 A symbol can be given an arbitrary value by writing a symbol, followed
2459 by an equals sign @samp{=}, followed by an expression
2460 (@pxref{Expressions}). This is equivalent to using the @code{.set}
2461 directive. @xref{Set,,@code{.set}}.
2464 @section Symbol Names
2466 @cindex symbol names
2467 @cindex names, symbol
2468 @ifclear SPECIAL-SYMS
2469 Symbol names begin with a letter or with one of @samp{._}. On most
2470 machines, you can also use @code{$} in symbol names; exceptions are
2471 noted in @ref{Machine Dependencies}. That character may be followed by any
2472 string of digits, letters, dollar signs (unless otherwise noted in
2473 @ref{Machine Dependencies}), and underscores.
2476 For the AMD 29K family, @samp{?} is also allowed in the
2477 body of a symbol name, though not at its beginning.
2482 Symbol names begin with a letter or with one of @samp{._}. On the
2484 H8/500, you can also use @code{$} in symbol names. That character may
2485 be followed by any string of digits, letters, dollar signs (save on the
2486 H8/300), and underscores.
2490 Case of letters is significant: @code{foo} is a different symbol name
2493 Each symbol has exactly one name. Each name in an assembly language program
2494 refers to exactly one symbol. You may use that symbol name any number of times
2497 @subheading Local Symbol Names
2499 @cindex local symbol names
2500 @cindex symbol names, local
2501 @cindex temporary symbol names
2502 @cindex symbol names, temporary
2503 Local symbols help compilers and programmers use names temporarily.
2504 There are ten local symbol names, which are re-used throughout the
2505 program. You may refer to them using the names @samp{0} @samp{1}
2506 @dots{} @samp{9}. To define a local symbol, write a label of the form
2507 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
2508 recent previous definition of that symbol write @samp{@b{N}b}, using the
2509 same digit as when you defined the label. To refer to the next
2510 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
2511 a choice of 10 forward references. The @samp{b} stands for
2512 ``backwards'' and the @samp{f} stands for ``forwards''.
2514 Local symbols are not emitted by the current @sc{gnu} C compiler.
2516 There is no restriction on how you can use these labels, but
2517 remember that at any point in the assembly you can refer to at most
2518 10 prior local labels and to at most 10 forward local labels.
2520 Local symbol names are only a notation device. They are immediately
2521 transformed into more conventional symbol names before the assembler
2522 uses them. The symbol names stored in the symbol table, appearing in
2523 error messages and optionally emitted to the object file have these
2528 All local labels begin with @samp{L}. Normally both @code{@value{AS}} and
2529 @code{@value{LD}} forget symbols that start with @samp{L}. These labels are
2530 used for symbols you are never intended to see. If you use the
2531 @samp{-L} option then @code{@value{AS}} retains these symbols in the
2532 object file. If you also instruct @code{@value{LD}} to retain these symbols,
2533 you may use them in debugging.
2536 If the label is written @samp{0:} then the digit is @samp{0}.
2537 If the label is written @samp{1:} then the digit is @samp{1}.
2538 And so on up through @samp{9:}.
2541 This unusual character is included so you do not accidentally invent
2542 a symbol of the same name. The character has ASCII value
2545 @item @emph{ordinal number}
2546 This is a serial number to keep the labels distinct. The first
2547 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
2548 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
2552 For instance, the first @code{1:} is named @code{L1@kbd{C-A}1}, the 44th
2553 @code{3:} is named @code{L3@kbd{C-A}44}.
2556 @section The Special Dot Symbol
2558 @cindex dot (symbol)
2559 @cindex @code{.} (symbol)
2560 @cindex current address
2561 @cindex location counter
2562 The special symbol @samp{.} refers to the current address that
2563 @code{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
2564 .long .} defines @code{melvin} to contain its own address.
2565 Assigning a value to @code{.} is treated the same as a @code{.org}
2566 directive. Thus, the expression @samp{.=.+4} is the same as saying
2567 @ifclear no-space-dir
2576 @node Symbol Attributes
2577 @section Symbol Attributes
2579 @cindex symbol attributes
2580 @cindex attributes, symbol
2581 Every symbol has, as well as its name, the attributes ``Value'' and
2582 ``Type''. Depending on output format, symbols can also have auxiliary
2585 The detailed definitions are in @file{a.out.h}.
2588 If you use a symbol without defining it, @code{@value{AS}} assumes zero for
2589 all these attributes, and probably won't warn you. This makes the
2590 symbol an externally defined symbol, which is generally what you
2594 * Symbol Value:: Value
2595 * Symbol Type:: Type
2598 * a.out Symbols:: Symbol Attributes: @code{a.out}
2602 * a.out Symbols:: Symbol Attributes: @code{a.out}
2605 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
2610 * COFF Symbols:: Symbol Attributes for COFF
2613 * SOM Symbols:: Symbol Attributes for SOM
2620 @cindex value of a symbol
2621 @cindex symbol value
2622 The value of a symbol is (usually) 32 bits. For a symbol which labels a
2623 location in the text, data, bss or absolute sections the value is the
2624 number of addresses from the start of that section to the label.
2625 Naturally for text, data and bss sections the value of a symbol changes
2626 as @code{@value{LD}} changes section base addresses during linking. Absolute
2627 symbols' values do not change during linking: that is why they are
2630 The value of an undefined symbol is treated in a special way. If it is
2631 0 then the symbol is not defined in this assembler source file, and
2632 @code{@value{LD}} tries to determine its value from other files linked into the
2633 same program. You make this kind of symbol simply by mentioning a symbol
2634 name without defining it. A non-zero value represents a @code{.comm}
2635 common declaration. The value is how much common storage to reserve, in
2636 bytes (addresses). The symbol refers to the first address of the
2642 @cindex type of a symbol
2644 The type attribute of a symbol contains relocation (section)
2645 information, any flag settings indicating that a symbol is external, and
2646 (optionally), other information for linkers and debuggers. The exact
2647 format depends on the object-code output format in use.
2652 @c The following avoids a "widow" subsection title. @group would be
2653 @c better if it were available outside examples.
2656 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
2658 @cindex @code{b.out} symbol attributes
2659 @cindex symbol attributes, @code{b.out}
2660 These symbol attributes appear only when @code{@value{AS}} is configured for
2661 one of the Berkeley-descended object output formats---@code{a.out} or
2667 @subsection Symbol Attributes: @code{a.out}
2669 @cindex @code{a.out} symbol attributes
2670 @cindex symbol attributes, @code{a.out}
2676 @subsection Symbol Attributes: @code{a.out}
2678 @cindex @code{a.out} symbol attributes
2679 @cindex symbol attributes, @code{a.out}
2683 * Symbol Desc:: Descriptor
2684 * Symbol Other:: Other
2688 @subsubsection Descriptor
2690 @cindex descriptor, of @code{a.out} symbol
2691 This is an arbitrary 16-bit value. You may establish a symbol's
2692 descriptor value by using a @code{.desc} statement
2693 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
2697 @subsubsection Other
2699 @cindex other attribute, of @code{a.out} symbol
2700 This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}.
2705 @subsection Symbol Attributes for COFF
2707 @cindex COFF symbol attributes
2708 @cindex symbol attributes, COFF
2710 The COFF format supports a multitude of auxiliary symbol attributes;
2711 like the primary symbol attributes, they are set between @code{.def} and
2712 @code{.endef} directives.
2714 @subsubsection Primary Attributes
2716 @cindex primary attributes, COFF symbols
2717 The symbol name is set with @code{.def}; the value and type,
2718 respectively, with @code{.val} and @code{.type}.
2720 @subsubsection Auxiliary Attributes
2722 @cindex auxiliary attributes, COFF symbols
2723 The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
2724 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2725 information for COFF.
2730 @subsection Symbol Attributes for SOM
2732 @cindex SOM symbol attributes
2733 @cindex symbol attributes, SOM
2735 The SOM format for the HPPA supports a multitude of symbol attributes set with
2736 the @code{.EXPORT} and @code{.IMPORT} directives.
2738 The attributes are described in @cite{HP9000 Series 800 Assembly
2739 Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
2740 @code{EXPORT} assembler directive documentation.
2744 @chapter Expressions
2748 @cindex numeric values
2749 An @dfn{expression} specifies an address or numeric value.
2750 Whitespace may precede and/or follow an expression.
2752 The result of an expression must be an absolute number, or else an offset into
2753 a particular section. If an expression is not absolute, and there is not
2754 enough information when @code{@value{AS}} sees the expression to know its
2755 section, a second pass over the source program might be necessary to interpret
2756 the expression---but the second pass is currently not implemented.
2757 @code{@value{AS}} aborts with an error message in this situation.
2760 * Empty Exprs:: Empty Expressions
2761 * Integer Exprs:: Integer Expressions
2765 @section Empty Expressions
2767 @cindex empty expressions
2768 @cindex expressions, empty
2769 An empty expression has no value: it is just whitespace or null.
2770 Wherever an absolute expression is required, you may omit the
2771 expression, and @code{@value{AS}} assumes a value of (absolute) 0. This
2772 is compatible with other assemblers.
2775 @section Integer Expressions
2777 @cindex integer expressions
2778 @cindex expressions, integer
2779 An @dfn{integer expression} is one or more @emph{arguments} delimited
2780 by @emph{operators}.
2783 * Arguments:: Arguments
2784 * Operators:: Operators
2785 * Prefix Ops:: Prefix Operators
2786 * Infix Ops:: Infix Operators
2790 @subsection Arguments
2792 @cindex expression arguments
2793 @cindex arguments in expressions
2794 @cindex operands in expressions
2795 @cindex arithmetic operands
2796 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2797 contexts arguments are sometimes called ``arithmetic operands''. In
2798 this manual, to avoid confusing them with the ``instruction operands'' of
2799 the machine language, we use the term ``argument'' to refer to parts of
2800 expressions only, reserving the word ``operand'' to refer only to machine
2801 instruction operands.
2803 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2804 @var{section} is one of text, data, bss, absolute,
2805 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2808 Numbers are usually integers.
2810 A number can be a flonum or bignum. In this case, you are warned
2811 that only the low order 32 bits are used, and @code{@value{AS}} pretends
2812 these 32 bits are an integer. You may write integer-manipulating
2813 instructions that act on exotic constants, compatible with other
2816 @cindex subexpressions
2817 Subexpressions are a left parenthesis @samp{(} followed by an integer
2818 expression, followed by a right parenthesis @samp{)}; or a prefix
2819 operator followed by an argument.
2822 @subsection Operators
2824 @cindex operators, in expressions
2825 @cindex arithmetic functions
2826 @cindex functions, in expressions
2827 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2828 operators are followed by an argument. Infix operators appear
2829 between their arguments. Operators may be preceded and/or followed by
2833 @subsection Prefix Operator
2835 @cindex prefix operators
2836 @code{@value{AS}} has the following @dfn{prefix operators}. They each take
2837 one argument, which must be absolute.
2839 @c the tex/end tex stuff surrounding this small table is meant to make
2840 @c it align, on the printed page, with the similar table in the next
2841 @c section (which is inside an enumerate).
2843 \global\advance\leftskip by \itemindent
2848 @dfn{Negation}. Two's complement negation.
2850 @dfn{Complementation}. Bitwise not.
2854 \global\advance\leftskip by -\itemindent
2858 @subsection Infix Operators
2860 @cindex infix operators
2861 @cindex operators, permitted arguments
2862 @dfn{Infix operators} take two arguments, one on either side. Operators
2863 have precedence, but operations with equal precedence are performed left
2864 to right. Apart from @code{+} or @code{-}, both arguments must be
2865 absolute, and the result is absolute.
2868 @cindex operator precedence
2869 @cindex precedence of operators
2876 @dfn{Multiplication}.
2879 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2886 @dfn{Shift Left}. Same as the C operator @samp{<<}.
2890 @dfn{Shift Right}. Same as the C operator @samp{>>}.
2894 Intermediate precedence
2899 @dfn{Bitwise Inclusive Or}.
2905 @dfn{Bitwise Exclusive Or}.
2908 @dfn{Bitwise Or Not}.
2915 @cindex addition, permitted arguments
2916 @cindex plus, permitted arguments
2917 @cindex arguments for addition
2919 @dfn{Addition}. If either argument is absolute, the result has the section of
2920 the other argument. You may not add together arguments from different
2923 @cindex subtraction, permitted arguments
2924 @cindex minus, permitted arguments
2925 @cindex arguments for subtraction
2927 @dfn{Subtraction}. If the right argument is absolute, the
2928 result has the section of the left argument.
2929 If both arguments are in the same section, the result is absolute.
2930 You may not subtract arguments from different sections.
2931 @c FIXME is there still something useful to say about undefined - undefined ?
2935 In short, it's only meaningful to add or subtract the @emph{offsets} in an
2936 address; you can only have a defined section in one of the two arguments.
2939 @chapter Assembler Directives
2941 @cindex directives, machine independent
2942 @cindex pseudo-ops, machine independent
2943 @cindex machine independent directives
2944 All assembler directives have names that begin with a period (@samp{.}).
2945 The rest of the name is letters, usually in lower case.
2947 This chapter discusses directives that are available regardless of the
2948 target machine configuration for the @sc{gnu} assembler.
2950 Some machine configurations provide additional directives.
2951 @xref{Machine Dependencies}.
2954 @ifset machine-directives
2955 @xref{Machine Dependencies} for additional directives.
2960 * Abort:: @code{.abort}
2962 * ABORT:: @code{.ABORT}
2965 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2966 * App-File:: @code{.app-file @var{string}}
2967 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2968 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2969 * Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}}
2970 * Byte:: @code{.byte @var{expressions}}
2971 * Comm:: @code{.comm @var{symbol} , @var{length} }
2972 * Data:: @code{.data @var{subsection}}
2974 * Def:: @code{.def @var{name}}
2977 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2983 * Double:: @code{.double @var{flonums}}
2984 * Eject:: @code{.eject}
2985 * Else:: @code{.else}
2987 * Endef:: @code{.endef}
2990 * Endif:: @code{.endif}
2991 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2992 * Equiv:: @code{.equiv @var{symbol}, @var{expression}}
2994 * Extern:: @code{.extern}
2995 @ifclear no-file-dir
2996 * File:: @code{.file @var{string}}
2999 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
3000 * Float:: @code{.float @var{flonums}}
3001 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
3002 * hword:: @code{.hword @var{expressions}}
3003 * Ident:: @code{.ident}
3004 * If:: @code{.if @var{absolute expression}}
3005 * Include:: @code{.include "@var{file}"}
3006 * Int:: @code{.int @var{expressions}}
3007 * Irp:: @code{.irp @var{symbol},@var{values}}@dots{}
3008 * Irpc:: @code{.irpc @var{symbol},@var{values}}@dots{}
3009 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
3010 * Lflags:: @code{.lflags}
3011 @ifclear no-line-dir
3012 * Line:: @code{.line @var{line-number}}
3015 * Ln:: @code{.ln @var{line-number}}
3016 * Linkonce:: @code{.linkonce [@var{type}]}
3017 * List:: @code{.list}
3018 * Long:: @code{.long @var{expressions}}
3020 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
3023 * Macro:: @code{.macro @var{name} @var{args}}@dots{}
3024 * MRI:: @code{.mri @var{val}}
3026 * Nolist:: @code{.nolist}
3027 * Octa:: @code{.octa @var{bignums}}
3028 * Org:: @code{.org @var{new-lc} , @var{fill}}
3029 * P2align:: @code{.p2align @var{abs-expr} , @var{abs-expr}}
3030 * Psize:: @code{.psize @var{lines}, @var{columns}}
3031 * Quad:: @code{.quad @var{bignums}}
3032 * Rept:: @code{.rept @var{count}}
3033 * Sbttl:: @code{.sbttl "@var{subheading}"}
3035 * Scl:: @code{.scl @var{class}}
3036 * Section:: @code{.section @var{name}, @var{subsection}}
3039 * Set:: @code{.set @var{symbol}, @var{expression}}
3040 * Short:: @code{.short @var{expressions}}
3041 * Single:: @code{.single @var{flonums}}
3043 * Size:: @code{.size}
3046 * Skip:: @code{.skip @var{size} , @var{fill}}
3047 * Sleb128:: @code{.sleb128 @var{expressions}}
3048 * Space:: @code{.space @var{size} , @var{fill}}
3050 * Stab:: @code{.stabd, .stabn, .stabs}
3053 * String:: @code{.string "@var{str}"}
3055 * Symver:: @code{.symver @var{name},@var{name2@@nodename}}
3058 * Tag:: @code{.tag @var{structname}}
3061 * Text:: @code{.text @var{subsection}}
3062 * Title:: @code{.title "@var{heading}"}
3064 * Type:: @code{.type @var{int}}
3065 * Val:: @code{.val @var{addr}}
3068 * Uleb128:: @code{.uleb128 @var{expressions}}
3069 * Word:: @code{.word @var{expressions}}
3070 * Deprecated:: Deprecated Directives
3074 @section @code{.abort}
3076 @cindex @code{abort} directive
3077 @cindex stopping the assembly
3078 This directive stops the assembly immediately. It is for
3079 compatibility with other assemblers. The original idea was that the
3080 assembly language source would be piped into the assembler. If the sender
3081 of the source quit, it could use this directive tells @code{@value{AS}} to
3082 quit also. One day @code{.abort} will not be supported.
3086 @section @code{.ABORT}
3088 @cindex @code{ABORT} directive
3089 When producing COFF output, @code{@value{AS}} accepts this directive as a
3090 synonym for @samp{.abort}.
3093 When producing @code{b.out} output, @code{@value{AS}} accepts this directive,
3099 @section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
3101 @cindex padding the location counter
3102 @cindex @code{align} directive
3103 Pad the location counter (in the current subsection) to a particular storage
3104 boundary. The first expression (which must be absolute) is the alignment
3105 required, as described below.
3107 The second expression (also absolute) gives the fill value to be stored in the
3108 padding bytes. It (and the comma) may be omitted. If it is omitted, the
3109 padding bytes are normally zero. However, on some systems, if the section is
3110 marked as containing code and the fill value is omitted, the space is filled
3111 with no-op instructions.
3113 The third expression is also absolute, and is also optional. If it is present,
3114 it is the maximum number of bytes that should be skipped by this alignment
3115 directive. If doing the alignment would require skipping more bytes than the
3116 specified maximum, then the alignment is not done at all. You can omit the
3117 fill value (the second argument) entirely by simply using two commas after the
3118 required alignment; this can be useful if you want the alignment to be filled
3119 with no-op instructions when appropriate.
3121 The way the required alignment is specified varies from system to system.
3122 For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF
3124 the first expression is the
3125 alignment request in bytes. For example @samp{.align 8} advances
3126 the location counter until it is a multiple of 8. If the location counter
3127 is already a multiple of 8, no change is needed.
3129 For other systems, including the i386 using a.out format, it is the
3130 number of low-order zero bits the location counter must have after
3131 advancement. For example @samp{.align 3} advances the location
3132 counter until it a multiple of 8. If the location counter is already a
3133 multiple of 8, no change is needed.
3135 This inconsistency is due to the different behaviors of the various
3136 native assemblers for these systems which GAS must emulate.
3137 GAS also provides @code{.balign} and @code{.p2align} directives,
3138 described later, which have a consistent behavior across all
3139 architectures (but are specific to GAS).
3142 @section @code{.app-file @var{string}}
3144 @cindex logical file name
3145 @cindex file name, logical
3146 @cindex @code{app-file} directive
3148 @ifclear no-file-dir
3149 (which may also be spelled @samp{.file})
3151 tells @code{@value{AS}} that we are about to start a new
3152 logical file. @var{string} is the new file name. In general, the
3153 filename is recognized whether or not it is surrounded by quotes @samp{"};
3154 but if you wish to specify an empty file name is permitted,
3155 you must give the quotes--@code{""}. This statement may go away in
3156 future: it is only recognized to be compatible with old @code{@value{AS}}
3160 @section @code{.ascii "@var{string}"}@dots{}
3162 @cindex @code{ascii} directive
3163 @cindex string literals
3164 @code{.ascii} expects zero or more string literals (@pxref{Strings})
3165 separated by commas. It assembles each string (with no automatic
3166 trailing zero byte) into consecutive addresses.
3169 @section @code{.asciz "@var{string}"}@dots{}
3171 @cindex @code{asciz} directive
3172 @cindex zero-terminated strings
3173 @cindex null-terminated strings
3174 @code{.asciz} is just like @code{.ascii}, but each string is followed by
3175 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
3178 @section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
3180 @cindex padding the location counter given number of bytes
3181 @cindex @code{balign} directive
3182 Pad the location counter (in the current subsection) to a particular
3183 storage boundary. The first expression (which must be absolute) is the
3184 alignment request in bytes. For example @samp{.balign 8} advances
3185 the location counter until it is a multiple of 8. If the location counter
3186 is already a multiple of 8, no change is needed.
3188 The second expression (also absolute) gives the fill value to be stored in the
3189 padding bytes. It (and the comma) may be omitted. If it is omitted, the
3190 padding bytes are normally zero. However, on some systems, if the section is
3191 marked as containing code and the fill value is omitted, the space is filled
3192 with no-op instructions.
3194 The third expression is also absolute, and is also optional. If it is present,
3195 it is the maximum number of bytes that should be skipped by this alignment
3196 directive. If doing the alignment would require skipping more bytes than the
3197 specified maximum, then the alignment is not done at all. You can omit the
3198 fill value (the second argument) entirely by simply using two commas after the
3199 required alignment; this can be useful if you want the alignment to be filled
3200 with no-op instructions when appropriate.
3202 @cindex @code{balignw} directive
3203 @cindex @code{balignl} directive
3204 The @code{.balignw} and @code{.balignl} directives are variants of the
3205 @code{.balign} directive. The @code{.balignw} directive treats the fill
3206 pattern as a two byte word value. The @code{.balignl} directives treats the
3207 fill pattern as a four byte longword value. For example, @code{.balignw
3208 4,0x368d} will align to a multiple of 4. If it skips two bytes, they will be
3209 filled in with the value 0x368d (the exact placement of the bytes depends upon
3210 the endianness of the processor). If it skips 1 or 3 bytes, the fill value is
3214 @section @code{.byte @var{expressions}}
3216 @cindex @code{byte} directive
3217 @cindex integers, one byte
3218 @code{.byte} expects zero or more expressions, separated by commas.
3219 Each expression is assembled into the next byte.
3222 @section @code{.comm @var{symbol} , @var{length} }
3224 @cindex @code{comm} directive
3225 @cindex symbol, common
3226 @code{.comm} declares a common symbol named @var{symbol}. When linking, a
3227 common symbol in one object file may be merged with a defined or common symbol
3228 of the same name in another object file. If @code{@value{LD}} does not see a
3229 definition for the symbol--just one or more common symbols--then it will
3230 allocate @var{length} bytes of uninitialized memory. @var{length} must be an
3231 absolute expression. If @code{@value{LD}} sees multiple common symbols with
3232 the same name, and they do not all have the same size, it will allocate space
3233 using the largest size.
3236 When using ELF, the @code{.comm} directive takes an optional third argument.
3237 This is the desired alignment of the symbol, specified as a byte boundary (for
3238 example, an alignment of 16 means that the least significant 4 bits of the
3239 address should be zero). The alignment must be an absolute expression, and it
3240 must be a power of two. If @code{@value{LD}} allocates uninitialized memory
3241 for the common symbol, it will use the alignment when placing the symbol. If
3242 no alignment is specified, @code{@value{AS}} will set the alignment to the
3243 largest power of two less than or equal to the size of the symbol, up to a
3248 The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
3249 @samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
3253 @section @code{.data @var{subsection}}
3255 @cindex @code{data} directive
3256 @code{.data} tells @code{@value{AS}} to assemble the following statements onto the
3257 end of the data subsection numbered @var{subsection} (which is an
3258 absolute expression). If @var{subsection} is omitted, it defaults
3263 @section @code{.def @var{name}}
3265 @cindex @code{def} directive
3266 @cindex COFF symbols, debugging
3267 @cindex debugging COFF symbols
3268 Begin defining debugging information for a symbol @var{name}; the
3269 definition extends until the @code{.endef} directive is encountered.
3272 This directive is only observed when @code{@value{AS}} is configured for COFF
3273 format output; when producing @code{b.out}, @samp{.def} is recognized,
3280 @section @code{.desc @var{symbol}, @var{abs-expression}}
3282 @cindex @code{desc} directive
3283 @cindex COFF symbol descriptor
3284 @cindex symbol descriptor, COFF
3285 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
3286 to the low 16 bits of an absolute expression.
3289 The @samp{.desc} directive is not available when @code{@value{AS}} is
3290 configured for COFF output; it is only for @code{a.out} or @code{b.out}
3291 object format. For the sake of compatibility, @code{@value{AS}} accepts
3292 it, but produces no output, when configured for COFF.
3298 @section @code{.dim}
3300 @cindex @code{dim} directive
3301 @cindex COFF auxiliary symbol information
3302 @cindex auxiliary symbol information, COFF
3303 This directive is generated by compilers to include auxiliary debugging
3304 information in the symbol table. It is only permitted inside
3305 @code{.def}/@code{.endef} pairs.
3308 @samp{.dim} is only meaningful when generating COFF format output; when
3309 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3315 @section @code{.double @var{flonums}}
3317 @cindex @code{double} directive
3318 @cindex floating point numbers (double)
3319 @code{.double} expects zero or more flonums, separated by commas. It
3320 assembles floating point numbers.
3322 The exact kind of floating point numbers emitted depends on how
3323 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
3327 On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
3328 in @sc{ieee} format.
3333 @section @code{.eject}
3335 @cindex @code{eject} directive
3336 @cindex new page, in listings
3337 @cindex page, in listings
3338 @cindex listing control: new page
3339 Force a page break at this point, when generating assembly listings.
3342 @section @code{.else}
3344 @cindex @code{else} directive
3345 @code{.else} is part of the @code{@value{AS}} support for conditional
3346 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
3347 of code to be assembled if the condition for the preceding @code{.if}
3351 @node End, Endef, Else, Pseudo Ops
3352 @section @code{.end}
3354 @cindex @code{end} directive
3355 This doesn't do anything---but isn't an s_ignore, so I suspect it's
3356 meant to do something eventually (which is why it isn't documented here
3357 as "for compatibility with blah").
3362 @section @code{.endef}
3364 @cindex @code{endef} directive
3365 This directive flags the end of a symbol definition begun with
3369 @samp{.endef} is only meaningful when generating COFF format output; if
3370 @code{@value{AS}} is configured to generate @code{b.out}, it accepts this
3371 directive but ignores it.
3376 @section @code{.endif}
3378 @cindex @code{endif} directive
3379 @code{.endif} is part of the @code{@value{AS}} support for conditional assembly;
3380 it marks the end of a block of code that is only assembled
3381 conditionally. @xref{If,,@code{.if}}.
3384 @section @code{.equ @var{symbol}, @var{expression}}
3386 @cindex @code{equ} directive
3387 @cindex assigning values to symbols
3388 @cindex symbols, assigning values to
3389 This directive sets the value of @var{symbol} to @var{expression}.
3390 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
3393 The syntax for @code{equ} on the HPPA is
3394 @samp{@var{symbol} .equ @var{expression}}.
3398 @section @code{.equiv @var{symbol}, @var{expression}}
3399 @cindex @code{equiv} directive
3400 The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that
3401 the assembler will signal an error if @var{symbol} is already defined.
3403 Except for the contents of the error message, this is roughly equivalent to
3412 @section @code{.err}
3413 @cindex @code{err} directive
3414 If @code{@value{AS}} assembles a @code{.err} directive, it will print an error
3415 message and, unless the @code{-Z} option was used, it will not generate an
3416 object file. This can be used to signal error an conditionally compiled code.
3419 @section @code{.extern}
3421 @cindex @code{extern} directive
3422 @code{.extern} is accepted in the source program---for compatibility
3423 with other assemblers---but it is ignored. @code{@value{AS}} treats
3424 all undefined symbols as external.
3426 @ifclear no-file-dir
3428 @section @code{.file @var{string}}
3430 @cindex @code{file} directive
3431 @cindex logical file name
3432 @cindex file name, logical
3433 @code{.file} (which may also be spelled @samp{.app-file}) tells
3434 @code{@value{AS}} that we are about to start a new logical file.
3435 @var{string} is the new file name. In general, the filename is
3436 recognized whether or not it is surrounded by quotes @samp{"}; but if
3437 you wish to specify an empty file name, you must give the
3438 quotes--@code{""}. This statement may go away in future: it is only
3439 recognized to be compatible with old @code{@value{AS}} programs.
3441 In some configurations of @code{@value{AS}}, @code{.file} has already been
3442 removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}.
3447 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
3449 @cindex @code{fill} directive
3450 @cindex writing patterns in memory
3451 @cindex patterns, writing in memory
3452 @var{result}, @var{size} and @var{value} are absolute expressions.
3453 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
3454 may be zero or more. @var{Size} may be zero or more, but if it is
3455 more than 8, then it is deemed to have the value 8, compatible with
3456 other people's assemblers. The contents of each @var{repeat} bytes
3457 is taken from an 8-byte number. The highest order 4 bytes are
3458 zero. The lowest order 4 bytes are @var{value} rendered in the
3459 byte-order of an integer on the computer @code{@value{AS}} is assembling for.
3460 Each @var{size} bytes in a repetition is taken from the lowest order
3461 @var{size} bytes of this number. Again, this bizarre behavior is
3462 compatible with other people's assemblers.
3464 @var{size} and @var{value} are optional.
3465 If the second comma and @var{value} are absent, @var{value} is
3466 assumed zero. If the first comma and following tokens are absent,
3467 @var{size} is assumed to be 1.
3470 @section @code{.float @var{flonums}}
3472 @cindex floating point numbers (single)
3473 @cindex @code{float} directive
3474 This directive assembles zero or more flonums, separated by commas. It
3475 has the same effect as @code{.single}.
3477 The exact kind of floating point numbers emitted depends on how
3478 @code{@value{AS}} is configured.
3479 @xref{Machine Dependencies}.
3483 On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
3484 in @sc{ieee} format.
3489 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
3491 @cindex @code{global} directive
3492 @cindex symbol, making visible to linker
3493 @code{.global} makes the symbol visible to @code{@value{LD}}. If you define
3494 @var{symbol} in your partial program, its value is made available to
3495 other partial programs that are linked with it. Otherwise,
3496 @var{symbol} takes its attributes from a symbol of the same name
3497 from another file linked into the same program.
3499 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
3500 compatibility with other assemblers.
3503 On the HPPA, @code{.global} is not always enough to make it accessible to other
3504 partial programs. You may need the HPPA-only @code{.EXPORT} directive as well.
3505 @xref{HPPA Directives,, HPPA Assembler Directives}.
3509 @section @code{.hword @var{expressions}}
3511 @cindex @code{hword} directive
3512 @cindex integers, 16-bit
3513 @cindex numbers, 16-bit
3514 @cindex sixteen bit integers
3515 This expects zero or more @var{expressions}, and emits
3516 a 16 bit number for each.
3519 This directive is a synonym for @samp{.short}; depending on the target
3520 architecture, it may also be a synonym for @samp{.word}.
3524 This directive is a synonym for @samp{.short}.
3527 This directive is a synonym for both @samp{.short} and @samp{.word}.
3532 @section @code{.ident}
3534 @cindex @code{ident} directive
3535 This directive is used by some assemblers to place tags in object files.
3536 @code{@value{AS}} simply accepts the directive for source-file
3537 compatibility with such assemblers, but does not actually emit anything
3541 @section @code{.if @var{absolute expression}}
3543 @cindex conditional assembly
3544 @cindex @code{if} directive
3545 @code{.if} marks the beginning of a section of code which is only
3546 considered part of the source program being assembled if the argument
3547 (which must be an @var{absolute expression}) is non-zero. The end of
3548 the conditional section of code must be marked by @code{.endif}
3549 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
3550 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}).
3552 The following variants of @code{.if} are also supported:
3554 @cindex @code{ifdef} directive
3555 @item .ifdef @var{symbol}
3556 Assembles the following section of code if the specified @var{symbol}
3560 @cindex @code{ifeqs} directive
3562 Not yet implemented.
3565 @cindex @code{ifndef} directive
3566 @cindex @code{ifnotdef} directive
3567 @item .ifndef @var{symbol}
3568 @itemx .ifnotdef @var{symbol}
3569 Assembles the following section of code if the specified @var{symbol}
3570 has not been defined. Both spelling variants are equivalent.
3574 Not yet implemented.
3579 @section @code{.include "@var{file}"}
3581 @cindex @code{include} directive
3582 @cindex supporting files, including
3583 @cindex files, including
3584 This directive provides a way to include supporting files at specified
3585 points in your source program. The code from @var{file} is assembled as
3586 if it followed the point of the @code{.include}; when the end of the
3587 included file is reached, assembly of the original file continues. You
3588 can control the search paths used with the @samp{-I} command-line option
3589 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
3593 @section @code{.int @var{expressions}}
3595 @cindex @code{int} directive
3596 @cindex integers, 32-bit
3597 Expect zero or more @var{expressions}, of any section, separated by commas.
3598 For each expression, emit a number that, at run time, is the value of that
3599 expression. The byte order and bit size of the number depends on what kind
3600 of target the assembly is for.
3604 On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
3605 integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits
3611 @section @code{.irp @var{symbol},@var{values}}@dots{}
3613 @cindex @code{irp} directive
3614 Evaluate a sequence of statements assigning different values to @var{symbol}.
3615 The sequence of statements starts at the @code{.irp} directive, and is
3616 terminated by an @code{.endr} directive. For each @var{value}, @var{symbol} is
3617 set to @var{value}, and the sequence of statements is assembled. If no
3618 @var{value} is listed, the sequence of statements is assembled once, with
3619 @var{symbol} set to the null string. To refer to @var{symbol} within the
3620 sequence of statements, use @var{\symbol}.
3622 For example, assembling
3630 is equivalent to assembling
3639 @section @code{.irpc @var{symbol},@var{values}}@dots{}
3641 @cindex @code{irpc} directive
3642 Evaluate a sequence of statements assigning different values to @var{symbol}.
3643 The sequence of statements starts at the @code{.irpc} directive, and is
3644 terminated by an @code{.endr} directive. For each character in @var{value},
3645 @var{symbol} is set to the character, and the sequence of statements is
3646 assembled. If no @var{value} is listed, the sequence of statements is
3647 assembled once, with @var{symbol} set to the null string. To refer to
3648 @var{symbol} within the sequence of statements, use @var{\symbol}.
3650 For example, assembling
3658 is equivalent to assembling
3667 @section @code{.lcomm @var{symbol} , @var{length}}
3669 @cindex @code{lcomm} directive
3670 @cindex local common symbols
3671 @cindex symbols, local common
3672 Reserve @var{length} (an absolute expression) bytes for a local common
3673 denoted by @var{symbol}. The section and value of @var{symbol} are
3674 those of the new local common. The addresses are allocated in the bss
3675 section, so that at run-time the bytes start off zeroed. @var{Symbol}
3676 is not declared global (@pxref{Global,,@code{.global}}), so is normally
3677 not visible to @code{@value{LD}}.
3680 Some targets permit a third argument to be used with @code{.lcomm}. This
3681 argument specifies the desired alignment of the symbol in the bss section.
3685 The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
3686 @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
3690 @section @code{.lflags}
3692 @cindex @code{lflags} directive (ignored)
3693 @code{@value{AS}} accepts this directive, for compatibility with other
3694 assemblers, but ignores it.
3696 @ifclear no-line-dir
3698 @section @code{.line @var{line-number}}
3700 @cindex @code{line} directive
3704 @section @code{.ln @var{line-number}}
3706 @cindex @code{ln} directive
3708 @cindex logical line number
3710 Change the logical line number. @var{line-number} must be an absolute
3711 expression. The next line has that logical line number. Therefore any other
3712 statements on the current line (after a statement separator character) are
3713 reported as on logical line number @var{line-number} @minus{} 1. One day
3714 @code{@value{AS}} will no longer support this directive: it is recognized only
3715 for compatibility with existing assembler programs.
3719 @emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
3720 not available; use the synonym @code{.ln} in that context.
3725 @ifclear no-line-dir
3726 Even though this is a directive associated with the @code{a.out} or
3727 @code{b.out} object-code formats, @code{@value{AS}} still recognizes it
3728 when producing COFF output, and treats @samp{.line} as though it
3729 were the COFF @samp{.ln} @emph{if} it is found outside a
3730 @code{.def}/@code{.endef} pair.
3732 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
3733 used by compilers to generate auxiliary symbol information for
3738 @section @code{.linkonce [@var{type}]}
3740 @cindex @code{linkonce} directive
3741 @cindex common sections
3742 Mark the current section so that the linker only includes a single copy of it.
3743 This may be used to include the same section in several different object files,
3744 but ensure that the linker will only include it once in the final output file.
3745 The @code{.linkonce} pseudo-op must be used for each instance of the section.
3746 Duplicate sections are detected based on the section name, so it should be
3749 This directive is only supported by a few object file formats; as of this
3750 writing, the only object file format which supports it is the Portable
3751 Executable format used on Windows NT.
3753 The @var{type} argument is optional. If specified, it must be one of the
3754 following strings. For example:
3758 Not all types may be supported on all object file formats.
3762 Silently discard duplicate sections. This is the default.
3765 Warn if there are duplicate sections, but still keep only one copy.
3768 Warn if any of the duplicates have different sizes.
3771 Warn if any of the duplicates do not have exactly the same contents.
3775 @section @code{.ln @var{line-number}}
3777 @cindex @code{ln} directive
3778 @ifclear no-line-dir
3779 @samp{.ln} is a synonym for @samp{.line}.
3782 Tell @code{@value{AS}} to change the logical line number. @var{line-number}
3783 must be an absolute expression. The next line has that logical
3784 line number, so any other statements on the current line (after a
3785 statement separator character @code{;}) are reported as on logical
3786 line number @var{line-number} @minus{} 1.
3789 This directive is accepted, but ignored, when @code{@value{AS}} is
3790 configured for @code{b.out}; its effect is only associated with COFF
3796 @section @code{.mri @var{val}}
3798 @cindex @code{mri} directive
3799 @cindex MRI mode, temporarily
3800 If @var{val} is non-zero, this tells @code{@value{AS}} to enter MRI mode. If
3801 @var{val} is zero, this tells @code{@value{AS}} to exit MRI mode. This change
3802 affects code assembled until the next @code{.mri} directive, or until the end
3803 of the file. @xref{M, MRI mode, MRI mode}.
3806 @section @code{.list}
3808 @cindex @code{list} directive
3809 @cindex listing control, turning on
3810 Control (in conjunction with the @code{.nolist} directive) whether or
3811 not assembly listings are generated. These two directives maintain an
3812 internal counter (which is zero initially). @code{.list} increments the
3813 counter, and @code{.nolist} decrements it. Assembly listings are
3814 generated whenever the counter is greater than zero.
3816 By default, listings are disabled. When you enable them (with the
3817 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
3818 the initial value of the listing counter is one.
3821 @section @code{.long @var{expressions}}
3823 @cindex @code{long} directive
3824 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
3827 @c no one seems to know what this is for or whether this description is
3828 @c what it really ought to do
3830 @section @code{.lsym @var{symbol}, @var{expression}}
3832 @cindex @code{lsym} directive
3833 @cindex symbol, not referenced in assembly
3834 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
3835 the hash table, ensuring it cannot be referenced by name during the
3836 rest of the assembly. This sets the attributes of the symbol to be
3837 the same as the expression value:
3839 @var{other} = @var{descriptor} = 0
3840 @var{type} = @r{(section of @var{expression})}
3841 @var{value} = @var{expression}
3844 The new symbol is not flagged as external.
3848 @section @code{.macro}
3851 The commands @code{.macro} and @code{.endm} allow you to define macros that
3852 generate assembly output. For example, this definition specifies a macro
3853 @code{sum} that puts a sequence of numbers into memory:
3856 .macro sum from=0, to=5
3865 With that definition, @samp{SUM 0,5} is equivalent to this assembly input:
3877 @item .macro @var{macname}
3878 @itemx .macro @var{macname} @var{macargs} @dots{}
3879 @cindex @code{macro} directive
3880 Begin the definition of a macro called @var{macname}. If your macro
3881 definition requires arguments, specify their names after the macro name,
3882 separated by commas or spaces. You can supply a default value for any
3883 macro argument by following the name with @samp{=@var{deflt}}. For
3884 example, these are all valid @code{.macro} statements:
3888 Begin the definition of a macro called @code{comm}, which takes no
3891 @item .macro plus1 p, p1
3892 @itemx .macro plus1 p p1
3893 Either statement begins the definition of a macro called @code{plus1},
3894 which takes two arguments; within the macro definition, write
3895 @samp{\p} or @samp{\p1} to evaluate the arguments.
3897 @item .macro reserve_str p1=0 p2
3898 Begin the definition of a macro called @code{reserve_str}, with two
3899 arguments. The first argument has a default value, but not the second.
3900 After the definition is complete, you can call the macro either as
3901 @samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to
3902 @var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str
3903 ,@var{b}} (with @samp{\p1} evaluating as the default, in this case
3904 @samp{0}, and @samp{\p2} evaluating to @var{b}).
3907 When you call a macro, you can specify the argument values either by
3908 position, or by keyword. For example, @samp{sum 9,17} is equivalent to
3909 @samp{sum to=17, from=9}.
3912 @cindex @code{endm} directive
3913 Mark the end of a macro definition.
3916 @cindex @code{exitm} directive
3917 Exit early from the current macro definition.
3919 @cindex number of macros executed
3920 @cindex macros, count executed
3922 @code{@value{AS}} maintains a counter of how many macros it has
3923 executed in this pseudo-variable; you can copy that number to your
3924 output with @samp{\@@}, but @emph{only within a macro definition}.
3927 @item LOCAL @var{name} [ , @dots{} ]
3928 @emph{Warning: @code{LOCAL} is only available if you select ``alternate
3929 macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,,
3930 Alternate macro syntax}.
3932 Generate a string replacement for each of the @var{name} arguments, and
3933 replace any instances of @var{name} in each macro expansion. The
3934 replacement string is unique in the assembly, and different for each
3935 separate macro expansion. @code{LOCAL} allows you to write macros that
3936 define symbols, without fear of conflict between separate macro expansions.
3941 @section @code{.nolist}
3943 @cindex @code{nolist} directive
3944 @cindex listing control, turning off
3945 Control (in conjunction with the @code{.list} directive) whether or
3946 not assembly listings are generated. These two directives maintain an
3947 internal counter (which is zero initially). @code{.list} increments the
3948 counter, and @code{.nolist} decrements it. Assembly listings are
3949 generated whenever the counter is greater than zero.
3952 @section @code{.octa @var{bignums}}
3954 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
3955 @cindex @code{octa} directive
3956 @cindex integer, 16-byte
3957 @cindex sixteen byte integer
3958 This directive expects zero or more bignums, separated by commas. For each
3959 bignum, it emits a 16-byte integer.
3961 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
3962 hence @emph{octa}-word for 16 bytes.
3965 @section @code{.org @var{new-lc} , @var{fill}}
3967 @cindex @code{org} directive
3968 @cindex location counter, advancing
3969 @cindex advancing location counter
3970 @cindex current address, advancing
3971 Advance the location counter of the current section to
3972 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3973 expression with the same section as the current subsection. That is,
3974 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3975 wrong section, the @code{.org} directive is ignored. To be compatible
3976 with former assemblers, if the section of @var{new-lc} is absolute,
3977 @code{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
3978 is the same as the current subsection.
3980 @code{.org} may only increase the location counter, or leave it
3981 unchanged; you cannot use @code{.org} to move the location counter
3984 @c double negative used below "not undefined" because this is a specific
3985 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3986 @c section. doc@cygnus.com 18feb91
3987 Because @code{@value{AS}} tries to assemble programs in one pass, @var{new-lc}
3988 may not be undefined. If you really detest this restriction we eagerly await
3989 a chance to share your improved assembler.
3991 Beware that the origin is relative to the start of the section, not
3992 to the start of the subsection. This is compatible with other
3993 people's assemblers.
3995 When the location counter (of the current subsection) is advanced, the
3996 intervening bytes are filled with @var{fill} which should be an
3997 absolute expression. If the comma and @var{fill} are omitted,
3998 @var{fill} defaults to zero.
4001 @section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
4003 @cindex padding the location counter given a power of two
4004 @cindex @code{p2align} directive
4005 Pad the location counter (in the current subsection) to a particular
4006 storage boundary. The first expression (which must be absolute) is the
4007 number of low-order zero bits the location counter must have after
4008 advancement. For example @samp{.p2align 3} advances the location
4009 counter until it a multiple of 8. If the location counter is already a
4010 multiple of 8, no change is needed.
4012 The second expression (also absolute) gives the fill value to be stored in the
4013 padding bytes. It (and the comma) may be omitted. If it is omitted, the
4014 padding bytes are normally zero. However, on some systems, if the section is
4015 marked as containing code and the fill value is omitted, the space is filled
4016 with no-op instructions.
4018 The third expression is also absolute, and is also optional. If it is present,
4019 it is the maximum number of bytes that should be skipped by this alignment
4020 directive. If doing the alignment would require skipping more bytes than the
4021 specified maximum, then the alignment is not done at all. You can omit the
4022 fill value (the second argument) entirely by simply using two commas after the
4023 required alignment; this can be useful if you want the alignment to be filled
4024 with no-op instructions when appropriate.
4026 @cindex @code{p2alignw} directive
4027 @cindex @code{p2alignl} directive
4028 The @code{.p2alignw} and @code{.p2alignl} directives are variants of the
4029 @code{.p2align} directive. The @code{.p2alignw} directive treats the fill
4030 pattern as a two byte word value. The @code{.p2alignl} directives treats the
4031 fill pattern as a four byte longword value. For example, @code{.p2alignw
4032 2,0x368d} will align to a multiple of 4. If it skips two bytes, they will be
4033 filled in with the value 0x368d (the exact placement of the bytes depends upon
4034 the endianness of the processor). If it skips 1 or 3 bytes, the fill value is
4038 @section @code{.psize @var{lines} , @var{columns}}
4040 @cindex @code{psize} directive
4041 @cindex listing control: paper size
4042 @cindex paper size, for listings
4043 Use this directive to declare the number of lines---and, optionally, the
4044 number of columns---to use for each page, when generating listings.
4046 If you do not use @code{.psize}, listings use a default line-count
4047 of 60. You may omit the comma and @var{columns} specification; the
4048 default width is 200 columns.
4050 @code{@value{AS}} generates formfeeds whenever the specified number of
4051 lines is exceeded (or whenever you explicitly request one, using
4054 If you specify @var{lines} as @code{0}, no formfeeds are generated save
4055 those explicitly specified with @code{.eject}.
4058 @section @code{.quad @var{bignums}}
4060 @cindex @code{quad} directive
4061 @code{.quad} expects zero or more bignums, separated by commas. For
4062 each bignum, it emits
4064 an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
4065 warning message; and just takes the lowest order 8 bytes of the bignum.
4066 @cindex eight-byte integer
4067 @cindex integer, 8-byte
4069 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
4070 hence @emph{quad}-word for 8 bytes.
4073 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
4074 warning message; and just takes the lowest order 16 bytes of the bignum.
4075 @cindex sixteen-byte integer
4076 @cindex integer, 16-byte
4080 @section @code{.rept @var{count}}
4082 @cindex @code{rept} directive
4083 Repeat the sequence of lines between the @code{.rept} directive and the next
4084 @code{.endr} directive @var{count} times.
4086 For example, assembling
4094 is equivalent to assembling
4103 @section @code{.sbttl "@var{subheading}"}
4105 @cindex @code{sbttl} directive
4106 @cindex subtitles for listings
4107 @cindex listing control: subtitle
4108 Use @var{subheading} as the title (third line, immediately after the
4109 title line) when generating assembly listings.
4111 This directive affects subsequent pages, as well as the current page if
4112 it appears within ten lines of the top of a page.
4116 @section @code{.scl @var{class}}
4118 @cindex @code{scl} directive
4119 @cindex symbol storage class (COFF)
4120 @cindex COFF symbol storage class
4121 Set the storage-class value for a symbol. This directive may only be
4122 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
4123 whether a symbol is static or external, or it may record further
4124 symbolic debugging information.
4127 The @samp{.scl} directive is primarily associated with COFF output; when
4128 configured to generate @code{b.out} output format, @code{@value{AS}}
4129 accepts this directive but ignores it.
4134 @section @code{.section @var{name}}
4136 @cindex @code{section} directive
4137 @cindex named section
4138 Use the @code{.section} directive to assemble the following code into a section
4141 This directive is only supported for targets that actually support arbitrarily
4142 named sections; on @code{a.out} targets, for example, it is not accepted, even
4143 with a standard @code{a.out} section name.
4146 For COFF targets, the @code{.section} directive is used in one of the following
4149 .section @var{name}[, "@var{flags}"]
4150 .section @var{name}[, @var{subsegment}]
4153 If the optional argument is quoted, it is taken as flags to use for the
4154 section. Each flag is a single character. The following flags are recognized:
4157 bss section (uninitialized data)
4159 section is not loaded
4170 If no flags are specified, the default flags depend upon the section name. If
4171 the section name is not recognized, the default will be for the section to be
4172 loaded and writable.
4174 If the optional argument to the @code{.section} directive is not quoted, it is
4175 taken as a subsegment number (@pxref{Sub-Sections}).
4179 For ELF targets, the @code{.section} directive is used like this:
4181 .section @var{name}[, "@var{flags}"[, @@@var{type}]]
4183 The optional @var{flags} argument is a quoted string which may contain any
4184 combintion of the following characters:
4187 section is allocatable
4191 section is executable
4194 The optional @var{type} argument may contain one of the following constants:
4197 section contains data
4199 section does not contain data (i.e., section only occupies space)
4202 If no flags are specified, the default flags depend upon the section name. If
4203 the section name is not recognized, the default will be for the section to have
4204 none of the above flags: it will not be allocated in memory, nor writable, nor
4205 executable. The section will contain data.
4207 For ELF targets, the assembler supports another type of @code{.section}
4208 directive for compatibility with the Solaris assembler:
4210 .section "@var{name}"[, @var{flags}...]
4212 Note that the section name is quoted. There may be a sequence of comma
4216 section is allocatable
4220 section is executable
4225 @section @code{.set @var{symbol}, @var{expression}}
4227 @cindex @code{set} directive
4228 @cindex symbol value, setting
4229 Set the value of @var{symbol} to @var{expression}. This
4230 changes @var{symbol}'s value and type to conform to
4231 @var{expression}. If @var{symbol} was flagged as external, it remains
4232 flagged (@pxref{Symbol Attributes}).
4234 You may @code{.set} a symbol many times in the same assembly.
4236 If you @code{.set} a global symbol, the value stored in the object
4237 file is the last value stored into it.
4240 The syntax for @code{set} on the HPPA is
4241 @samp{@var{symbol} .set @var{expression}}.
4245 @section @code{.short @var{expressions}}
4247 @cindex @code{short} directive
4249 @code{.short} is normally the same as @samp{.word}.
4250 @xref{Word,,@code{.word}}.
4252 In some configurations, however, @code{.short} and @code{.word} generate
4253 numbers of different lengths; @pxref{Machine Dependencies}.
4257 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
4260 This expects zero or more @var{expressions}, and emits
4261 a 16 bit number for each.
4266 @section @code{.single @var{flonums}}
4268 @cindex @code{single} directive
4269 @cindex floating point numbers (single)
4270 This directive assembles zero or more flonums, separated by commas. It
4271 has the same effect as @code{.float}.
4273 The exact kind of floating point numbers emitted depends on how
4274 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
4278 On the @value{TARGET} family, @code{.single} emits 32-bit floating point
4279 numbers in @sc{ieee} format.
4285 @section @code{.size}
4287 @cindex @code{size} directive
4288 This directive is generated by compilers to include auxiliary debugging
4289 information in the symbol table. It is only permitted inside
4290 @code{.def}/@code{.endef} pairs.
4293 @samp{.size} is only meaningful when generating COFF format output; when
4294 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
4300 @section @code{.sleb128 @var{expressions}}
4302 @cindex @code{sleb128} directive
4303 @var{sleb128} stands for ``signed little endian base 128.'' This is a
4304 compact, variable length representation of numbers used by the DWARF
4305 symbolic debugging format. @xref{Uleb128,@code{.uleb128}}.
4307 @ifclear no-space-dir
4309 @section @code{.skip @var{size} , @var{fill}}
4311 @cindex @code{skip} directive
4312 @cindex filling memory
4313 This directive emits @var{size} bytes, each of value @var{fill}. Both
4314 @var{size} and @var{fill} are absolute expressions. If the comma and
4315 @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same as
4319 @section @code{.space @var{size} , @var{fill}}
4321 @cindex @code{space} directive
4322 @cindex filling memory
4323 This directive emits @var{size} bytes, each of value @var{fill}. Both
4324 @var{size} and @var{fill} are absolute expressions. If the comma
4325 and @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same
4330 @emph{Warning:} @code{.space} has a completely different meaning for HPPA
4331 targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800
4332 Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the
4333 @code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives},
4342 @section @code{.space}
4343 @cindex @code{space} directive
4345 On the AMD 29K, this directive is ignored; it is accepted for
4346 compatibility with other AMD 29K assemblers.
4349 @emph{Warning:} In most versions of the @sc{gnu} assembler, the directive
4350 @code{.space} has the effect of @code{.block} @xref{Machine Dependencies}.
4356 @section @code{.stabd, .stabn, .stabs}
4358 @cindex symbolic debuggers, information for
4359 @cindex @code{stab@var{x}} directives
4360 There are three directives that begin @samp{.stab}.
4361 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
4362 The symbols are not entered in the @code{@value{AS}} hash table: they
4363 cannot be referenced elsewhere in the source file.
4364 Up to five fields are required:
4368 This is the symbol's name. It may contain any character except
4369 @samp{\000}, so is more general than ordinary symbol names. Some
4370 debuggers used to code arbitrarily complex structures into symbol names
4374 An absolute expression. The symbol's type is set to the low 8 bits of
4375 this expression. Any bit pattern is permitted, but @code{@value{LD}}
4376 and debuggers choke on silly bit patterns.
4379 An absolute expression. The symbol's ``other'' attribute is set to the
4380 low 8 bits of this expression.
4383 An absolute expression. The symbol's descriptor is set to the low 16
4384 bits of this expression.
4387 An absolute expression which becomes the symbol's value.
4390 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
4391 or @code{.stabs} statement, the symbol has probably already been created;
4392 you get a half-formed symbol in your object file. This is
4393 compatible with earlier assemblers!
4396 @cindex @code{stabd} directive
4397 @item .stabd @var{type} , @var{other} , @var{desc}
4399 The ``name'' of the symbol generated is not even an empty string.
4400 It is a null pointer, for compatibility. Older assemblers used a
4401 null pointer so they didn't waste space in object files with empty
4404 The symbol's value is set to the location counter,
4405 relocatably. When your program is linked, the value of this symbol
4406 is the address of the location counter when the @code{.stabd} was
4409 @cindex @code{stabn} directive
4410 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
4411 The name of the symbol is set to the empty string @code{""}.
4413 @cindex @code{stabs} directive
4414 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
4415 All five fields are specified.
4421 @section @code{.string} "@var{str}"
4423 @cindex string, copying to object file
4424 @cindex @code{string} directive
4426 Copy the characters in @var{str} to the object file. You may specify more than
4427 one string to copy, separated by commas. Unless otherwise specified for a
4428 particular machine, the assembler marks the end of each string with a 0 byte.
4429 You can use any of the escape sequences described in @ref{Strings,,Strings}.
4433 @section @code{.symver}
4434 @cindex @code{symver} directive
4435 @cindex symbol versioning
4436 @cindex versions of symbols
4437 Use the @code{.symver} directive to bind symbols to specific version nodes
4438 within a source file. This is only supported on ELF platforms, and is
4439 typically used when assembling files to be linked into a shared library.
4440 There are cases where it may make sense to use this in objects to be bound
4441 into an application itself so as to override a versioned symbol from a
4444 For ELF targets, the @code{.symver} directive is used like this:
4446 .symver @var{name}, @var{name2@@nodename}
4448 In this case, the symbol @var{name} must exist and be defined within the file
4449 being assembled. The @code{.versym} directive effectively creates a symbol
4450 alias with the name @var{name2@@nodename}, and in fact the main reason that we
4451 just don't try and create a regular alias is that the @var{@@} character isn't
4452 permitted in symbol names. The @var{name2} part of the name is the actual name
4453 of the symbol by which it will be externally referenced. The name @var{name}
4454 itself is merely a name of convenience that is used so that it is possible to
4455 have definitions for multiple versions of a function within a single source
4456 file, and so that the compiler can unambiguously know which version of a
4457 function is being mentioned. The @var{nodename} portion of the alias should be
4458 the name of a node specified in the version script supplied to the linker when
4459 building a shared library. If you are attempting to override a versioned
4460 symbol from a shared library, then @var{nodename} should correspond to the
4461 nodename of the symbol you are trying to override.
4466 @section @code{.tag @var{structname}}
4468 @cindex COFF structure debugging
4469 @cindex structure debugging, COFF
4470 @cindex @code{tag} directive
4471 This directive is generated by compilers to include auxiliary debugging
4472 information in the symbol table. It is only permitted inside
4473 @code{.def}/@code{.endef} pairs. Tags are used to link structure
4474 definitions in the symbol table with instances of those structures.
4477 @samp{.tag} is only used when generating COFF format output; when
4478 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
4484 @section @code{.text @var{subsection}}
4486 @cindex @code{text} directive
4487 Tells @code{@value{AS}} to assemble the following statements onto the end of
4488 the text subsection numbered @var{subsection}, which is an absolute
4489 expression. If @var{subsection} is omitted, subsection number zero
4493 @section @code{.title "@var{heading}"}
4495 @cindex @code{title} directive
4496 @cindex listing control: title line
4497 Use @var{heading} as the title (second line, immediately after the
4498 source file name and pagenumber) when generating assembly listings.
4500 This directive affects subsequent pages, as well as the current page if
4501 it appears within ten lines of the top of a page.
4505 @section @code{.type @var{int}}
4507 @cindex COFF symbol type
4508 @cindex symbol type, COFF
4509 @cindex @code{type} directive
4510 This directive, permitted only within @code{.def}/@code{.endef} pairs,
4511 records the integer @var{int} as the type attribute of a symbol table entry.
4514 @samp{.type} is associated only with COFF format output; when
4515 @code{@value{AS}} is configured for @code{b.out} output, it accepts this
4516 directive but ignores it.
4522 @section @code{.val @var{addr}}
4524 @cindex @code{val} directive
4525 @cindex COFF value attribute
4526 @cindex value attribute, COFF
4527 This directive, permitted only within @code{.def}/@code{.endef} pairs,
4528 records the address @var{addr} as the value attribute of a symbol table
4532 @samp{.val} is used only for COFF output; when @code{@value{AS}} is
4533 configured for @code{b.out}, it accepts this directive but ignores it.
4538 @section @code{.uleb128 @var{expressions}}
4540 @cindex @code{uleb128} directive
4541 @var{uleb128} stands for ``unsigned little endian base 128.'' This is a
4542 compact, variable length representation of numbers used by the DWARF
4543 symbolic debugging format. @xref{Sleb128,@code{.sleb128}}.
4546 @section @code{.word @var{expressions}}
4548 @cindex @code{word} directive
4549 This directive expects zero or more @var{expressions}, of any section,
4550 separated by commas.
4553 For each expression, @code{@value{AS}} emits a 32-bit number.
4556 For each expression, @code{@value{AS}} emits a 16-bit number.
4561 The size of the number emitted, and its byte order,
4562 depend on what target computer the assembly is for.
4565 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
4566 @c happen---32-bit addressability, period; no long/short jumps.
4567 @ifset DIFF-TBL-KLUGE
4568 @cindex difference tables altered
4569 @cindex altered difference tables
4571 @emph{Warning: Special Treatment to support Compilers}
4575 Machines with a 32-bit address space, but that do less than 32-bit
4576 addressing, require the following special treatment. If the machine of
4577 interest to you does 32-bit addressing (or doesn't require it;
4578 @pxref{Machine Dependencies}), you can ignore this issue.
4581 In order to assemble compiler output into something that works,
4582 @code{@value{AS}} occasionlly does strange things to @samp{.word} directives.
4583 Directives of the form @samp{.word sym1-sym2} are often emitted by
4584 compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a
4585 directive of the form @samp{.word sym1-sym2}, and the difference between
4586 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}}
4587 creates a @dfn{secondary jump table}, immediately before the next label.
4588 This secondary jump table is preceded by a short-jump to the
4589 first byte after the secondary table. This short-jump prevents the flow
4590 of control from accidentally falling into the new table. Inside the
4591 table is a long-jump to @code{sym2}. The original @samp{.word}
4592 contains @code{sym1} minus the address of the long-jump to
4595 If there were several occurrences of @samp{.word sym1-sym2} before the
4596 secondary jump table, all of them are adjusted. If there was a
4597 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
4598 long-jump to @code{sym4} is included in the secondary jump table,
4599 and the @code{.word} directives are adjusted to contain @code{sym3}
4600 minus the address of the long-jump to @code{sym4}; and so on, for as many
4601 entries in the original jump table as necessary.
4604 @emph{This feature may be disabled by compiling @code{@value{AS}} with the
4605 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
4606 assembly language programmers.
4609 @c end DIFF-TBL-KLUGE
4612 @section Deprecated Directives
4614 @cindex deprecated directives
4615 @cindex obsolescent directives
4616 One day these directives won't work.
4617 They are included for compatibility with older assemblers.
4625 @node Machine Dependencies
4626 @chapter Machine Dependent Features
4628 @cindex machine dependencies
4629 The machine instruction sets are (almost by definition) different on
4630 each machine where @code{@value{AS}} runs. Floating point representations
4631 vary as well, and @code{@value{AS}} often supports a few additional
4632 directives or command-line options for compatibility with other
4633 assemblers on a particular platform. Finally, some versions of
4634 @code{@value{AS}} support special pseudo-instructions for branch
4637 This chapter discusses most of these differences, though it does not
4638 include details on any machine's instruction set. For details on that
4639 subject, see the hardware manufacturer's manual.
4643 * AMD29K-Dependent:: AMD 29K Dependent Features
4646 * ARC-Dependent:: ARC Dependent Features
4649 * ARM-Dependent:: ARM Dependent Features
4652 * D10V-Dependent:: D10V Dependent Features
4655 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
4658 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
4661 * HPPA-Dependent:: HPPA Dependent Features
4664 * i386-Dependent:: Intel 80386 Dependent Features
4667 * i960-Dependent:: Intel 80960 Dependent Features
4670 * M68K-Dependent:: M680x0 Dependent Features
4673 * MIPS-Dependent:: MIPS Dependent Features
4676 * SH-Dependent:: Hitachi SH Dependent Features
4679 * Sparc-Dependent:: SPARC Dependent Features
4682 * V850-Dependent:: V850 Dependent Features
4685 * Z8000-Dependent:: Z8000 Dependent Features
4688 * Vax-Dependent:: VAX Dependent Features
4695 @c The following major nodes are *sections* in the GENERIC version, *chapters*
4696 @c in single-cpu versions. This is mainly achieved by @lowersections. There is a
4697 @c peculiarity: to preserve cross-references, there must be a node called
4698 @c "Machine Dependencies". Hence the conditional nodenames in each
4699 @c major node below. Node defaulting in makeinfo requires adjacency of
4700 @c node and sectioning commands; hence the repetition of @chapter BLAH
4701 @c in both conditional blocks.
4707 @chapter ARC Dependent Features
4710 @node Machine Dependencies
4711 @chapter ARC Dependent Features
4716 * ARC-Opts:: Options
4717 * ARC-Float:: Floating Point
4718 * ARC-Directives:: Sparc Machine Directives
4724 @cindex options for ARC
4726 @cindex architectures, ARC
4727 @cindex ARC architectures
4728 The ARC chip family includes several successive levels (or other
4729 variants) of chip, using the same core instruction set, but including
4730 a few additional instructions at each level.
4732 By default, @code{@value{AS}} assumes the core instruction set (ARC
4733 base). The @code{.cpu} pseudo-op is intended to be used to select
4737 @cindex @code{-mbig-endian} option (ARC)
4738 @cindex @code{-mlittle-endian} option (ARC)
4739 @cindex ARC big-endian output
4740 @cindex ARC little-endian output
4741 @cindex big-endian output, ARC
4742 @cindex little-endian output, ARC
4744 @itemx -mlittle-endian
4745 Any @sc{arc} configuration of @code{@value{AS}} can select big-endian or
4746 little-endian output at run time (unlike most other @sc{gnu} development
4747 tools, which must be configured for one or the other). Use
4748 @samp{-mbig-endian} to select big-endian output, and @samp{-mlittle-endian}
4753 @section Floating Point
4755 @cindex floating point, ARC (@sc{ieee})
4756 @cindex ARC floating point (@sc{ieee})
4757 The ARC cpu family currently does not have hardware floating point
4758 support. Software floating point support is provided by @code{GCC}
4759 and uses @sc{ieee} floating-point numbers.
4761 @node ARC-Directives
4762 @section ARC Machine Directives
4764 @cindex ARC machine directives
4765 @cindex machine directives, ARC
4766 The ARC version of @code{@value{AS}} supports the following additional
4771 @cindex @code{cpu} directive, SPARC
4772 This must be followed by the desired cpu.
4773 The ARC is intended to be customizable, @code{.cpu} is used to
4774 select the desired variant [though currently there are none].
4781 @include c-a29k.texi
4790 @node Machine Dependencies
4791 @chapter Machine Dependent Features
4793 The machine instruction sets are different on each Hitachi chip family,
4794 and there are also some syntax differences among the families. This
4795 chapter describes the specific @code{@value{AS}} features for each
4799 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
4800 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
4801 * SH-Dependent:: Hitachi SH Dependent Features
4808 @include c-d10v.texi
4812 @include c-h8300.texi
4816 @include c-h8500.texi
4820 @include c-hppa.texi
4824 @include c-i386.texi
4828 @include c-i960.texi
4832 @include c-m68k.texi
4836 @include c-mips.texi
4840 @include c-ns32k.texi
4848 @include c-sparc.texi
4859 @c start-sanitize-v850
4861 @include c-v850.texi
4863 @c end-sanitize-v850
4866 @c reverse effect of @down at top of generic Machine-Dep chapter
4870 @node Reporting Bugs
4871 @chapter Reporting Bugs
4872 @cindex bugs in assembler
4873 @cindex reporting bugs in assembler
4875 Your bug reports play an essential role in making @code{@value{AS}} reliable.
4877 Reporting a bug may help you by bringing a solution to your problem, or it may
4878 not. But in any case the principal function of a bug report is to help the
4879 entire community by making the next version of @code{@value{AS}} work better.
4880 Bug reports are your contribution to the maintenance of @code{@value{AS}}.
4882 In order for a bug report to serve its purpose, you must include the
4883 information that enables us to fix the bug.
4886 * Bug Criteria:: Have you found a bug?
4887 * Bug Reporting:: How to report bugs
4891 @section Have you found a bug?
4892 @cindex bug criteria
4894 If you are not sure whether you have found a bug, here are some guidelines:
4897 @cindex fatal signal
4898 @cindex assembler crash
4899 @cindex crash of assembler
4901 If the assembler gets a fatal signal, for any input whatever, that is a
4902 @code{@value{AS}} bug. Reliable assemblers never crash.
4904 @cindex error on valid input
4906 If @code{@value{AS}} produces an error message for valid input, that is a bug.
4908 @cindex invalid input
4910 If @code{@value{AS}} does not produce an error message for invalid input, that
4911 is a bug. However, you should note that your idea of ``invalid input'' might
4912 be our idea of ``an extension'' or ``support for traditional practice''.
4915 If you are an experienced user of assemblers, your suggestions for improvement
4916 of @code{@value{AS}} are welcome in any case.
4920 @section How to report bugs
4922 @cindex assembler bugs, reporting
4924 A number of companies and individuals offer support for @sc{gnu} products. If
4925 you obtained @code{@value{AS}} from a support organization, we recommend you
4926 contact that organization first.
4928 You can find contact information for many support companies and
4929 individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
4932 In any event, we also recommend that you send bug reports for @code{@value{AS}}
4933 to @samp{bug-gnu-utils@@prep.ai.mit.edu}.
4935 The fundamental principle of reporting bugs usefully is this:
4936 @strong{report all the facts}. If you are not sure whether to state a
4937 fact or leave it out, state it!
4939 Often people omit facts because they think they know what causes the problem
4940 and assume that some details do not matter. Thus, you might assume that the
4941 name of a symbol you use in an example does not matter. Well, probably it does
4942 not, but one cannot be sure. Perhaps the bug is a stray memory reference which
4943 happens to fetch from the location where that name is stored in memory;
4944 perhaps, if the name were different, the contents of that location would fool
4945 the assembler into doing the right thing despite the bug. Play it safe and
4946 give a specific, complete example. That is the easiest thing for you to do,
4947 and the most helpful.
4949 Keep in mind that the purpose of a bug report is to enable us to fix the bug if
4950 it is new to us. Therefore, always write your bug reports on the assumption
4951 that the bug has not been reported previously.
4953 Sometimes people give a few sketchy facts and ask, ``Does this ring a
4954 bell?'' Those bug reports are useless, and we urge everyone to
4955 @emph{refuse to respond to them} except to chide the sender to report
4958 To enable us to fix the bug, you should include all these things:
4962 The version of @code{@value{AS}}. @code{@value{AS}} announces it if you start
4963 it with the @samp{--version} argument.
4965 Without this, we will not know whether there is any point in looking for
4966 the bug in the current version of @code{@value{AS}}.
4969 Any patches you may have applied to the @code{@value{AS}} source.
4972 The type of machine you are using, and the operating system name and
4976 What compiler (and its version) was used to compile @code{@value{AS}}---e.g.
4980 The command arguments you gave the assembler to assemble your example and
4981 observe the bug. To guarantee you will not omit something important, list them
4982 all. A copy of the Makefile (or the output from make) is sufficient.
4984 If we were to try to guess the arguments, we would probably guess wrong
4985 and then we might not encounter the bug.
4988 A complete input file that will reproduce the bug. If the bug is observed when
4989 the assembler is invoked via a compiler, send the assembler source, not the
4990 high level language source. Most compilers will produce the assembler source
4991 when run with the @samp{-S} option. If you are using @code{@value{GCC}}, use
4992 the options @samp{-v --save-temps}; this will save the assembler source in a
4993 file with an extension of @file{.s}, and also show you exactly how
4994 @code{@value{AS}} is being run.
4997 A description of what behavior you observe that you believe is
4998 incorrect. For example, ``It gets a fatal signal.''
5000 Of course, if the bug is that @code{@value{AS}} gets a fatal signal, then we
5001 will certainly notice it. But if the bug is incorrect output, we might not
5002 notice unless it is glaringly wrong. You might as well not give us a chance to
5005 Even if the problem you experience is a fatal signal, you should still say so
5006 explicitly. Suppose something strange is going on, such as, your copy of
5007 @code{@value{AS}} is out of synch, or you have encountered a bug in the C
5008 library on your system. (This has happened!) Your copy might crash and ours
5009 would not. If you told us to expect a crash, then when ours fails to crash, we
5010 would know that the bug was not happening for us. If you had not told us to
5011 expect a crash, then we would not be able to draw any conclusion from our
5015 If you wish to suggest changes to the @code{@value{AS}} source, send us context
5016 diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
5017 option. Always send diffs from the old file to the new file. If you even
5018 discuss something in the @code{@value{AS}} source, refer to it by context, not
5021 The line numbers in our development sources will not match those in your
5022 sources. Your line numbers would convey no useful information to us.
5025 Here are some things that are not necessary:
5029 A description of the envelope of the bug.
5031 Often people who encounter a bug spend a lot of time investigating
5032 which changes to the input file will make the bug go away and which
5033 changes will not affect it.
5035 This is often time consuming and not very useful, because the way we
5036 will find the bug is by running a single example under the debugger
5037 with breakpoints, not by pure deduction from a series of examples.
5038 We recommend that you save your time for something else.
5040 Of course, if you can find a simpler example to report @emph{instead}
5041 of the original one, that is a convenience for us. Errors in the
5042 output will be easier to spot, running under the debugger will take
5043 less time, and so on.
5045 However, simplification is not vital; if you do not want to do this,
5046 report the bug anyway and send us the entire test case you used.
5049 A patch for the bug.
5051 A patch for the bug does help us if it is a good one. But do not omit
5052 the necessary information, such as the test case, on the assumption that
5053 a patch is all we need. We might see problems with your patch and decide
5054 to fix the problem another way, or we might not understand it at all.
5056 Sometimes with a program as complicated as @code{@value{AS}} it is very hard to
5057 construct an example that will make the program follow a certain path through
5058 the code. If you do not send us the example, we will not be able to construct
5059 one, so we will not be able to verify that the bug is fixed.
5061 And if we cannot understand what bug you are trying to fix, or why your
5062 patch should be an improvement, we will not install it. A test case will
5063 help us to understand.
5066 A guess about what the bug is or what it depends on.
5068 Such guesses are usually wrong. Even we cannot guess right about such
5069 things without first using the debugger to find the facts.
5072 @node Acknowledgements
5073 @chapter Acknowledgements
5075 If you have contributed to @code{@value{AS}} and your name isn't listed here,
5076 it is not meant as a slight. We just don't know about it. Send mail to the
5077 maintainer, and we'll correct the situation. Currently
5079 the maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
5081 Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any
5084 Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
5085 information and the 68k series machines, most of the preprocessing pass, and
5086 extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}.
5088 K. Richard Pixley maintained GAS for a while, adding various enhancements and
5089 many bug fixes, including merging support for several processors, breaking GAS
5090 up to handle multiple object file format back ends (including heavy rewrite,
5091 testing, an integration of the coff and b.out back ends), adding configuration
5092 including heavy testing and verification of cross assemblers and file splits
5093 and renaming, converted GAS to strictly ANSI C including full prototypes, added
5094 support for m680[34]0 and cpu32, did considerable work on i960 including a COFF
5095 port (including considerable amounts of reverse engineering), a SPARC opcode
5096 file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know''
5097 assertions and made them work, much other reorganization, cleanup, and lint.
5099 Ken Raeburn wrote the high-level BFD interface code to replace most of the code
5100 in format-specific I/O modules.
5102 The original VMS support was contributed by David L. Kashtan. Eric Youngdale
5103 has done much work with it since.
5105 The Intel 80386 machine description was written by Eliot Dresselhaus.
5107 Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
5109 The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
5110 University and Torbjorn Granlund of the Swedish Institute of Computer Science.
5112 Keith Knowles at the Open Software Foundation wrote the original MIPS back end
5113 (@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support
5114 (which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to
5115 support a.out format.
5117 Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k,
5118 tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
5119 Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
5120 use BFD for some low-level operations, for use with the H8/300 and AMD 29k
5123 John Gilmore built the AMD 29000 support, added @code{.include} support, and
5124 simplified the configuration of which versions accept which directives. He
5125 updated the 68k machine description so that Motorola's opcodes always produced
5126 fixed-size instructions (e.g. @code{jsr}), while synthetic instructions
5127 remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested
5128 cross-compilation support, and one bug in relaxation that took a week and
5129 required the proverbial one-bit fix.
5131 Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
5132 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
5133 added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and
5134 PowerPC assembler, and made a few other minor patches.
5136 Steve Chamberlain made @code{@value{AS}} able to generate listings.
5138 Hewlett-Packard contributed support for the HP9000/300.
5140 Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
5141 along with a fairly extensive HPPA testsuite (for both SOM and ELF object
5142 formats). This work was supported by both the Center for Software Science at
5143 the University of Utah and Cygnus Support.
5145 Support for ELF format files has been worked on by Mark Eichin of Cygnus
5146 Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
5147 Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
5148 Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
5149 and some initial 64-bit support).
5151 Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD
5152 support for openVMS/Alpha.
5154 Several engineers at Cygnus Support have also provided many small bug fixes and
5155 configuration enhancements.
5157 Many others have contributed large or small bugfixes and enhancements. If
5158 you have contributed significant work and are not mentioned on this list, and
5159 want to be, let us know. Some of the history has been lost; we are not
5160 intentionally leaving anyone out.