1 \input texinfo @c -*-Texinfo-*-
2 @c Copyright (c) 1991 1992 1993 1994 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 asdoc-config.texi
19 @c common OR combinations of conditions
36 @set abnormal-separator
40 @settitle Using @value{AS}
43 @settitle Using @value{AS} (@value{TARGET})
45 @setchapternewpage odd
51 * As: (as). The GNU assembler.
60 This file documents the GNU Assembler "@value{AS}".
62 Copyright (C) 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
64 Permission is granted to make and distribute verbatim copies of
65 this manual provided the copyright notice and this permission notice
66 are preserved on all copies.
69 Permission is granted to process this file through Tex and print the
70 results, provided the printed document carries copying permission
71 notice identical to this one except for the removal of this paragraph
72 (this paragraph not being relevant to the printed manual).
75 Permission is granted to copy and distribute modified versions of this
76 manual under the conditions for verbatim copying, provided also that the
77 section entitled ``GNU General Public License'' is included exactly as
78 in the original, and provided that the entire resulting derived work is
79 distributed under the terms of a permission notice identical to this
82 Permission is granted to copy and distribute translations of this manual
83 into another language, under the above conditions for modified versions,
84 except that the section entitled ``GNU General Public License'' may be
85 included in a translation approved by the Free Software Foundation
86 instead of in the original English.
90 @title Using @value{AS}
91 @subtitle The GNU Assembler
93 @subtitle for the @value{TARGET} family
96 @subtitle January 1994
99 The Free Software Foundation Inc. thanks The Nice Computer
100 Company of Australia for loaning Dean Elsner to write the
101 first (Vax) version of @code{as} for Project GNU.
102 The proprietors, management and staff of TNCCA thank FSF for
103 distracting the boss while they got some work
106 @author Dean Elsner, Jay Fenlason & friends
110 \hfill {\it Using {\tt @value{AS}}}\par
111 \hfill Edited by Roland Pesch for Cygnus Support\par
113 %"boxit" macro for figures:
114 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
115 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
116 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
117 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
118 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
121 @vskip 0pt plus 1filll
122 Copyright @copyright{} 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
124 Permission is granted to make and distribute verbatim copies of
125 this manual provided the copyright notice and this permission notice
126 are preserved on all copies.
128 Permission is granted to copy and distribute modified versions of this
129 manual under the conditions for verbatim copying, provided also that the
130 section entitled ``GNU General Public License'' is included exactly as
131 in the original, and provided that the entire resulting derived work is
132 distributed under the terms of a permission notice identical to this
135 Permission is granted to copy and distribute translations of this manual
136 into another language, under the above conditions for modified versions,
137 except that the section entitled ``GNU General Public License'' may be
138 included in a translation approved by the Free Software Foundation
139 instead of in the original English.
144 @top Using @value{AS}
146 This file is a user guide to the GNU assembler @code{@value{AS}}.
148 This version of the file describes @code{@value{AS}} configured to generate
149 code for @value{TARGET} architectures.
152 * Overview:: Overview
153 * Invoking:: Command-Line Options
155 * Sections:: Sections and Relocation
157 * Expressions:: Expressions
158 * Pseudo Ops:: Assembler Directives
159 * Machine Dependencies:: Machine Dependent Features
161 * Copying:: GNU GENERAL PUBLIC LICENSE
164 * Acknowledgements:: Who Did What
173 This manual is a user guide to the GNU assembler @code{@value{AS}}.
175 This version of the manual describes @code{@value{AS}} configured to generate
176 code for @value{TARGET} architectures.
180 @cindex invocation summary
181 @cindex option summary
182 @cindex summary of options
183 Here is a brief summary of how to invoke @code{@value{AS}}. For details,
184 @pxref{Invoking,,Comand-Line Options}.
186 @c We don't use deffn and friends for the following because they seem
187 @c to be limited to one line for the header.
189 @value{AS} [ -a[dhlns] ] [ -D ] [ -f ] [ -I @var{path} ]
190 [ -K ] [ -L ] [ -o @var{objfile} ] [ -R ]
191 [ --statistics] [ -v ] [ -W ] [ -Z ]
193 @c am29k has no machine-dependent assembler options
196 @c Hitachi family chips have no machine-dependent assembler options
199 @c HPPA has no machine-dependent assembler options (yet).
202 [ -Av6 | -Av7 | -Av8 | -Asparclite | -bump ]
205 @c Z8000 has no machine-dependent assembler options
208 @c see md_parse_option in tc-i960.c
209 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
213 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
216 [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ]
218 [ -- | @var{files} @dots{} ]
223 Turn on listings, in any of a variety of ways:
227 omit debugging directives from listing
230 include high-level source
242 You may combine these options; for example, use @samp{-aln} for assembly
243 listing without forms processing. By itself, @samp{-a} defaults to
244 @samp{-ahls}---that is, all listings turned on.
247 This option is accepted only for script compatibility with calls to
248 other assemblers; it has no effect on @code{@value{AS}}.
251 ``fast''---skip whitespace and comment preprocessing (assume source is
255 Add @var{path} to the search list for @code{.include} directives
258 @ifclear DIFF-TBL-KLUGE
259 This option is accepted but has no effect on the @value{TARGET} family.
261 @ifset DIFF-TBL-KLUGE
262 Issue warnings when difference tables altered for long displacements.
266 Keep (in symbol table) local symbols, starting with @samp{L}
268 @item -o @var{objfile}
269 Name the object-file output from @code{@value{AS}}
272 Fold data section into text section
275 Display maximum space (in bytes), and total time (in seconds), taken by
279 Announce @code{as} version
282 Suppress warning messages
285 Generate object file even after errors
287 @item -- | @var{files} @dots{}
288 Standard input, or source files to assemble.
293 The following options are available when @value{AS} is configured for the
294 Intel 80960 processor.
297 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
298 Specify which variant of the 960 architecture is the target.
301 Add code to collect statistics about branches taken.
304 Do not alter compare-and-branch instructions for long displacements;
311 The following options are available when @value{AS} is configured for the
312 Motorola 68000 series.
317 Shorten references to undefined symbols, to one word instead of two.
319 @item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040
320 @itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32
321 Specify what processor in the 68000 family is the target. The default
322 is normally the 68020, but this can be changed at configuration time.
324 @item -m68881 | -m68882 | -mno-68881 | -mno-68882
325 The target machine does (or does not) have a floating-point coprocessor.
326 The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
327 the basic 68000 is not compatible with the 68881, a combination of the
328 two can be specified, since it's possible to do emulation of the
329 coprocessor instructions with the main processor.
331 @item -m68851 | -mno-68851
332 The target machine does (or does not) have a memory-management
333 unit coprocessor. The default is to assume an MMU for 68020 and up.
339 The following options are available when @code{@value{AS}} is configured
340 for the SPARC architecture:
343 @item -Av6 | -Av7 | -Av8 | -Asparclite
344 Explicitly select a variant of the SPARC architecture.
347 Warn when the assembler switches to another architecture.
352 The following options are available when @value{AS} is configured for
353 the MIPS R2000/R3000 processors.
357 This option sets the largest size of an object that can be referenced
358 implicitly with the @code{gp} register. It is only accepted for targets
359 that use ECOFF format, such as a DECstation running Ultrix. The default
362 @cindex MIPS endianness
363 @cindex endianness, MIPS
365 @cindex big endian output, MIPS
366 Generate ``big endian'' format output.
369 @cindex little endian output, MIPS
370 Generate ``little endian'' format output.
373 This option is ignored. It is accepted for compatibility with the native
379 * Manual:: Structure of this Manual
380 * GNU Assembler:: @value{AS}, the GNU Assembler
381 * Object Formats:: Object File Formats
382 * Command Line:: Command Line
383 * Input Files:: Input Files
384 * Object:: Output (Object) File
385 * Errors:: Error and Warning Messages
389 @section Structure of this Manual
391 @cindex manual, structure and purpose
392 This manual is intended to describe what you need to know to use
393 @sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including
394 notation for symbols, constants, and expressions; the directives that
395 @code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}.
398 We also cover special features in the @value{TARGET}
399 configuration of @code{@value{AS}}, including assembler directives.
402 This manual also describes some of the machine-dependent features of
403 various flavors of the assembler.
406 @cindex machine instructions (not covered)
407 On the other hand, this manual is @emph{not} intended as an introduction
408 to programming in assembly language---let alone programming in general!
409 In a similar vein, we make no attempt to introduce the machine
410 architecture; we do @emph{not} describe the instruction set, standard
411 mnemonics, registers or addressing modes that are standard to a
412 particular architecture.
414 You may want to consult the manufacturer's
415 machine architecture manual for this information.
419 For information on the H8/300 machine instruction set, see @cite{H8/300
420 Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H,
421 see @cite{H8/300H Series Programming Manual} (Hitachi).
424 For information on the H8/500 machine instruction set, see @cite{H8/500
425 Series Programming Manual} (Hitachi M21T001).
428 For information on the Hitachi SH machine instruction set, see
429 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
432 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
436 @c I think this is premature---pesch@cygnus.com, 17jan1991
438 Throughout this manual, we assume that you are running @dfn{GNU},
439 the portable operating system from the @dfn{Free Software
440 Foundation, Inc.}. This restricts our attention to certain kinds of
441 computer (in particular, the kinds of computers that GNU can run on);
442 once this assumption is granted examples and definitions need less
445 @code{@value{AS}} is part of a team of programs that turn a high-level
446 human-readable series of instructions into a low-level
447 computer-readable series of instructions. Different versions of
448 @code{@value{AS}} are used for different kinds of computer.
451 @c There used to be a section "Terminology" here, which defined
452 @c "contents", "byte", "word", and "long". Defining "word" to any
453 @c particular size is confusing when the .word directive may generate 16
454 @c bits on one machine and 32 bits on another; in general, for the user
455 @c version of this manual, none of these terms seem essential to define.
456 @c They were used very little even in the former draft of the manual;
457 @c this draft makes an effort to avoid them (except in names of
461 @section @value{AS}, the GNU Assembler
463 GNU @code{as} is really a family of assemblers.
465 This manual describes @code{@value{AS}}, a member of that family which is
466 configured for the @value{TARGET} architectures.
468 If you use (or have used) the GNU assembler on one architecture, you
469 should find a fairly similar environment when you use it on another
470 architecture. Each version has much in common with the others,
471 including object file formats, most assembler directives (often called
472 @dfn{pseudo-ops}) and assembler syntax.@refill
474 @cindex purpose of @sc{gnu} @code{@value{AS}}
475 @code{@value{AS}} is primarily intended to assemble the output of the
476 GNU C compiler @code{@value{GCC}} for use by the linker
477 @code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}}
478 assemble correctly everything that other assemblers for the same
479 machine would assemble.
481 Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
484 @c This remark should appear in generic version of manual; assumption
485 @c here is that generic version sets M680x0.
486 This doesn't mean @code{@value{AS}} always uses the same syntax as another
487 assembler for the same architecture; for example, we know of several
488 incompatible versions of 680x0 assembly language syntax.
491 Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
492 program in one pass of the source file. This has a subtle impact on the
493 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
496 @section Object File Formats
498 @cindex object file format
499 The GNU assembler can be configured to produce several alternative
500 object file formats. For the most part, this does not affect how you
501 write assembly language programs; but directives for debugging symbols
502 are typically different in different file formats. @xref{Symbol
503 Attributes,,Symbol Attributes}.
506 On the @value{TARGET}, @code{@value{AS}} is configured to produce
507 @value{OBJ-NAME} format object files.
509 @c The following should exhaust all configs that set MULTI-OBJ, ideally
511 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
512 @code{a.out} or COFF format object files.
515 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
516 @code{b.out} or COFF format object files.
519 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
520 SOM or ELF format object files.
525 @section Command Line
527 @cindex command line conventions
528 After the program name @code{@value{AS}}, the command line may contain
529 options and file names. Options may appear in any order, and may be
530 before, after, or between file names. The order of file names is
533 @cindex standard input, as input file
535 @file{--} (two hyphens) by itself names the standard input file
536 explicitly, as one of the files for @code{@value{AS}} to assemble.
538 @cindex options, command line
539 Except for @samp{--} any command line argument that begins with a
540 hyphen (@samp{-}) is an option. Each option changes the behavior of
541 @code{@value{AS}}. No option changes the way another option works. An
542 option is a @samp{-} followed by one or more letters; the case of
543 the letter is important. All options are optional.
545 Some options expect exactly one file name to follow them. The file
546 name may either immediately follow the option's letter (compatible
547 with older assemblers) or it may be the next command argument (GNU
548 standard). These two command lines are equivalent:
551 @value{AS} -o my-object-file.o mumble.s
552 @value{AS} -omy-object-file.o mumble.s
559 @cindex source program
561 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
562 describe the program input to one run of @code{@value{AS}}. The program may
563 be in one or more files; how the source is partitioned into files
564 doesn't change the meaning of the source.
566 @c I added "con" prefix to "catenation" just to prove I can overcome my
567 @c APL training... pesch@cygnus.com
568 The source program is a concatenation of the text in all the files, in the
571 Each time you run @code{@value{AS}} it assembles exactly one source
572 program. The source program is made up of one or more files.
573 (The standard input is also a file.)
575 You give @code{@value{AS}} a command line that has zero or more input file
576 names. The input files are read (from left file name to right). A
577 command line argument (in any position) that has no special meaning
578 is taken to be an input file name.
580 If you give @code{@value{AS}} no file names it attempts to read one input file
581 from the @code{@value{AS}} standard input, which is normally your terminal. You
582 may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program
585 Use @samp{--} if you need to explicitly name the standard input file
586 in your command line.
588 If the source is empty, @code{@value{AS}} produces a small, empty object
591 @subheading Filenames and Line-numbers
593 @cindex input file linenumbers
594 @cindex line numbers, in input files
595 There are two ways of locating a line in the input file (or files) and
596 either may be used in reporting error messages. One way refers to a line
597 number in a physical file; the other refers to a line number in a
598 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
600 @dfn{Physical files} are those files named in the command line given
601 to @code{@value{AS}}.
603 @dfn{Logical files} are simply names declared explicitly by assembler
604 directives; they bear no relation to physical files. Logical file names
605 help error messages reflect the original source file, when @code{@value{AS}}
606 source is itself synthesized from other files.
607 @xref{App-File,,@code{.app-file}}.
610 @section Output (Object) File
616 Every time you run @code{@value{AS}} it produces an output file, which is
617 your assembly language program translated into numbers. This file
618 is the object file, named
622 if @code{@value{AS}} is configured for the Intel 80960, or
628 unless you tell @code{@value{AS}} to
629 give it another name by using the @code{-o} option. Conventionally,
630 object file names end with @file{.o}. The default name of
631 @file{a.out} is used for historical reasons: older assemblers were
632 capable of assembling self-contained programs directly into a
634 (For some formats, this isn't currently possible, but it can be done for
635 @code{a.out} format.)
639 The object file is meant for input to the linker @code{@value{LD}}. It contains
640 assembled program code, information to help @code{@value{LD}} integrate
641 the assembled program into a runnable file, and (optionally) symbolic
642 information for the debugger.
644 @c link above to some info file(s) like the description of a.out.
645 @c don't forget to describe GNU info as well as Unix lossage.
648 @section Error and Warning Messages
650 @cindex error messsages
651 @cindex warning messages
652 @cindex messages from @code{@value{AS}}
653 @code{@value{AS}} may write warnings and error messages to the standard error
654 file (usually your terminal). This should not happen when a compiler
655 runs @code{@value{AS}} automatically. Warnings report an assumption made so
656 that @code{@value{AS}} could keep assembling a flawed program; errors report a
657 grave problem that stops the assembly.
659 @cindex format of warning messages
660 Warning messages have the format
663 file_name:@b{NNN}:Warning Message Text
667 @cindex line numbers, in warnings/errors
668 (where @b{NNN} is a line number). If a logical file name has been given
669 (@pxref{App-File,,@code{.app-file}}) it is used for the filename,
670 otherwise the name of the current input file is used. If a logical line
673 (@pxref{Line,,@code{.line}})
677 (@pxref{Line,,@code{.line}})
680 (@pxref{Ln,,@code{.ln}})
683 then it is used to calculate the number printed,
684 otherwise the actual line in the current source file is printed. The
685 message text is intended to be self explanatory (in the grand Unix
688 @cindex format of error messages
689 Error messages have the format
691 file_name:@b{NNN}:FATAL:Error Message Text
693 The file name and line number are derived as for warning
694 messages. The actual message text may be rather less explanatory
695 because many of them aren't supposed to happen.
698 @chapter Command-Line Options
700 @cindex options, all versions of @code{@value{AS}}
701 This chapter describes command-line options available in @emph{all}
702 versions of the GNU assembler; @pxref{Machine Dependencies}, for options specific
704 to the @value{TARGET}.
707 to particular machine architectures.
710 If you are invoking @code{@value{AS}} via the GNU C compiler (version 2), you
711 can use the @samp{-Wa} option to pass arguments through to the
712 assembler. The assembler arguments must be separated from each other
713 (and the @samp{-Wa}) by commas. For example:
716 gcc -c -g -O -Wa,-alh,-L file.c
720 emits a listing to standard output with high-level
723 Many compiler command-line options, such as @samp{-R} and many machine-specific
724 options, are automatically passed to the assembler by the compiler, so usually
725 you do not need to use this @samp{-Wa} mechanism. (You can call the GNU
726 compiler driver with the @samp{-v} option to see precisely what options it
727 passes to each compilation pass, including the assembler.)
730 * a:: -a[dhlns] enable listings
731 * D:: -D for compatibility
732 * f:: -f to work faster
733 * I:: -I for .include search path
734 @ifclear DIFF-TBL-KLUGE
735 * K:: -K for compatibility
737 @ifset DIFF-TBL-KLUGE
738 * K:: -K for difference tables
741 * L:: -L to retain local labels
742 * o:: -o to name the object file
743 * R:: -R to join data and text sections
744 * statistics:: --statistics to see statistics about assembly
745 * v:: -v to announce version
746 * W:: -W to suppress warnings
747 * Z:: -Z to make object file even after errors
751 @section Enable Listings: @code{-a[dhlns]}
759 @cindex listings, enabling
760 @cindex assembly listings, enabling
762 These options enable listing output from the assembler. By itself,
763 @samp{-a} requests high-level, assembly, and symbols listing.
764 Other letters may be used to select specific options for the list:
765 @samp{-ah} requests a high-level language listing,
766 @samp{-al} requests an output-program assembly listing, and
767 @samp{-as} requests a symbol table listing.
768 High-level listings require that a compiler debugging option like
769 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
772 The @samp{-ad} option may be used to omit debugging directives from the
775 Once you have specified one of these options, you can further control
776 listing output and its appearance using the directives @code{.list},
777 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
779 The @samp{-an} option turns off all forms processing.
780 If you do not request listing output with one of the @samp{-a} options, the
781 listing-control directives have no effect.
783 The letters after @samp{-a} may be combined into one option,
784 @emph{e.g.}, @samp{-aln}.
790 This option has no effect whatsoever, but it is accepted to make it more
791 likely that scripts written for other assemblers also work with
795 @section Work Faster: @code{-f}
798 @cindex trusted compiler
799 @cindex faster processing (@code{-f})
800 @samp{-f} should only be used when assembling programs written by a
801 (trusted) compiler. @samp{-f} stops the assembler from doing whitespace
802 and comment preprocessing on
803 the input file(s) before assembling them. @xref{Preprocessing,
807 @emph{Warning:} if you use @samp{-f} when the files actually need to be
808 preprocessed (if they contain comments, for example), @code{@value{AS}} does
813 @section @code{.include} search path: @code{-I} @var{path}
815 @kindex -I @var{path}
816 @cindex paths for @code{.include}
817 @cindex search path for @code{.include}
818 @cindex @code{include} directive search path
819 Use this option to add a @var{path} to the list of directories
820 @code{@value{AS}} searches for files specified in @code{.include}
821 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
822 many times as necessary to include a variety of paths. The current
823 working directory is always searched first; after that, @code{@value{AS}}
824 searches any @samp{-I} directories in the same order as they were
825 specified (left to right) on the command line.
828 @section Difference Tables: @code{-K}
831 @ifclear DIFF-TBL-KLUGE
832 On the @value{TARGET} family, this option is allowed, but has no effect. It is
833 permitted for compatibility with the GNU assembler on other platforms,
834 where it can be used to warn when the assembler alters the machine code
835 generated for @samp{.word} directives in difference tables. The @value{TARGET}
836 family does not have the addressing limitations that sometimes lead to this
837 alteration on other platforms.
840 @ifset DIFF-TBL-KLUGE
841 @cindex difference tables, warning
842 @cindex warning for altered difference tables
843 @code{@value{AS}} sometimes alters the code emitted for directives of the form
844 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
845 You can use the @samp{-K} option if you want a warning issued when this
850 @section Include Local Labels: @code{-L}
853 @cindex local labels, retaining in output
854 Labels beginning with @samp{L} (upper case only) are called @dfn{local
855 labels}. @xref{Symbol Names}. Normally you do not see such labels when
856 debugging, because they are intended for the use of programs (like
857 compilers) that compose assembler programs, not for your notice.
858 Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not
859 normally debug with them.
861 This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols
862 in the object file. Usually if you do this you also tell the linker
863 @code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
865 By default, a local label is any label beginning with @samp{L}, but each
866 target is allowed to redefine the local label prefix.
868 On the HPPA local labels begin with @samp{L$}.
872 @section Name the Object File: @code{-o}
875 @cindex naming object file
876 @cindex object file name
877 There is always one object file output when you run @code{@value{AS}}. By
878 default it has the name
881 @file{a.out} (or @file{b.out}, for Intel 960 targets only).
895 You use this option (which takes exactly one filename) to give the
896 object file a different name.
898 Whatever the object file is called, @code{@value{AS}} overwrites any
899 existing file of the same name.
902 @section Join Data and Text Sections: @code{-R}
905 @cindex data and text sections, joining
906 @cindex text and data sections, joining
907 @cindex joining text and data sections
908 @cindex merging text and data sections
909 @code{-R} tells @code{@value{AS}} to write the object file as if all
910 data-section data lives in the text section. This is only done at
911 the very last moment: your binary data are the same, but data
912 section parts are relocated differently. The data section part of
913 your object file is zero bytes long because all its bytes are
914 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
916 When you specify @code{-R} it would be possible to generate shorter
917 address displacements (because we do not have to cross between text and
918 data section). We refrain from doing this simply for compatibility with
919 older versions of @code{@value{AS}}. In future, @code{-R} may work this way.
922 When @code{@value{AS}} is configured for COFF output,
923 this option is only useful if you use sections named @samp{.text} and
928 @code{-R} is not supported for any of the HPPA targets. Using
929 @code{-R} generates a warning from @code{@value{AS}}.
933 @section Display Statistics about Assembly: @code{--statistics}
936 @cindex statistics, about assembly
937 @cindex time, total for assembly
938 @cindex space used, maximum for assembly
939 Use @samp{--statistics} to display two statistics about the resources used by
940 @code{@value{AS}}: the maximum amount of space allocated during the assembly
941 (in bytes), and the total execution time taken for the assembly (in @sc{cpu}
945 @section Announce Version: @code{-v}
949 @cindex @code{@value{AS}} version
950 @cindex version of @code{@value{AS}}
951 You can find out what version of as is running by including the
952 option @samp{-v} (which you can also spell as @samp{-version}) on the
956 @section Suppress Warnings: @code{-W}
959 @cindex suppressing warnings
960 @cindex warnings, suppressing
961 @code{@value{AS}} should never give a warning or error message when
962 assembling compiler output. But programs written by people often
963 cause @code{@value{AS}} to give a warning that a particular assumption was
964 made. All such warnings are directed to the standard error file.
965 If you use this option, no warnings are issued. This option only
966 affects the warning messages: it does not change any particular of how
967 @code{@value{AS}} assembles your file. Errors, which stop the assembly, are
971 @section Generate Object File in Spite of Errors: @code{-Z}
972 @cindex object file, after errors
973 @cindex errors, continuing after
974 After an error message, @code{@value{AS}} normally produces no output. If for
975 some reason you are interested in object file output even after
976 @code{@value{AS}} gives an error message on your program, use the @samp{-Z}
977 option. If there are any errors, @code{@value{AS}} continues anyways, and
978 writes an object file after a final warning message of the form @samp{@var{n}
979 errors, @var{m} warnings, generating bad object file.}
984 @cindex machine-independent syntax
985 @cindex syntax, machine-independent
986 This chapter describes the machine-independent syntax allowed in a
987 source file. @code{@value{AS}} syntax is similar to what many other
988 assemblers use; it is inspired by the BSD 4.2
993 assembler, except that @code{@value{AS}} does not assemble Vax bit-fields.
997 * Preprocessing:: Preprocessing
998 * Whitespace:: Whitespace
999 * Comments:: Comments
1000 * Symbol Intro:: Symbols
1001 * Statements:: Statements
1002 * Constants:: Constants
1006 @section Preprocessing
1008 @cindex preprocessing
1009 The @code{@value{AS}} internal preprocessor:
1011 @cindex whitespace, removed by preprocessor
1013 adjusts and removes extra whitespace. It leaves one space or tab before
1014 the keywords on a line, and turns any other whitespace on the line into
1017 @cindex comments, removed by preprocessor
1019 removes all comments, replacing them with a single space, or an
1020 appropriate number of newlines.
1022 @cindex constants, converted by preprocessor
1024 converts character constants into the appropriate numeric values.
1027 Note that it does not do macro processing, include file handling, or
1028 anything else you may get from your C compiler's preprocessor. You can
1029 do include file processing with the @code{.include} directive
1030 (@pxref{Include,,@code{.include}}). Other ``CPP'' style preprocessing
1031 can be done with the @sc{GNU} C compiler, by giving the input file a
1032 @samp{.S} suffix; see the compiler documentation for details.
1034 Excess whitespace, comments, and character constants
1035 cannot be used in the portions of the input text that are not
1038 @cindex turning preprocessing on and off
1039 @cindex preprocessing, turning on and off
1042 If the first line of an input file is @code{#NO_APP} or if you use the
1043 @samp{-f} option, whitespace and comments are not removed from the input file.
1044 Within an input file, you can ask for whitespace and comment removal in
1045 specific portions of the by putting a line that says @code{#APP} before the
1046 text that may contain whitespace or comments, and putting a line that says
1047 @code{#NO_APP} after this text. This feature is mainly intend to support
1048 @code{asm} statements in compilers whose output is otherwise free of comments
1055 @dfn{Whitespace} is one or more blanks or tabs, in any order.
1056 Whitespace is used to separate symbols, and to make programs neater for
1057 people to read. Unless within character constants
1058 (@pxref{Characters,,Character Constants}), any whitespace means the same
1059 as exactly one space.
1065 There are two ways of rendering comments to @code{@value{AS}}. In both
1066 cases the comment is equivalent to one space.
1068 Anything from @samp{/*} through the next @samp{*/} is a comment.
1069 This means you may not nest these comments.
1073 The only way to include a newline ('\n') in a comment
1074 is to use this sort of comment.
1077 /* This sort of comment does not nest. */
1080 @cindex line comment character
1081 Anything from the @dfn{line comment} character to the next newline
1082 is considered a comment and is ignored. The line comment character is
1084 @samp{#} on the Vax;
1087 @samp{#} on the i960;
1090 @samp{!} on the SPARC;
1093 @samp{|} on the 680x0;
1096 @samp{;} for the AMD 29K family;
1099 @samp{;} for the H8/300 family;
1102 @samp{!} for the H8/500 family;
1105 @samp{;} for the HPPA;
1108 @samp{!} for the Hitachi SH;
1111 @samp{!} for the Z8000;
1113 see @ref{Machine Dependencies}. @refill
1114 @c FIXME What about i386, m88k, i860?
1117 On some machines there are two different line comment characters. One
1118 character only begins a comment if it is the first non-whitespace character on
1119 a line, while the other always begins a comment.
1123 @cindex lines starting with @code{#}
1124 @cindex logical line numbers
1125 To be compatible with past assemblers, a special interpretation is given to
1126 lines that begin with @samp{#}. Following the @samp{#} should be an absolute
1127 expression (@pxref{Expressions}): the logical line number of the @emph{next}
1128 line. Then a string (@xref{Strings}.) is allowed: if present it is a new
1129 logical file name. The rest of the line, if any, should be whitespace.
1131 If the first non-whitespace characters on the line are not numeric,
1132 the line is ignored. (Just like a comment.)
1134 # This is an ordinary comment.
1135 # 42-6 "new_file_name" # New logical file name
1136 # This is logical line # 36.
1138 This feature is deprecated, and may disappear from future versions
1139 of @code{@value{AS}}.
1144 @cindex characters used in symbols
1145 @ifclear SPECIAL-SYMS
1146 A @dfn{symbol} is one or more characters chosen from the set of all
1147 letters (both upper and lower case), digits and the three characters
1153 A @dfn{symbol} is one or more characters chosen from the set of all
1154 letters (both upper and lower case), digits and the three characters
1155 @samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in
1161 On most machines, you can also use @code{$} in symbol names; exceptions
1162 are noted in @ref{Machine Dependencies}.
1164 No symbol may begin with a digit. Case is significant.
1165 There is no length limit: all characters are significant. Symbols are
1166 delimited by characters not in that set, or by the beginning of a file
1167 (since the source program must end with a newline, the end of a file is
1168 not a possible symbol delimiter). @xref{Symbols}.
1169 @cindex length of symbols
1174 @cindex statements, structure of
1175 @cindex line separator character
1176 @cindex statement separator character
1178 @ifclear abnormal-separator
1179 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
1180 semicolon (@samp{;}). The newline or semicolon is considered part of
1181 the preceding statement. Newlines and semicolons within character
1182 constants are an exception: they do not end statements.
1184 @ifset abnormal-separator
1186 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
1187 sign (@samp{@@}). The newline or at sign is considered part of the
1188 preceding statement. Newlines and at signs within character constants
1189 are an exception: they do not end statements.
1192 A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation
1193 point (@samp{!}). The newline or exclamation point is considered part of the
1194 preceding statement. Newlines and exclamation points within character
1195 constants are an exception: they do not end statements.
1198 A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
1199 H8/300) a dollar sign (@samp{$}); or (for the
1202 (@samp{;}). The newline or separator character is considered part of
1203 the preceding statement. Newlines and separators within character
1204 constants are an exception: they do not end statements.
1209 A @dfn{statement} ends at a newline character (@samp{\n}) or line
1210 separator character. (The line separator is usually @samp{;}, unless
1211 this conflicts with the comment character; @pxref{Machine Dependencies}.) The
1212 newline or separator character is considered part of the preceding
1213 statement. Newlines and separators within character constants are an
1214 exception: they do not end statements.
1217 @cindex newline, required at file end
1218 @cindex EOF, newline must precede
1219 It is an error to end any statement with end-of-file: the last
1220 character of any input file should be a newline.@refill
1222 @cindex continuing statements
1223 @cindex multi-line statements
1224 @cindex statement on multiple lines
1225 You may write a statement on more than one line if you put a
1226 backslash (@kbd{\}) immediately in front of any newlines within the
1227 statement. When @code{@value{AS}} reads a backslashed newline both
1228 characters are ignored. You can even put backslashed newlines in
1229 the middle of symbol names without changing the meaning of your
1232 An empty statement is allowed, and may include whitespace. It is ignored.
1234 @cindex instructions and directives
1235 @cindex directives and instructions
1236 @c "key symbol" is not used elsewhere in the document; seems pedantic to
1237 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
1239 A statement begins with zero or more labels, optionally followed by a
1240 key symbol which determines what kind of statement it is. The key
1241 symbol determines the syntax of the rest of the statement. If the
1242 symbol begins with a dot @samp{.} then the statement is an assembler
1243 directive: typically valid for any computer. If the symbol begins with
1244 a letter the statement is an assembly language @dfn{instruction}: it
1245 assembles into a machine language instruction.
1247 Different versions of @code{@value{AS}} for different computers
1248 recognize different instructions. In fact, the same symbol may
1249 represent a different instruction in a different computer's assembly
1253 @cindex @code{:} (label)
1254 @cindex label (@code{:})
1255 A label is a symbol immediately followed by a colon (@code{:}).
1256 Whitespace before a label or after a colon is permitted, but you may not
1257 have whitespace between a label's symbol and its colon. @xref{Labels}.
1260 For HPPA targets, labels need not be immediately followed by a colon, but
1261 the definition of a label must begin in column zero. This also implies that
1262 only one label may be defined on each line.
1266 label: .directive followed by something
1267 another_label: # This is an empty statement.
1268 instruction operand_1, operand_2, @dots{}
1275 A constant is a number, written so that its value is known by
1276 inspection, without knowing any context. Like this:
1279 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
1280 .ascii "Ring the bell\7" # A string constant.
1281 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
1282 .float 0f-314159265358979323846264338327\
1283 95028841971.693993751E-40 # - pi, a flonum.
1288 * Characters:: Character Constants
1289 * Numbers:: Number Constants
1293 @subsection Character Constants
1295 @cindex character constants
1296 @cindex constants, character
1297 There are two kinds of character constants. A @dfn{character} stands
1298 for one character in one byte and its value may be used in
1299 numeric expressions. String constants (properly called string
1300 @emph{literals}) are potentially many bytes and their values may not be
1301 used in arithmetic expressions.
1305 * Chars:: Characters
1309 @subsubsection Strings
1311 @cindex string constants
1312 @cindex constants, string
1313 A @dfn{string} is written between double-quotes. It may contain
1314 double-quotes or null characters. The way to get special characters
1315 into a string is to @dfn{escape} these characters: precede them with
1316 a backslash @samp{\} character. For example @samp{\\} represents
1317 one backslash: the first @code{\} is an escape which tells
1318 @code{@value{AS}} to interpret the second character literally as a backslash
1319 (which prevents @code{@value{AS}} from recognizing the second @code{\} as an
1320 escape character). The complete list of escapes follows.
1322 @cindex escape codes, character
1323 @cindex character escape codes
1326 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1329 @cindex @code{\b} (backspace character)
1330 @cindex backspace (@code{\b})
1331 Mnemonic for backspace; for ASCII this is octal code 010.
1334 @c Mnemonic for EOText; for ASCII this is octal code 004.
1337 @cindex @code{\f} (formfeed character)
1338 @cindex formfeed (@code{\f})
1339 Mnemonic for FormFeed; for ASCII this is octal code 014.
1342 @cindex @code{\n} (newline character)
1343 @cindex newline (@code{\n})
1344 Mnemonic for newline; for ASCII this is octal code 012.
1347 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1350 @cindex @code{\r} (carriage return character)
1351 @cindex carriage return (@code{\r})
1352 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1355 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1356 @c other assemblers.
1359 @cindex @code{\t} (tab)
1360 @cindex tab (@code{\t})
1361 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1364 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1365 @c @item \x @var{digit} @var{digit} @var{digit}
1366 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1368 @item \ @var{digit} @var{digit} @var{digit}
1369 @cindex @code{\@var{ddd}} (octal character code)
1370 @cindex octal character code (@code{\@var{ddd}})
1371 An octal character code. The numeric code is 3 octal digits.
1372 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1373 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1376 @item \@code{x} @var{hex-digit} @var{hex-digit}
1377 @cindex @code{\@var{xdd}} (hex character code)
1378 @cindex hex character code (@code{\@var{xdd}})
1379 A hex character code. The numeric code is 2 hexadecimal digits. Either
1380 upper or lower case @code{x} works.
1384 @cindex @code{\\} (@samp{\} character)
1385 @cindex backslash (@code{\\})
1386 Represents one @samp{\} character.
1389 @c Represents one @samp{'} (accent acute) character.
1390 @c This is needed in single character literals
1391 @c (@xref{Characters,,Character Constants}.) to represent
1395 @cindex @code{\"} (doublequote character)
1396 @cindex doublequote (@code{\"})
1397 Represents one @samp{"} character. Needed in strings to represent
1398 this character, because an unescaped @samp{"} would end the string.
1400 @item \ @var{anything-else}
1401 Any other character when escaped by @kbd{\} gives a warning, but
1402 assemble as if the @samp{\} was not present. The idea is that if
1403 you used an escape sequence you clearly didn't want the literal
1404 interpretation of the following character. However @code{@value{AS}} has no
1405 other interpretation, so @code{@value{AS}} knows it is giving you the wrong
1406 code and warns you of the fact.
1409 Which characters are escapable, and what those escapes represent,
1410 varies widely among assemblers. The current set is what we think
1411 the BSD 4.2 assembler recognizes, and is a subset of what most C
1412 compilers recognize. If you are in doubt, do not use an escape
1416 @subsubsection Characters
1418 @cindex single character constant
1419 @cindex character, single
1420 @cindex constant, single character
1421 A single character may be written as a single quote immediately
1422 followed by that character. The same escapes apply to characters as
1423 to strings. So if you want to write the character backslash, you
1424 must write @kbd{'\\} where the first @code{\} escapes the second
1425 @code{\}. As you can see, the quote is an acute accent, not a
1426 grave accent. A newline
1428 @ifclear abnormal-separator
1429 (or semicolon @samp{;})
1431 @ifset abnormal-separator
1433 (or at sign @samp{@@})
1436 (or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
1442 immediately following an acute accent is taken as a literal character
1443 and does not count as the end of a statement. The value of a character
1444 constant in a numeric expression is the machine's byte-wide code for
1445 that character. @code{@value{AS}} assumes your character code is ASCII:
1446 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1449 @subsection Number Constants
1451 @cindex constants, number
1452 @cindex number constants
1453 @code{@value{AS}} distinguishes three kinds of numbers according to how they
1454 are stored in the target machine. @emph{Integers} are numbers that
1455 would fit into an @code{int} in the C language. @emph{Bignums} are
1456 integers, but they are stored in more than 32 bits. @emph{Flonums}
1457 are floating point numbers, described below.
1460 * Integers:: Integers
1465 * Bit Fields:: Bit Fields
1471 @subsubsection Integers
1473 @cindex constants, integer
1475 @cindex binary integers
1476 @cindex integers, binary
1477 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1478 the binary digits @samp{01}.
1480 @cindex octal integers
1481 @cindex integers, octal
1482 An octal integer is @samp{0} followed by zero or more of the octal
1483 digits (@samp{01234567}).
1485 @cindex decimal integers
1486 @cindex integers, decimal
1487 A decimal integer starts with a non-zero digit followed by zero or
1488 more digits (@samp{0123456789}).
1490 @cindex hexadecimal integers
1491 @cindex integers, hexadecimal
1492 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1493 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1495 Integers have the usual values. To denote a negative integer, use
1496 the prefix operator @samp{-} discussed under expressions
1497 (@pxref{Prefix Ops,,Prefix Operators}).
1500 @subsubsection Bignums
1503 @cindex constants, bignum
1504 A @dfn{bignum} has the same syntax and semantics as an integer
1505 except that the number (or its negative) takes more than 32 bits to
1506 represent in binary. The distinction is made because in some places
1507 integers are permitted while bignums are not.
1510 @subsubsection Flonums
1512 @cindex floating point numbers
1513 @cindex constants, floating point
1515 @cindex precision, floating point
1516 A @dfn{flonum} represents a floating point number. The translation is
1517 indirect: a decimal floating point number from the text is converted by
1518 @code{@value{AS}} to a generic binary floating point number of more than
1519 sufficient precision. This generic floating point number is converted
1520 to a particular computer's floating point format (or formats) by a
1521 portion of @code{@value{AS}} specialized to that computer.
1523 A flonum is written by writing (in order)
1528 (@samp{0} is optional on the HPPA.)
1532 A letter, to tell @code{@value{AS}} the rest of the number is a flonum.
1534 @kbd{e} is recommended. Case is not important.
1536 @c FIXME: verify if flonum syntax really this vague for most cases
1537 (Any otherwise illegal letter works here, but that might be changed. Vax BSD
1538 4.2 assembler seems to allow any of @samp{defghDEFGH}.)
1541 On the H8/300, H8/500,
1543 and AMD 29K architectures, the letter must be
1544 one of the letters @samp{DFPRSX} (in upper or lower case).
1546 On the Intel 960 architecture, the letter must be
1547 one of the letters @samp{DFT} (in upper or lower case).
1549 On the HPPA architecture, the letter must be @samp{E} (upper case only).
1553 One of the letters @samp{DFPRSX} (in upper or lower case).
1556 One of the letters @samp{DFPRSX} (in upper or lower case).
1559 One of the letters @samp{DFT} (in upper or lower case).
1562 The letter @samp{E} (upper case only).
1567 An optional sign: either @samp{+} or @samp{-}.
1570 An optional @dfn{integer part}: zero or more decimal digits.
1573 An optional @dfn{fractional part}: @samp{.} followed by zero
1574 or more decimal digits.
1577 An optional exponent, consisting of:
1581 An @samp{E} or @samp{e}.
1582 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1583 @c principle this can perfectly well be different on different targets.
1585 Optional sign: either @samp{+} or @samp{-}.
1587 One or more decimal digits.
1592 At least one of the integer part or the fractional part must be
1593 present. The floating point number has the usual base-10 value.
1595 @code{@value{AS}} does all processing using integers. Flonums are computed
1596 independently of any floating point hardware in the computer running
1601 @c Bit fields are written as a general facility but are also controlled
1602 @c by a conditional-compilation flag---which is as of now (21mar91)
1603 @c turned on only by the i960 config of GAS.
1605 @subsubsection Bit Fields
1608 @cindex constants, bit field
1609 You can also define numeric constants as @dfn{bit fields}.
1610 specify two numbers separated by a colon---
1612 @var{mask}:@var{value}
1615 @code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
1618 The resulting number is then packed
1620 @c this conditional paren in case bit fields turned on elsewhere than 960
1621 (in host-dependent byte order)
1623 into a field whose width depends on which assembler directive has the
1624 bit-field as its argument. Overflow (a result from the bitwise and
1625 requiring more binary digits to represent) is not an error; instead,
1626 more constants are generated, of the specified width, beginning with the
1627 least significant digits.@refill
1629 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1630 @code{.short}, and @code{.word} accept bit-field arguments.
1635 @chapter Sections and Relocation
1640 * Secs Background:: Background
1641 * Ld Sections:: @value{LD} Sections
1642 * As Sections:: @value{AS} Internal Sections
1643 * Sub-Sections:: Sub-Sections
1647 @node Secs Background
1650 Roughly, a section is a range of addresses, with no gaps; all data
1651 ``in'' those addresses is treated the same for some particular purpose.
1652 For example there may be a ``read only'' section.
1654 @cindex linker, and assembler
1655 @cindex assembler, and linker
1656 The linker @code{@value{LD}} reads many object files (partial programs) and
1657 combines their contents to form a runnable program. When @code{@value{AS}}
1658 emits an object file, the partial program is assumed to start at address 0.
1659 @code{@value{LD}} assigns the final addresses for the partial program, so that
1660 different partial programs do not overlap. This is actually an
1661 oversimplification, but it suffices to explain how @code{@value{AS}} uses
1664 @code{@value{LD}} moves blocks of bytes of your program to their run-time
1665 addresses. These blocks slide to their run-time addresses as rigid
1666 units; their length does not change and neither does the order of bytes
1667 within them. Such a rigid unit is called a @emph{section}. Assigning
1668 run-time addresses to sections is called @dfn{relocation}. It includes
1669 the task of adjusting mentions of object-file addresses so they refer to
1670 the proper run-time addresses.
1672 For the H8/300 and H8/500,
1673 and for the Hitachi SH,
1674 @code{@value{AS}} pads sections if needed to
1675 ensure they end on a word (sixteen bit) boundary.
1678 @cindex standard @code{@value{AS}} sections
1679 An object file written by @code{@value{AS}} has at least three sections, any
1680 of which may be empty. These are named @dfn{text}, @dfn{data} and
1685 When it generates COFF output,
1687 @code{@value{AS}} can also generate whatever other named sections you specify
1688 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1689 If you do not use any directives that place output in the @samp{.text}
1690 or @samp{.data} sections, these sections still exist, but are empty.
1695 When @code{@value{AS}} generates SOM or ELF output for the HPPA,
1697 @code{@value{AS}} can also generate whatever other named sections you
1698 specify using the @samp{.space} and @samp{.subspace} directives. See
1699 @cite{HP9000 Series 800 Assembly Language Reference Manual}
1700 (HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
1701 assembler directives.
1704 Additionally, @code{@value{AS}} uses different names for the standard
1705 text, data, and bss sections when generating SOM output. Program text
1706 is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
1707 BSS into @samp{$BSS$}.
1711 Within the object file, the text section starts at address @code{0}, the
1712 data section follows, and the bss section follows the data section.
1715 When generating either SOM or ELF output files on the HPPA, the text
1716 section starts at address @code{0}, the data section at address
1717 @code{0x4000000}, and the bss section follows the data section.
1720 To let @code{@value{LD}} know which data changes when the sections are
1721 relocated, and how to change that data, @code{@value{AS}} also writes to the
1722 object file details of the relocation needed. To perform relocation
1723 @code{@value{LD}} must know, each time an address in the object
1727 Where in the object file is the beginning of this reference to
1730 How long (in bytes) is this reference?
1732 Which section does the address refer to? What is the numeric value of
1734 (@var{address}) @minus{} (@var{start-address of section})?
1737 Is the reference to an address ``Program-Counter relative''?
1740 @cindex addresses, format of
1741 @cindex section-relative addressing
1742 In fact, every address @code{@value{AS}} ever uses is expressed as
1744 (@var{section}) + (@var{offset into section})
1747 Further, every expression @code{@value{AS}} computes is of this section-relative
1748 nature. @dfn{Absolute expression} means an expression with section
1749 ``absolute'' (@pxref{Ld Sections}). A @dfn{pass1 expression} means
1750 an expression with section ``pass1'' (@pxref{As Sections,,@value{AS}
1751 Internal Sections}). In this manual we use the notation @{@var{secname}
1752 @var{N}@} to mean ``offset @var{N} into section @var{secname}''.
1754 Apart from text, data and bss sections you need to know about the
1755 @dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
1756 addresses in the absolute section remain unchanged. For example, address
1757 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
1758 @code{@value{LD}}. Although the linker never arranges two partial programs'
1759 data sections with overlapping addresses after linking, @emph{by definition}
1760 their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one
1761 part of a program is always the same address when the program is running as
1762 address @code{@{absolute@ 239@}} in any other part of the program.
1764 The idea of sections is extended to the @dfn{undefined} section. Any
1765 address whose section is unknown at assembly time is by definition
1766 rendered @{undefined @var{U}@}---where @var{U} is filled in later.
1767 Since numbers are always defined, the only way to generate an undefined
1768 address is to mention an undefined symbol. A reference to a named
1769 common block would be such a symbol: its value is unknown at assembly
1770 time so it has section @emph{undefined}.
1772 By analogy the word @emph{section} is used to describe groups of sections in
1773 the linked program. @code{@value{LD}} puts all partial programs' text
1774 sections in contiguous addresses in the linked program. It is
1775 customary to refer to the @emph{text section} of a program, meaning all
1776 the addresses of all partial programs' text sections. Likewise for
1777 data and bss sections.
1779 Some sections are manipulated by @code{@value{LD}}; others are invented for
1780 use of @code{@value{AS}} and have no meaning except during assembly.
1783 @section @value{LD} Sections
1784 @code{@value{LD}} deals with just four kinds of sections, summarized below.
1789 @cindex named sections
1790 @cindex sections, named
1791 @item named sections
1794 @cindex text section
1795 @cindex data section
1799 These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as
1800 separate but equal sections. Anything you can say of one section is
1803 When the program is running, however, it is
1804 customary for the text section to be unalterable. The
1805 text section is often shared among processes: it contains
1806 instructions, constants and the like. The data section of a running
1807 program is usually alterable: for example, C variables would be stored
1808 in the data section.
1813 This section contains zeroed bytes when your program begins running. It
1814 is used to hold unitialized variables or common storage. The length of
1815 each partial program's bss section is important, but because it starts
1816 out containing zeroed bytes there is no need to store explicit zero
1817 bytes in the object file. The bss section was invented to eliminate
1818 those explicit zeros from object files.
1820 @cindex absolute section
1821 @item absolute section
1822 Address 0 of this section is always ``relocated'' to runtime address 0.
1823 This is useful if you want to refer to an address that @code{@value{LD}} must
1824 not change when relocating. In this sense we speak of absolute
1825 addresses being ``unrelocatable'': they do not change during relocation.
1827 @cindex undefined section
1828 @item undefined section
1829 This ``section'' is a catch-all for address references to objects not in
1830 the preceding sections.
1831 @c FIXME: ref to some other doc on obj-file formats could go here.
1834 @cindex relocation example
1835 An idealized example of three relocatable sections follows.
1837 The example uses the traditional section names @samp{.text} and @samp{.data}.
1839 Memory addresses are on the horizontal axis.
1843 @c END TEXI2ROFF-KILL
1846 partial program # 1: |ttttt|dddd|00|
1853 partial program # 2: |TTT|DDD|000|
1856 +--+---+-----+--+----+---+-----+~~
1857 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1858 +--+---+-----+--+----+---+-----+~~
1860 addresses: 0 @dots{}
1864 @c FIXME make sure no page breaks inside figure!!
1867 \line{\it Partial program \#1: \hfil}
1868 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1869 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1871 \line{\it Partial program \#2: \hfil}
1872 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1873 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1875 \line{\it linked program: \hfil}
1876 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1877 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1878 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1879 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1881 \line{\it addresses: \hfil}
1885 @c END TEXI2ROFF-KILL
1888 @section @value{AS} Internal Sections
1890 @cindex internal @code{@value{AS}} sections
1891 @cindex sections in messages, internal
1892 These sections are meant only for the internal use of @code{@value{AS}}. They
1893 have no meaning at run-time. You do not really need to know about these
1894 sections for most purposes; but they can be mentioned in @code{@value{AS}}
1895 warning messages, so it might be helpful to have an idea of their
1896 meanings to @code{@value{AS}}. These sections are used to permit the
1897 value of every expression in your assembly language program to be a
1898 section-relative address.
1901 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
1902 @cindex assembler internal logic error
1903 An internal assembler logic error has been found. This means there is a
1904 bug in the assembler.
1907 @cindex expr (internal section)
1908 The assembler stores complex expression internally as combinations of
1909 symbols. When it needs to represent an expression as a symbol, it puts
1910 it in the expr section.
1912 @c FIXME item transfer[t] vector preload
1913 @c FIXME item transfer[t] vector postload
1914 @c FIXME item register
1918 @section Sub-Sections
1920 @cindex numbered subsections
1921 @cindex grouping data
1927 fall into two sections: text and data.
1929 You may have separate groups of
1931 data in named sections
1935 data in named sections
1941 that you want to end up near to each other in the object file, even though they
1942 are not contiguous in the assembler source. @code{@value{AS}} allows you to
1943 use @dfn{subsections} for this purpose. Within each section, there can be
1944 numbered subsections with values from 0 to 8192. Objects assembled into the
1945 same subsection go into the object file together with other objects in the same
1946 subsection. For example, a compiler might want to store constants in the text
1947 section, but might not want to have them interspersed with the program being
1948 assembled. In this case, the compiler could issue a @samp{.text 0} before each
1949 section of code being output, and a @samp{.text 1} before each group of
1950 constants being output.
1952 Subsections are optional. If you do not use subsections, everything
1953 goes in subsection number zero.
1956 Each subsection is zero-padded up to a multiple of four bytes.
1957 (Subsections may be padded a different amount on different flavors
1958 of @code{@value{AS}}.)
1962 On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
1963 boundary (two bytes).
1964 The same is true on the Hitachi SH.
1967 @c FIXME section padding (alignment)?
1968 @c Rich Pixley says padding here depends on target obj code format; that
1969 @c doesn't seem particularly useful to say without further elaboration,
1970 @c so for now I say nothing about it. If this is a generic BFD issue,
1971 @c these paragraphs might need to vanish from this manual, and be
1972 @c discussed in BFD chapter of binutils (or some such).
1975 On the AMD 29K family, no particular padding is added to section or
1976 subsection sizes; @value{AS} forces no alignment on this platform.
1980 Subsections appear in your object file in numeric order, lowest numbered
1981 to highest. (All this to be compatible with other people's assemblers.)
1982 The object file contains no representation of subsections; @code{@value{LD}} and
1983 other programs that manipulate object files see no trace of them.
1984 They just see all your text subsections as a text section, and all your
1985 data subsections as a data section.
1987 To specify which subsection you want subsequent statements assembled
1988 into, use a numeric argument to specify it, in a @samp{.text
1989 @var{expression}} or a @samp{.data @var{expression}} statement.
1992 When generating COFF output, you
1997 can also use an extra subsection
1998 argument with arbitrary named sections: @samp{.section @var{name},
2001 @var{Expression} should be an absolute expression.
2002 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
2003 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
2004 begins in @code{text 0}. For instance:
2006 .text 0 # The default subsection is text 0 anyway.
2007 .ascii "This lives in the first text subsection. *"
2009 .ascii "But this lives in the second text subsection."
2011 .ascii "This lives in the data section,"
2012 .ascii "in the first data subsection."
2014 .ascii "This lives in the first text section,"
2015 .ascii "immediately following the asterisk (*)."
2018 Each section has a @dfn{location counter} incremented by one for every byte
2019 assembled into that section. Because subsections are merely a convenience
2020 restricted to @code{@value{AS}} there is no concept of a subsection location
2021 counter. There is no way to directly manipulate a location counter---but the
2022 @code{.align} directive changes it, and any label definition captures its
2023 current value. The location counter of the section where statements are being
2024 assembled is said to be the @dfn{active} location counter.
2027 @section bss Section
2030 @cindex common variable storage
2031 The bss section is used for local common variable storage.
2032 You may allocate address space in the bss section, but you may
2033 not dictate data to load into it before your program executes. When
2034 your program starts running, all the contents of the bss
2035 section are zeroed bytes.
2037 Addresses in the bss section are allocated with special directives; you
2038 may not assemble anything directly into the bss section. Hence there
2039 are no bss subsections. @xref{Comm,,@code{.comm}},
2040 @pxref{Lcomm,,@code{.lcomm}}.
2046 Symbols are a central concept: the programmer uses symbols to name
2047 things, the linker uses symbols to link, and the debugger uses symbols
2051 @cindex debuggers, and symbol order
2052 @emph{Warning:} @code{@value{AS}} does not place symbols in the object file in
2053 the same order they were declared. This may break some debuggers.
2058 * Setting Symbols:: Giving Symbols Other Values
2059 * Symbol Names:: Symbol Names
2060 * Dot:: The Special Dot Symbol
2061 * Symbol Attributes:: Symbol Attributes
2068 A @dfn{label} is written as a symbol immediately followed by a colon
2069 @samp{:}. The symbol then represents the current value of the
2070 active location counter, and is, for example, a suitable instruction
2071 operand. You are warned if you use the same symbol to represent two
2072 different locations: the first definition overrides any other
2076 On the HPPA, a label need not be immediately followed by a colon,
2077 but instead must start in column zero. Only one label may be
2078 defined on a single line.
2081 @node Setting Symbols
2082 @section Giving Symbols Other Values
2084 @cindex assigning values to symbols
2085 @cindex symbol values, assigning
2086 A symbol can be given an arbitrary value by writing a symbol, followed
2087 by an equals sign @samp{=}, followed by an expression
2088 (@pxref{Expressions}). This is equivalent to using the @code{.set}
2089 directive. @xref{Set,,@code{.set}}.
2092 @section Symbol Names
2094 @cindex symbol names
2095 @cindex names, symbol
2096 @ifclear SPECIAL-SYMS
2097 Symbol names begin with a letter or with one of @samp{._}. On most
2098 machines, you can also use @code{$} in symbol names; exceptions are
2099 noted in @ref{Machine Dependencies}. That character may be followed by any
2100 string of digits, letters, dollar signs (unless otherwise noted in
2101 @ref{Machine Dependencies}), and underscores.
2104 For the AMD 29K family, @samp{?} is also allowed in the
2105 body of a symbol name, though not at its beginning.
2110 Symbol names begin with a letter or with one of @samp{._}. On the
2112 H8/500, you can also use @code{$} in symbol names. That character may
2113 be followed by any string of digits, letters, dollar signs (save on the
2114 H8/300), and underscores.
2118 Case of letters is significant: @code{foo} is a different symbol name
2121 Each symbol has exactly one name. Each name in an assembly language program
2122 refers to exactly one symbol. You may use that symbol name any number of times
2125 @subheading Local Symbol Names
2127 @cindex local symbol names
2128 @cindex symbol names, local
2129 @cindex temporary symbol names
2130 @cindex symbol names, temporary
2131 Local symbols help compilers and programmers use names temporarily.
2132 There are ten local symbol names, which are re-used throughout the
2133 program. You may refer to them using the names @samp{0} @samp{1}
2134 @dots{} @samp{9}. To define a local symbol, write a label of the form
2135 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
2136 recent previous definition of that symbol write @samp{@b{N}b}, using the
2137 same digit as when you defined the label. To refer to the next
2138 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
2139 a choice of 10 forward references. The @samp{b} stands for
2140 ``backwards'' and the @samp{f} stands for ``forwards''.
2142 Local symbols are not emitted by the current GNU C compiler.
2144 There is no restriction on how you can use these labels, but
2145 remember that at any point in the assembly you can refer to at most
2146 10 prior local labels and to at most 10 forward local labels.
2148 Local symbol names are only a notation device. They are immediately
2149 transformed into more conventional symbol names before the assembler
2150 uses them. The symbol names stored in the symbol table, appearing in
2151 error messages and optionally emitted to the object file have these
2156 All local labels begin with @samp{L}. Normally both @code{@value{AS}} and
2157 @code{@value{LD}} forget symbols that start with @samp{L}. These labels are
2158 used for symbols you are never intended to see. If you use the
2159 @samp{-L} option then @code{@value{AS}} retains these symbols in the
2160 object file. If you also instruct @code{@value{LD}} to retain these symbols,
2161 you may use them in debugging.
2164 If the label is written @samp{0:} then the digit is @samp{0}.
2165 If the label is written @samp{1:} then the digit is @samp{1}.
2166 And so on up through @samp{9:}.
2169 This unusual character is included so you do not accidentally invent
2170 a symbol of the same name. The character has ASCII value
2173 @item @emph{ordinal number}
2174 This is a serial number to keep the labels distinct. The first
2175 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
2176 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
2180 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
2181 @code{3:} is named @code{L3@ctrl{A}44}.
2184 @section The Special Dot Symbol
2186 @cindex dot (symbol)
2187 @cindex @code{.} (symbol)
2188 @cindex current address
2189 @cindex location counter
2190 The special symbol @samp{.} refers to the current address that
2191 @code{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
2192 .long .} defines @code{melvin} to contain its own address.
2193 Assigning a value to @code{.} is treated the same as a @code{.org}
2194 directive. Thus, the expression @samp{.=.+4} is the same as saying
2195 @ifclear no-space-dir
2204 @node Symbol Attributes
2205 @section Symbol Attributes
2207 @cindex symbol attributes
2208 @cindex attributes, symbol
2209 Every symbol has, as well as its name, the attributes ``Value'' and
2210 ``Type''. Depending on output format, symbols can also have auxiliary
2213 The detailed definitions are in @file{a.out.h}.
2216 If you use a symbol without defining it, @code{@value{AS}} assumes zero for
2217 all these attributes, and probably won't warn you. This makes the
2218 symbol an externally defined symbol, which is generally what you
2222 * Symbol Value:: Value
2223 * Symbol Type:: Type
2226 * a.out Symbols:: Symbol Attributes: @code{a.out}
2230 * a.out Symbols:: Symbol Attributes: @code{a.out}
2233 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
2238 * COFF Symbols:: Symbol Attributes for COFF
2241 * SOM Symbols:: Symbol Attributes for SOM
2248 @cindex value of a symbol
2249 @cindex symbol value
2250 The value of a symbol is (usually) 32 bits. For a symbol which labels a
2251 location in the text, data, bss or absolute sections the value is the
2252 number of addresses from the start of that section to the label.
2253 Naturally for text, data and bss sections the value of a symbol changes
2254 as @code{@value{LD}} changes section base addresses during linking. Absolute
2255 symbols' values do not change during linking: that is why they are
2258 The value of an undefined symbol is treated in a special way. If it is
2259 0 then the symbol is not defined in this assembler source file, and
2260 @code{@value{LD}} tries to determine its value from other files linked into the
2261 same program. You make this kind of symbol simply by mentioning a symbol
2262 name without defining it. A non-zero value represents a @code{.comm}
2263 common declaration. The value is how much common storage to reserve, in
2264 bytes (addresses). The symbol refers to the first address of the
2270 @cindex type of a symbol
2272 The type attribute of a symbol contains relocation (section)
2273 information, any flag settings indicating that a symbol is external, and
2274 (optionally), other information for linkers and debuggers. The exact
2275 format depends on the object-code output format in use.
2280 @c The following avoids a "widow" subsection title. @group would be
2281 @c better if it were available outside examples.
2284 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
2286 @cindex @code{b.out} symbol attributes
2287 @cindex symbol attributes, @code{b.out}
2288 These symbol attributes appear only when @code{@value{AS}} is configured for
2289 one of the Berkeley-descended object output formats---@code{a.out} or
2295 @subsection Symbol Attributes: @code{a.out}
2297 @cindex @code{a.out} symbol attributes
2298 @cindex symbol attributes, @code{a.out}
2304 @subsection Symbol Attributes: @code{a.out}
2306 @cindex @code{a.out} symbol attributes
2307 @cindex symbol attributes, @code{a.out}
2311 * Symbol Desc:: Descriptor
2312 * Symbol Other:: Other
2316 @subsubsection Descriptor
2318 @cindex descriptor, of @code{a.out} symbol
2319 This is an arbitrary 16-bit value. You may establish a symbol's
2320 descriptor value by using a @code{.desc} statement
2321 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
2325 @subsubsection Other
2327 @cindex other attribute, of @code{a.out} symbol
2328 This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}.
2333 @subsection Symbol Attributes for COFF
2335 @cindex COFF symbol attributes
2336 @cindex symbol attributes, COFF
2338 The COFF format supports a multitude of auxiliary symbol attributes;
2339 like the primary symbol attributes, they are set between @code{.def} and
2340 @code{.endef} directives.
2342 @subsubsection Primary Attributes
2344 @cindex primary attributes, COFF symbols
2345 The symbol name is set with @code{.def}; the value and type,
2346 respectively, with @code{.val} and @code{.type}.
2348 @subsubsection Auxiliary Attributes
2350 @cindex auxiliary attributes, COFF symbols
2351 The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
2352 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2353 information for COFF.
2358 @subsection Symbol Attributes for SOM
2360 @cindex SOM symbol attributes
2361 @cindex symbol attributes, SOM
2363 The SOM format for the HPPA supports a multitude of symbol attributes set with
2364 the @code{.EXPORT} and @code{.IMPORT} directives.
2366 The attributes are described in @cite{HP9000 Series 800 Assembly
2367 Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
2368 @code{EXPORT} assembler directive documentation.
2372 @chapter Expressions
2376 @cindex numeric values
2377 An @dfn{expression} specifies an address or numeric value.
2378 Whitespace may precede and/or follow an expression.
2381 * Empty Exprs:: Empty Expressions
2382 * Integer Exprs:: Integer Expressions
2386 @section Empty Expressions
2388 @cindex empty expressions
2389 @cindex expressions, empty
2390 An empty expression has no value: it is just whitespace or null.
2391 Wherever an absolute expression is required, you may omit the
2392 expression, and @code{@value{AS}} assumes a value of (absolute) 0. This
2393 is compatible with other assemblers.
2396 @section Integer Expressions
2398 @cindex integer expressions
2399 @cindex expressions, integer
2400 An @dfn{integer expression} is one or more @emph{arguments} delimited
2401 by @emph{operators}.
2404 * Arguments:: Arguments
2405 * Operators:: Operators
2406 * Prefix Ops:: Prefix Operators
2407 * Infix Ops:: Infix Operators
2411 @subsection Arguments
2413 @cindex expression arguments
2414 @cindex arguments in expressions
2415 @cindex operands in expressions
2416 @cindex arithmetic operands
2417 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2418 contexts arguments are sometimes called ``arithmetic operands''. In
2419 this manual, to avoid confusing them with the ``instruction operands'' of
2420 the machine language, we use the term ``argument'' to refer to parts of
2421 expressions only, reserving the word ``operand'' to refer only to machine
2422 instruction operands.
2424 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2425 @var{section} is one of text, data, bss, absolute,
2426 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2429 Numbers are usually integers.
2431 A number can be a flonum or bignum. In this case, you are warned
2432 that only the low order 32 bits are used, and @code{@value{AS}} pretends
2433 these 32 bits are an integer. You may write integer-manipulating
2434 instructions that act on exotic constants, compatible with other
2437 @cindex subexpressions
2438 Subexpressions are a left parenthesis @samp{(} followed by an integer
2439 expression, followed by a right parenthesis @samp{)}; or a prefix
2440 operator followed by an argument.
2443 @subsection Operators
2445 @cindex operators, in expressions
2446 @cindex arithmetic functions
2447 @cindex functions, in expressions
2448 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2449 operators are followed by an argument. Infix operators appear
2450 between their arguments. Operators may be preceded and/or followed by
2454 @subsection Prefix Operator
2456 @cindex prefix operators
2457 @code{@value{AS}} has the following @dfn{prefix operators}. They each take
2458 one argument, which must be absolute.
2460 @c the tex/end tex stuff surrounding this small table is meant to make
2461 @c it align, on the printed page, with the similar table in the next
2462 @c section (which is inside an enumerate).
2464 \global\advance\leftskip by \itemindent
2469 @dfn{Negation}. Two's complement negation.
2471 @dfn{Complementation}. Bitwise not.
2475 \global\advance\leftskip by -\itemindent
2479 @subsection Infix Operators
2481 @cindex infix operators
2482 @cindex operators, permitted arguments
2483 @dfn{Infix operators} take two arguments, one on either side. Operators
2484 have precedence, but operations with equal precedence are performed left
2485 to right. Apart from @code{+} or @code{-}, both arguments must be
2486 absolute, and the result is absolute.
2489 @cindex operator precedence
2490 @cindex precedence of operators
2497 @dfn{Multiplication}.
2500 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2507 @dfn{Shift Left}. Same as the C operator @samp{<<}.
2511 @dfn{Shift Right}. Same as the C operator @samp{>>}.
2515 Intermediate precedence
2520 @dfn{Bitwise Inclusive Or}.
2526 @dfn{Bitwise Exclusive Or}.
2529 @dfn{Bitwise Or Not}.
2537 @cindex addition, permitted arguments
2538 @cindex plus, permitted arguments
2539 @cindex arguments for addition
2540 @dfn{Addition}. If either argument is absolute, the result
2541 has the section of the other argument.
2542 If either argument is pass1 or undefined, the result is pass1.
2543 Otherwise @code{+} is illegal.
2546 @cindex subtraction, permitted arguments
2547 @cindex minus, permitted arguments
2548 @cindex arguments for subtraction
2549 @dfn{Subtraction}. If the right argument is absolute, the
2550 result has the section of the left argument.
2551 If either argument is pass1 the result is pass1.
2552 If either argument is undefined the result is difference section.
2553 If both arguments are in the same section, the result is absolute---provided
2554 that section is one of text, data or bss.
2555 Otherwise subtraction is illegal.
2559 The sense of the rule for addition is that it's only meaningful to add
2560 the @emph{offsets} in an address; you can only have a defined section in
2561 one of the two arguments.
2563 Similarly, you can't subtract quantities from two different sections.
2566 @chapter Assembler Directives
2568 @cindex directives, machine independent
2569 @cindex pseudo-ops, machine independent
2570 @cindex machine independent directives
2571 All assembler directives have names that begin with a period (@samp{.}).
2572 The rest of the name is letters, usually in lower case.
2574 This chapter discusses directives that are available regardless of the
2575 target machine configuration for the GNU assembler.
2577 Some machine configurations provide additional directives.
2578 @xref{Machine Dependencies}.
2581 @ifset machine-directives
2582 @xref{Machine Dependencies} for additional directives.
2587 * Abort:: @code{.abort}
2589 * ABORT:: @code{.ABORT}
2592 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2593 * App-File:: @code{.app-file @var{string}}
2594 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2595 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2596 * Byte:: @code{.byte @var{expressions}}
2597 * Comm:: @code{.comm @var{symbol} , @var{length} }
2598 * Data:: @code{.data @var{subsection}}
2600 * Def:: @code{.def @var{name}}
2603 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2609 * Double:: @code{.double @var{flonums}}
2610 * Eject:: @code{.eject}
2611 * Else:: @code{.else}
2613 * Endef:: @code{.endef}
2616 * Endif:: @code{.endif}
2617 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2618 * Extern:: @code{.extern}
2619 @ifclear no-file-dir
2620 * File:: @code{.file @var{string}}
2623 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2624 * Float:: @code{.float @var{flonums}}
2625 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2626 * hword:: @code{.hword @var{expressions}}
2627 * Ident:: @code{.ident}
2628 * If:: @code{.if @var{absolute expression}}
2629 * Include:: @code{.include "@var{file}"}
2630 * Int:: @code{.int @var{expressions}}
2631 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2632 * Lflags:: @code{.lflags}
2633 @ifclear no-line-dir
2634 * Line:: @code{.line @var{line-number}}
2637 * Ln:: @code{.ln @var{line-number}}
2638 * List:: @code{.list}
2639 * Long:: @code{.long @var{expressions}}
2641 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2644 * Nolist:: @code{.nolist}
2645 * Octa:: @code{.octa @var{bignums}}
2646 * Org:: @code{.org @var{new-lc} , @var{fill}}
2647 * Psize:: @code{.psize @var{lines}, @var{columns}}
2648 * Quad:: @code{.quad @var{bignums}}
2649 * Sbttl:: @code{.sbttl "@var{subheading}"}
2651 * Scl:: @code{.scl @var{class}}
2654 * Section:: @code{.section @var{name}, @var{subsection}}
2657 * Set:: @code{.set @var{symbol}, @var{expression}}
2658 * Short:: @code{.short @var{expressions}}
2659 * Single:: @code{.single @var{flonums}}
2661 * Size:: @code{.size}
2664 * Space:: @code{.space @var{size} , @var{fill}}
2666 * Stab:: @code{.stabd, .stabn, .stabs}
2669 * String:: @code{.string "@var{str}"}
2671 * Tag:: @code{.tag @var{structname}}
2674 * Text:: @code{.text @var{subsection}}
2675 * Title:: @code{.title "@var{heading}"}
2677 * Type:: @code{.type @var{int}}
2678 * Val:: @code{.val @var{addr}}
2681 * Word:: @code{.word @var{expressions}}
2682 * Deprecated:: Deprecated Directives
2686 @section @code{.abort}
2688 @cindex @code{abort} directive
2689 @cindex stopping the assembly
2690 This directive stops the assembly immediately. It is for
2691 compatibility with other assemblers. The original idea was that the
2692 assembly language source would be piped into the assembler. If the sender
2693 of the source quit, it could use this directive tells @code{@value{AS}} to
2694 quit also. One day @code{.abort} will not be supported.
2698 @section @code{.ABORT}
2700 @cindex @code{ABORT} directive
2701 When producing COFF output, @code{@value{AS}} accepts this directive as a
2702 synonym for @samp{.abort}.
2705 When producing @code{b.out} output, @code{@value{AS}} accepts this directive,
2711 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2713 @cindex padding the location counter
2714 @cindex @code{align} directive
2715 Pad the location counter (in the current subsection) to a particular
2716 storage boundary. The first expression (which must be absolute) is the
2717 number of low-order zero bits the location counter must have after
2718 advancement. For example @samp{.align 3} advances the location
2719 counter until it a multiple of 8. If the location counter is already a
2720 multiple of 8, no change is needed.
2723 For the HPPA, the first expression (which must be absolute) is the
2724 alignment request in bytes. For example @samp{.align 8} advances
2725 the location counter until it is a multiple of 8. If the location counter
2726 is already a multiple of 8, no change is needed.
2729 The second expression (also absolute) gives the value to be stored in
2730 the padding bytes. It (and the comma) may be omitted. If it is
2731 omitted, the padding bytes are zero.
2734 @section @code{.app-file @var{string}}
2736 @cindex logical file name
2737 @cindex file name, logical
2738 @cindex @code{app-file} directive
2740 @ifclear no-file-dir
2741 (which may also be spelled @samp{.file})
2743 tells @code{@value{AS}} that we are about to start a new
2744 logical file. @var{string} is the new file name. In general, the
2745 filename is recognized whether or not it is surrounded by quotes @samp{"};
2746 but if you wish to specify an empty file name is permitted,
2747 you must give the quotes--@code{""}. This statement may go away in
2748 future: it is only recognized to be compatible with old @code{@value{AS}}
2752 @section @code{.ascii "@var{string}"}@dots{}
2754 @cindex @code{ascii} directive
2755 @cindex string literals
2756 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2757 separated by commas. It assembles each string (with no automatic
2758 trailing zero byte) into consecutive addresses.
2761 @section @code{.asciz "@var{string}"}@dots{}
2763 @cindex @code{asciz} directive
2764 @cindex zero-terminated strings
2765 @cindex null-terminated strings
2766 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2767 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2770 @section @code{.byte @var{expressions}}
2772 @cindex @code{byte} directive
2773 @cindex integers, one byte
2774 @code{.byte} expects zero or more expressions, separated by commas.
2775 Each expression is assembled into the next byte.
2778 @section @code{.comm @var{symbol} , @var{length} }
2780 @cindex @code{comm} directive
2781 @cindex symbol, common
2782 @code{.comm} declares a named common area in the bss section. Normally
2783 @code{@value{LD}} reserves memory addresses for it during linking, so no partial
2784 program defines the location of the symbol. Use @code{.comm} to tell
2785 @code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}}
2786 allocates space for each @code{.comm} symbol that is at least as
2787 long as the longest @code{.comm} request in any of the partial programs
2788 linked. @var{length} is an absolute expression.
2791 The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
2792 @samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
2796 @section @code{.data @var{subsection}}
2798 @cindex @code{data} directive
2799 @code{.data} tells @code{@value{AS}} to assemble the following statements onto the
2800 end of the data subsection numbered @var{subsection} (which is an
2801 absolute expression). If @var{subsection} is omitted, it defaults
2806 @section @code{.def @var{name}}
2808 @cindex @code{def} directive
2809 @cindex COFF symbols, debugging
2810 @cindex debugging COFF symbols
2811 Begin defining debugging information for a symbol @var{name}; the
2812 definition extends until the @code{.endef} directive is encountered.
2815 This directive is only observed when @code{@value{AS}} is configured for COFF
2816 format output; when producing @code{b.out}, @samp{.def} is recognized,
2823 @section @code{.desc @var{symbol}, @var{abs-expression}}
2825 @cindex @code{desc} directive
2826 @cindex COFF symbol descriptor
2827 @cindex symbol descriptor, COFF
2828 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2829 to the low 16 bits of an absolute expression.
2832 The @samp{.desc} directive is not available when @code{@value{AS}} is
2833 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2834 object format. For the sake of compatibility, @code{@value{AS}} accepts
2835 it, but produces no output, when configured for COFF.
2841 @section @code{.dim}
2843 @cindex @code{dim} directive
2844 @cindex COFF auxiliary symbol information
2845 @cindex auxiliary symbol information, COFF
2846 This directive is generated by compilers to include auxiliary debugging
2847 information in the symbol table. It is only permitted inside
2848 @code{.def}/@code{.endef} pairs.
2851 @samp{.dim} is only meaningful when generating COFF format output; when
2852 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
2858 @section @code{.double @var{flonums}}
2860 @cindex @code{double} directive
2861 @cindex floating point numbers (double)
2862 @code{.double} expects zero or more flonums, separated by commas. It
2863 assembles floating point numbers.
2865 The exact kind of floating point numbers emitted depends on how
2866 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
2870 On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
2871 in @sc{ieee} format.
2876 @section @code{.eject}
2878 @cindex @code{eject} directive
2879 @cindex new page, in listings
2880 @cindex page, in listings
2881 @cindex listing control: new page
2882 Force a page break at this point, when generating assembly listings.
2885 @section @code{.else}
2887 @cindex @code{else} directive
2888 @code{.else} is part of the @code{@value{AS}} support for conditional
2889 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2890 of code to be assembled if the condition for the preceding @code{.if}
2894 @node End, Endef, Else, Pseudo Ops
2895 @section @code{.end}
2897 @cindex @code{end} directive
2898 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2899 meant to do something eventually (which is why it isn't documented here
2900 as "for compatibility with blah").
2905 @section @code{.endef}
2907 @cindex @code{endef} directive
2908 This directive flags the end of a symbol definition begun with
2912 @samp{.endef} is only meaningful when generating COFF format output; if
2913 @code{@value{AS}} is configured to generate @code{b.out}, it accepts this
2914 directive but ignores it.
2919 @section @code{.endif}
2921 @cindex @code{endif} directive
2922 @code{.endif} is part of the @code{@value{AS}} support for conditional assembly;
2923 it marks the end of a block of code that is only assembled
2924 conditionally. @xref{If,,@code{.if}}.
2927 @section @code{.equ @var{symbol}, @var{expression}}
2929 @cindex @code{equ} directive
2930 @cindex assigning values to symbols
2931 @cindex symbols, assigning values to
2932 This directive sets the value of @var{symbol} to @var{expression}.
2933 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
2936 The syntax for @code{equ} on the HPPA is
2937 @samp{@var{symbol} .equ @var{expression}}.
2941 @section @code{.extern}
2943 @cindex @code{extern} directive
2944 @code{.extern} is accepted in the source program---for compatibility
2945 with other assemblers---but it is ignored. @code{@value{AS}} treats
2946 all undefined symbols as external.
2948 @ifclear no-file-dir
2950 @section @code{.file @var{string}}
2952 @cindex @code{file} directive
2953 @cindex logical file name
2954 @cindex file name, logical
2955 @code{.file} (which may also be spelled @samp{.app-file}) tells
2956 @code{@value{AS}} that we are about to start a new logical file.
2957 @var{string} is the new file name. In general, the filename is
2958 recognized whether or not it is surrounded by quotes @samp{"}; but if
2959 you wish to specify an empty file name, you must give the
2960 quotes--@code{""}. This statement may go away in future: it is only
2961 recognized to be compatible with old @code{@value{AS}} programs.
2963 In some configurations of @code{@value{AS}}, @code{.file} has already been
2964 removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}.
2969 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
2971 @cindex @code{fill} directive
2972 @cindex writing patterns in memory
2973 @cindex patterns, writing in memory
2974 @var{result}, @var{size} and @var{value} are absolute expressions.
2975 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
2976 may be zero or more. @var{Size} may be zero or more, but if it is
2977 more than 8, then it is deemed to have the value 8, compatible with
2978 other people's assemblers. The contents of each @var{repeat} bytes
2979 is taken from an 8-byte number. The highest order 4 bytes are
2980 zero. The lowest order 4 bytes are @var{value} rendered in the
2981 byte-order of an integer on the computer @code{@value{AS}} is assembling for.
2982 Each @var{size} bytes in a repetition is taken from the lowest order
2983 @var{size} bytes of this number. Again, this bizarre behavior is
2984 compatible with other people's assemblers.
2986 @var{size} and @var{value} are optional.
2987 If the second comma and @var{value} are absent, @var{value} is
2988 assumed zero. If the first comma and following tokens are absent,
2989 @var{size} is assumed to be 1.
2992 @section @code{.float @var{flonums}}
2994 @cindex floating point numbers (single)
2995 @cindex @code{float} directive
2996 This directive assembles zero or more flonums, separated by commas. It
2997 has the same effect as @code{.single}.
2999 The exact kind of floating point numbers emitted depends on how
3000 @code{@value{AS}} is configured.
3001 @xref{Machine Dependencies}.
3005 On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
3006 in @sc{ieee} format.
3011 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
3013 @cindex @code{global} directive
3014 @cindex symbol, making visible to linker
3015 @code{.global} makes the symbol visible to @code{@value{LD}}. If you define
3016 @var{symbol} in your partial program, its value is made available to
3017 other partial programs that are linked with it. Otherwise,
3018 @var{symbol} takes its attributes from a symbol of the same name
3019 from another file linked into the same program.
3021 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
3022 compatibility with other assemblers.
3025 On the HPPA, @code{.global} is not always enough to make it accessible to other
3026 partial programs. You may need the HPPA-only @code{.EXPORT} directive as well.
3027 @xref{HPPA Directives,, HPPA Assembler Directives}.
3031 @section @code{.hword @var{expressions}}
3033 @cindex @code{hword} directive
3034 @cindex integers, 16-bit
3035 @cindex numbers, 16-bit
3036 @cindex sixteen bit integers
3037 This expects zero or more @var{expressions}, and emits
3038 a 16 bit number for each.
3041 This directive is a synonym for @samp{.short}; depending on the target
3042 architecture, it may also be a synonym for @samp{.word}.
3046 This directive is a synonym for @samp{.short}.
3049 This directive is a synonym for both @samp{.short} and @samp{.word}.
3054 @section @code{.ident}
3056 @cindex @code{ident} directive
3057 This directive is used by some assemblers to place tags in object files.
3058 @code{@value{AS}} simply accepts the directive for source-file
3059 compatibility with such assemblers, but does not actually emit anything
3063 @section @code{.if @var{absolute expression}}
3065 @cindex conditional assembly
3066 @cindex @code{if} directive
3067 @code{.if} marks the beginning of a section of code which is only
3068 considered part of the source program being assembled if the argument
3069 (which must be an @var{absolute expression}) is non-zero. The end of
3070 the conditional section of code must be marked by @code{.endif}
3071 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
3072 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
3074 The following variants of @code{.if} are also supported:
3076 @item .ifdef @var{symbol}
3077 @cindex @code{ifdef} directive
3078 Assembles the following section of code if the specified @var{symbol}
3083 @cindex @code{ifeqs} directive
3084 Not yet implemented.
3087 @item .ifndef @var{symbol}
3088 @itemx ifnotdef @var{symbol}
3089 @cindex @code{ifndef} directive
3090 @cindex @code{ifnotdef} directive
3091 Assembles the following section of code if the specified @var{symbol}
3092 has not been defined. Both spelling variants are equivalent.
3096 Not yet implemented.
3101 @section @code{.include "@var{file}"}
3103 @cindex @code{include} directive
3104 @cindex supporting files, including
3105 @cindex files, including
3106 This directive provides a way to include supporting files at specified
3107 points in your source program. The code from @var{file} is assembled as
3108 if it followed the point of the @code{.include}; when the end of the
3109 included file is reached, assembly of the original file continues. You
3110 can control the search paths used with the @samp{-I} command-line option
3111 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
3115 @section @code{.int @var{expressions}}
3117 @cindex @code{int} directive
3118 @cindex integers, 32-bit
3119 Expect zero or more @var{expressions}, of any section, separated by commas.
3120 For each expression, emit a number that, at run time, is the value of that
3121 expression. The byte order and bit size of the number depends on what kind
3122 of target the assembly is for.
3126 On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
3127 integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits
3133 @section @code{.lcomm @var{symbol} , @var{length}}
3135 @cindex @code{lcomm} directive
3136 @cindex local common symbols
3137 @cindex symbols, local common
3138 Reserve @var{length} (an absolute expression) bytes for a local common
3139 denoted by @var{symbol}. The section and value of @var{symbol} are
3140 those of the new local common. The addresses are allocated in the bss
3141 section, so that at run-time the bytes start off zeroed. @var{Symbol}
3142 is not declared global (@pxref{Global,,@code{.global}}), so is normally
3143 not visible to @code{@value{LD}}.
3146 The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
3147 @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
3151 @section @code{.lflags}
3153 @cindex @code{lflags} directive (ignored)
3154 @code{@value{AS}} accepts this directive, for compatibility with other
3155 assemblers, but ignores it.
3157 @ifclear no-line-dir
3159 @section @code{.line @var{line-number}}
3161 @cindex @code{line} directive
3165 @section @code{.ln @var{line-number}}
3167 @cindex @code{ln} directive
3169 @cindex logical line number
3171 Change the logical line number. @var{line-number} must be an absolute
3172 expression. The next line has that logical line number. Therefore any other
3173 statements on the current line (after a statement separator character) are
3174 reported as on logical line number @var{line-number} @minus{} 1. One day
3175 @code{@value{AS}} will no longer support this directive: it is recognized only
3176 for compatibility with existing assembler programs.
3180 @emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
3181 only available with the name @code{.ln}, rather than as either
3182 @code{.line} or @code{.ln}.
3187 @ifclear no-line-dir
3188 Even though this is a directive associated with the @code{a.out} or
3189 @code{b.out} object-code formats, @code{@value{AS}} still recognizes it
3190 when producing COFF output, and treats @samp{.line} as though it
3191 were the COFF @samp{.ln} @emph{if} it is found outside a
3192 @code{.def}/@code{.endef} pair.
3194 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
3195 used by compilers to generate auxiliary symbol information for
3200 @section @code{.ln @var{line-number}}
3202 @cindex @code{ln} directive
3203 @ifclear no-line-dir
3204 @samp{.ln} is a synonym for @samp{.line}.
3207 Tell @code{@value{AS}} to change the logical line number. @var{line-number}
3208 must be an absolute expression. The next line has that logical
3209 line number, so any other statements on the current line (after a
3210 statement separator character @code{;}) are reported as on logical
3211 line number @var{line-number} @minus{} 1.
3214 This directive is accepted, but ignored, when @code{@value{AS}} is
3215 configured for @code{b.out}; its effect is only associated with COFF
3221 @section @code{.list}
3223 @cindex @code{list} directive
3224 @cindex listing control, turning on
3225 Control (in conjunction with the @code{.nolist} directive) whether or
3226 not assembly listings are generated. These two directives maintain an
3227 internal counter (which is zero initially). @code{.list} increments the
3228 counter, and @code{.nolist} decrements it. Assembly listings are
3229 generated whenever the counter is greater than zero.
3231 By default, listings are disabled. When you enable them (with the
3232 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
3233 the initial value of the listing counter is one.
3236 @section @code{.long @var{expressions}}
3238 @cindex @code{long} directive
3239 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
3242 @c no one seems to know what this is for or whether this description is
3243 @c what it really ought to do
3245 @section @code{.lsym @var{symbol}, @var{expression}}
3247 @cindex @code{lsym} directive
3248 @cindex symbol, not referenced in assembly
3249 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
3250 the hash table, ensuring it cannot be referenced by name during the
3251 rest of the assembly. This sets the attributes of the symbol to be
3252 the same as the expression value:
3254 @var{other} = @var{descriptor} = 0
3255 @var{type} = @r{(section of @var{expression})}
3256 @var{value} = @var{expression}
3259 The new symbol is not flagged as external.
3263 @section @code{.nolist}
3265 @cindex @code{nolist} directive
3266 @cindex listing control, turning off
3267 Control (in conjunction with the @code{.list} directive) whether or
3268 not assembly listings are generated. These two directives maintain an
3269 internal counter (which is zero initially). @code{.list} increments the
3270 counter, and @code{.nolist} decrements it. Assembly listings are
3271 generated whenever the counter is greater than zero.
3274 @section @code{.octa @var{bignums}}
3276 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
3277 @cindex @code{octa} directive
3278 @cindex integer, 16-byte
3279 @cindex sixteen byte integer
3280 This directive expects zero or more bignums, separated by commas. For each
3281 bignum, it emits a 16-byte integer.
3283 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
3284 hence @emph{octa}-word for 16 bytes.
3287 @section @code{.org @var{new-lc} , @var{fill}}
3289 @cindex @code{org} directive
3290 @cindex location counter, advancing
3291 @cindex advancing location counter
3292 @cindex current address, advancing
3293 Advance the location counter of the current section to
3294 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3295 expression with the same section as the current subsection. That is,
3296 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3297 wrong section, the @code{.org} directive is ignored. To be compatible
3298 with former assemblers, if the section of @var{new-lc} is absolute,
3299 @code{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
3300 is the same as the current subsection.
3302 @code{.org} may only increase the location counter, or leave it
3303 unchanged; you cannot use @code{.org} to move the location counter
3306 @c double negative used below "not undefined" because this is a specific
3307 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3308 @c section. pesch@cygnus.com 18feb91
3309 Because @code{@value{AS}} tries to assemble programs in one pass @var{new-lc}
3310 may not be undefined. If you really detest this restriction we eagerly await
3311 a chance to share your improved assembler.
3313 Beware that the origin is relative to the start of the section, not
3314 to the start of the subsection. This is compatible with other
3315 people's assemblers.
3317 When the location counter (of the current subsection) is advanced, the
3318 intervening bytes are filled with @var{fill} which should be an
3319 absolute expression. If the comma and @var{fill} are omitted,
3320 @var{fill} defaults to zero.
3323 @section @code{.psize @var{lines} , @var{columns}}
3325 @cindex @code{psize} directive
3326 @cindex listing control: paper size
3327 @cindex paper size, for listings
3328 Use this directive to declare the number of lines---and, optionally, the
3329 number of columns---to use for each page, when generating listings.
3331 If you do not use @code{.psize}, listings use a default line-count
3332 of 60. You may omit the comma and @var{columns} specification; the
3333 default width is 200 columns.
3335 @code{@value{AS}} generates formfeeds whenever the specified number of
3336 lines is exceeded (or whenever you explicitly request one, using
3339 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3340 those explicitly specified with @code{.eject}.
3343 @section @code{.quad @var{bignums}}
3345 @cindex @code{quad} directive
3346 @code{.quad} expects zero or more bignums, separated by commas. For
3347 each bignum, it emits
3349 an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
3350 warning message; and just takes the lowest order 8 bytes of the bignum.
3351 @cindex eight-byte integer
3352 @cindex integer, 8-byte
3354 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3355 hence @emph{quad}-word for 8 bytes.
3358 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3359 warning message; and just takes the lowest order 16 bytes of the bignum.
3360 @cindex sixteen-byte integer
3361 @cindex integer, 16-byte
3365 @section @code{.sbttl "@var{subheading}"}
3367 @cindex @code{sbttl} directive
3368 @cindex subtitles for listings
3369 @cindex listing control: subtitle
3370 Use @var{subheading} as the title (third line, immediately after the
3371 title line) when generating assembly listings.
3373 This directive affects subsequent pages, as well as the current page if
3374 it appears within ten lines of the top of a page.
3378 @section @code{.scl @var{class}}
3380 @cindex @code{scl} directive
3381 @cindex symbol storage class (COFF)
3382 @cindex COFF symbol storage class
3383 Set the storage-class value for a symbol. This directive may only be
3384 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3385 whether a symbol is static or external, or it may record further
3386 symbolic debugging information.
3389 The @samp{.scl} directive is primarily associated with COFF output; when
3390 configured to generate @code{b.out} output format, @code{@value{AS}}
3391 accepts this directive but ignores it.
3397 @section @code{.section @var{name}, @var{subsection}}
3399 @cindex @code{section} directive
3400 @cindex named section (COFF)
3401 @cindex COFF named section
3402 Assemble the following code into end of subsection numbered
3403 @var{subsection} in the COFF named section @var{name}. If you omit
3404 @var{subsection}, @code{@value{AS}} uses subsection number zero.
3405 @samp{.section .text} is equivalent to the @code{.text} directive;
3406 @samp{.section .data} is equivalent to the @code{.data} directive.
3410 @section @code{.set @var{symbol}, @var{expression}}
3412 @cindex @code{set} directive
3413 @cindex symbol value, setting
3414 Set the value of @var{symbol} to @var{expression}. This
3415 changes @var{symbol}'s value and type to conform to
3416 @var{expression}. If @var{symbol} was flagged as external, it remains
3417 flagged. (@xref{Symbol Attributes}.)
3419 You may @code{.set} a symbol many times in the same assembly.
3420 If the expression's section is unknowable during pass 1, a second
3421 pass over the source program is necessary. The second pass is
3422 currently not implemented. @code{@value{AS}} aborts with an error
3423 message if one is required.
3425 If you @code{.set} a global symbol, the value stored in the object
3426 file is the last value stored into it.
3429 The syntax for @code{set} on the HPPA is
3430 @samp{@var{symbol} .set @var{expression}}.
3434 @section @code{.short @var{expressions}}
3436 @cindex @code{short} directive
3438 @code{.short} is normally the same as @samp{.word}.
3439 @xref{Word,,@code{.word}}.
3441 In some configurations, however, @code{.short} and @code{.word} generate
3442 numbers of different lengths; @pxref{Machine Dependencies}.
3446 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3449 This expects zero or more @var{expressions}, and emits
3450 a 16 bit number for each.
3455 @section @code{.single @var{flonums}}
3457 @cindex @code{single} directive
3458 @cindex floating point numbers (single)
3459 This directive assembles zero or more flonums, separated by commas. It
3460 has the same effect as @code{.float}.
3462 The exact kind of floating point numbers emitted depends on how
3463 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
3467 On the @value{TARGET} family, @code{.single} emits 32-bit floating point
3468 numbers in @sc{ieee} format.
3474 @section @code{.size}
3476 @cindex @code{size} directive
3477 This directive is generated by compilers to include auxiliary debugging
3478 information in the symbol table. It is only permitted inside
3479 @code{.def}/@code{.endef} pairs.
3482 @samp{.size} is only meaningful when generating COFF format output; when
3483 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3488 @ifclear no-space-dir
3490 @section @code{.space @var{size} , @var{fill}}
3492 @cindex @code{space} directive
3493 @cindex filling memory
3494 This directive emits @var{size} bytes, each of value @var{fill}. Both
3495 @var{size} and @var{fill} are absolute expressions. If the comma
3496 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3500 @emph{Warning:} @code{.space} has a completely different meaning for HPPA
3501 targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800
3502 Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the
3503 @code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives},
3512 @section @code{.space}
3513 @cindex @code{space} directive
3515 On the AMD 29K, this directive is ignored; it is accepted for
3516 compatibility with other AMD 29K assemblers.
3519 @emph{Warning:} In most versions of the GNU assembler, the directive
3520 @code{.space} has the effect of @code{.block} @xref{Machine Dependencies}.
3526 @section @code{.stabd, .stabn, .stabs}
3528 @cindex symbolic debuggers, information for
3529 @cindex @code{stab@var{x}} directives
3530 There are three directives that begin @samp{.stab}.
3531 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3532 The symbols are not entered in the @code{@value{AS}} hash table: they
3533 cannot be referenced elsewhere in the source file.
3534 Up to five fields are required:
3538 This is the symbol's name. It may contain any character except
3539 @samp{\000}, so is more general than ordinary symbol names. Some
3540 debuggers used to code arbitrarily complex structures into symbol names
3544 An absolute expression. The symbol's type is set to the low 8 bits of
3545 this expression. Any bit pattern is permitted, but @code{@value{LD}}
3546 and debuggers choke on silly bit patterns.
3549 An absolute expression. The symbol's ``other'' attribute is set to the
3550 low 8 bits of this expression.
3553 An absolute expression. The symbol's descriptor is set to the low 16
3554 bits of this expression.
3557 An absolute expression which becomes the symbol's value.
3560 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3561 or @code{.stabs} statement, the symbol has probably already been created;
3562 you get a half-formed symbol in your object file. This is
3563 compatible with earlier assemblers!
3566 @cindex @code{stabd} directive
3567 @item .stabd @var{type} , @var{other} , @var{desc}
3569 The ``name'' of the symbol generated is not even an empty string.
3570 It is a null pointer, for compatibility. Older assemblers used a
3571 null pointer so they didn't waste space in object files with empty
3574 The symbol's value is set to the location counter,
3575 relocatably. When your program is linked, the value of this symbol
3576 is the address of the location counter when the @code{.stabd} was
3579 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3580 @cindex @code{stabn} directive
3581 The name of the symbol is set to the empty string @code{""}.
3583 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3584 @cindex @code{stabs} directive
3585 All five fields are specified.
3591 @section @code{.string} "@var{str}"
3593 @cindex string, copying to object file
3594 @cindex @code{string} directive
3596 Copy the characters in @var{str} to the object file. You may specify more than
3597 one string to copy, separated by commas. Unless otherwise specified for a
3598 particular machine, the assembler marks the end of each string with a 0 byte.
3602 @section @code{.tag @var{structname}}
3604 @cindex COFF structure debugging
3605 @cindex structure debugging, COFF
3606 @cindex @code{tag} directive
3607 This directive is generated by compilers to include auxiliary debugging
3608 information in the symbol table. It is only permitted inside
3609 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3610 definitions in the symbol table with instances of those structures.
3613 @samp{.tag} is only used when generating COFF format output; when
3614 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3620 @section @code{.text @var{subsection}}
3622 @cindex @code{text} directive
3623 Tells @code{@value{AS}} to assemble the following statements onto the end of
3624 the text subsection numbered @var{subsection}, which is an absolute
3625 expression. If @var{subsection} is omitted, subsection number zero
3629 @section @code{.title "@var{heading}"}
3631 @cindex @code{title} directive
3632 @cindex listing control: title line
3633 Use @var{heading} as the title (second line, immediately after the
3634 source file name and pagenumber) when generating assembly listings.
3636 This directive affects subsequent pages, as well as the current page if
3637 it appears within ten lines of the top of a page.
3641 @section @code{.type @var{int}}
3643 @cindex COFF symbol type
3644 @cindex symbol type, COFF
3645 @cindex @code{type} directive
3646 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3647 records the integer @var{int} as the type attribute of a symbol table entry.
3650 @samp{.type} is associated only with COFF format output; when
3651 @code{@value{AS}} is configured for @code{b.out} output, it accepts this
3652 directive but ignores it.
3658 @section @code{.val @var{addr}}
3660 @cindex @code{val} directive
3661 @cindex COFF value attribute
3662 @cindex value attribute, COFF
3663 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3664 records the address @var{addr} as the value attribute of a symbol table
3668 @samp{.val} is used only for COFF output; when @code{@value{AS}} is
3669 configured for @code{b.out}, it accepts this directive but ignores it.
3674 @section @code{.word @var{expressions}}
3676 @cindex @code{word} directive
3677 This directive expects zero or more @var{expressions}, of any section,
3678 separated by commas.
3681 For each expression, @code{@value{AS}} emits a 32-bit number.
3684 For each expression, @code{@value{AS}} emits a 16-bit number.
3689 The size of the number emitted, and its byte order,
3690 depend on what target computer the assembly is for.
3693 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3694 @c happen---32-bit addressability, period; no long/short jumps.
3695 @ifset DIFF-TBL-KLUGE
3696 @cindex difference tables altered
3697 @cindex altered difference tables
3699 @emph{Warning: Special Treatment to support Compilers}
3703 Machines with a 32-bit address space, but that do less than 32-bit
3704 addressing, require the following special treatment. If the machine of
3705 interest to you does 32-bit addressing (or doesn't require it;
3706 @pxref{Machine Dependencies}), you can ignore this issue.
3709 In order to assemble compiler output into something that works,
3710 @code{@value{AS}} occasionlly does strange things to @samp{.word} directives.
3711 Directives of the form @samp{.word sym1-sym2} are often emitted by
3712 compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a
3713 directive of the form @samp{.word sym1-sym2}, and the difference between
3714 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}}
3715 creates a @dfn{secondary jump table}, immediately before the next label.
3716 This secondary jump table is preceded by a short-jump to the
3717 first byte after the secondary table. This short-jump prevents the flow
3718 of control from accidentally falling into the new table. Inside the
3719 table is a long-jump to @code{sym2}. The original @samp{.word}
3720 contains @code{sym1} minus the address of the long-jump to
3723 If there were several occurrences of @samp{.word sym1-sym2} before the
3724 secondary jump table, all of them are adjusted. If there was a
3725 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3726 long-jump to @code{sym4} is included in the secondary jump table,
3727 and the @code{.word} directives are adjusted to contain @code{sym3}
3728 minus the address of the long-jump to @code{sym4}; and so on, for as many
3729 entries in the original jump table as necessary.
3732 @emph{This feature may be disabled by compiling @code{@value{AS}} with the
3733 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3734 assembly language programmers.
3737 @c end DIFF-TBL-KLUGE
3740 @section Deprecated Directives
3742 @cindex deprecated directives
3743 @cindex obsolescent directives
3744 One day these directives won't work.
3745 They are included for compatibility with older assemblers.
3753 @node Machine Dependencies
3754 @chapter Machine Dependent Features
3756 @cindex machine dependencies
3757 The machine instruction sets are (almost by definition) different on
3758 each machine where @code{@value{AS}} runs. Floating point representations
3759 vary as well, and @code{@value{AS}} often supports a few additional
3760 directives or command-line options for compatibility with other
3761 assemblers on a particular platform. Finally, some versions of
3762 @code{@value{AS}} support special pseudo-instructions for branch
3765 This chapter discusses most of these differences, though it does not
3766 include details on any machine's instruction set. For details on that
3767 subject, see the hardware manufacturer's manual.
3771 * Vax-Dependent:: VAX Dependent Features
3774 * AMD29K-Dependent:: AMD 29K Dependent Features
3777 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
3780 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
3783 * HPPA-Dependent:: HPPA Dependent Features
3786 * SH-Dependent:: Hitachi SH Dependent Features
3789 * i960-Dependent:: Intel 80960 Dependent Features
3792 * M68K-Dependent:: M680x0 Dependent Features
3795 * Sparc-Dependent:: SPARC Dependent Features
3798 * Z8000-Dependent:: Z8000 Dependent Features
3801 * i386-Dependent:: 80386 Dependent Features
3808 @c The following major nodes are *sections* in the GENERIC version, *chapters*
3809 @c in single-cpu versions. This is mainly achieved by @lowersections. There is a
3810 @c peculiarity: to preserve cross-references, there must be a node called
3811 @c "Machine Dependencies". Hence the conditional nodenames in each
3812 @c major node below. Node defaulting in makeinfo requires adjacency of
3813 @c node and sectioning commands; hence the repetition of @chapter BLAH
3814 @c in both conditional blocks.
3819 @chapter VAX Dependent Features
3824 @node Machine Dependencies
3825 @chapter VAX Dependent Features
3831 * Vax-Opts:: VAX Command-Line Options
3832 * VAX-float:: VAX Floating Point
3833 * VAX-directives:: Vax Machine Directives
3834 * VAX-opcodes:: VAX Opcodes
3835 * VAX-branch:: VAX Branch Improvement
3836 * VAX-operands:: VAX Operands
3837 * VAX-no:: Not Supported on VAX
3842 @section VAX Command-Line Options
3844 @cindex command-line options ignored, VAX
3845 @cindex VAX command-line options ignored
3846 The Vax version of @code{@value{AS}} accepts any of the following options,
3847 gives a warning message that the option was ignored and proceeds.
3848 These options are for compatibility with scripts designed for other
3849 people's assemblers.
3852 @item @samp{-D} (Debug)
3853 @itemx @samp{-S} (Symbol Table)
3854 @itemx @samp{-T} (Token Trace)
3855 @cindex @code{-D}, ignored on VAX
3856 @cindex @code{-S}, ignored on VAX
3857 @cindex @code{-T}, ignored on VAX
3858 These are obsolete options used to debug old assemblers.
3860 @item @samp{-d} (Displacement size for JUMPs)
3861 @cindex @code{-d}, VAX option
3862 This option expects a number following the @samp{-d}. Like options
3863 that expect filenames, the number may immediately follow the
3864 @samp{-d} (old standard) or constitute the whole of the command line
3865 argument that follows @samp{-d} (GNU standard).
3867 @item @samp{-V} (Virtualize Interpass Temporary File)
3868 @cindex @code{-V}, redundant on VAX
3869 Some other assemblers use a temporary file. This option
3870 commanded them to keep the information in active memory rather
3871 than in a disk file. @code{@value{AS}} always does this, so this
3872 option is redundant.
3874 @item @samp{-J} (JUMPify Longer Branches)
3875 @cindex @code{-J}, ignored on VAX
3876 Many 32-bit computers permit a variety of branch instructions
3877 to do the same job. Some of these instructions are short (and
3878 fast) but have a limited range; others are long (and slow) but
3879 can branch anywhere in virtual memory. Often there are 3
3880 flavors of branch: short, medium and long. Some other
3881 assemblers would emit short and medium branches, unless told by
3882 this option to emit short and long branches.
3884 @item @samp{-t} (Temporary File Directory)
3885 @cindex @code{-t}, ignored on VAX
3886 Some other assemblers may use a temporary file, and this option
3887 takes a filename being the directory to site the temporary
3888 file. Since @code{@value{AS}} does not use a temporary disk file, this
3889 option makes no difference. @samp{-t} needs exactly one
3893 @cindex VMS (VAX) options
3894 @cindex options for VAX/VMS
3895 @cindex VAX/VMS options
3896 @cindex @code{-h} option, VAX/VMS
3897 @cindex @code{-+} option, VAX/VMS
3898 @cindex Vax-11 C compatibility
3899 @cindex symbols with lowercase, VAX/VMS
3900 @c FIXME! look into "I think" below, correct if needed, delete.
3901 The Vax version of the assembler accepts two options when
3902 compiled for VMS. They are @samp{-h}, and @samp{-+}. The
3903 @samp{-h} option prevents @code{@value{AS}} from modifying the
3904 symbol-table entries for symbols that contain lowercase
3905 characters (I think). The @samp{-+} option causes @code{@value{AS}} to
3906 print warning messages if the FILENAME part of the object file,
3907 or any symbol name is larger than 31 characters. The @samp{-+}
3908 option also inserts some code following the @samp{_main}
3909 symbol so that the object file is compatible with Vax-11
3913 @section VAX Floating Point
3915 @cindex VAX floating point
3916 @cindex floating point, VAX
3917 Conversion of flonums to floating point is correct, and
3918 compatible with previous assemblers. Rounding is
3919 towards zero if the remainder is exactly half the least significant bit.
3921 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
3924 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
3925 are rendered correctly. Again, rounding is towards zero in the
3928 @cindex @code{float} directive, VAX
3929 @cindex @code{double} directive, VAX
3930 The @code{.float} directive produces @code{f} format numbers.
3931 The @code{.double} directive produces @code{d} format numbers.
3933 @node VAX-directives
3934 @section Vax Machine Directives
3936 @cindex machine directives, VAX
3937 @cindex VAX machine directives
3938 The Vax version of the assembler supports four directives for
3939 generating Vax floating point constants. They are described in the
3942 @cindex wide floating point directives, VAX
3945 @cindex @code{dfloat} directive, VAX
3946 This expects zero or more flonums, separated by commas, and
3947 assembles Vax @code{d} format 64-bit floating point constants.
3950 @cindex @code{ffloat} directive, VAX
3951 This expects zero or more flonums, separated by commas, and
3952 assembles Vax @code{f} format 32-bit floating point constants.
3955 @cindex @code{gfloat} directive, VAX
3956 This expects zero or more flonums, separated by commas, and
3957 assembles Vax @code{g} format 64-bit floating point constants.
3960 @cindex @code{hfloat} directive, VAX
3961 This expects zero or more flonums, separated by commas, and
3962 assembles Vax @code{h} format 128-bit floating point constants.
3967 @section VAX Opcodes
3969 @cindex VAX opcode mnemonics
3970 @cindex opcode mnemonics, VAX
3971 @cindex mnemonics for opcodes, VAX
3972 All DEC mnemonics are supported. Beware that @code{case@dots{}}
3973 instructions have exactly 3 operands. The dispatch table that
3974 follows the @code{case@dots{}} instruction should be made with
3975 @code{.word} statements. This is compatible with all unix
3976 assemblers we know of.
3979 @section VAX Branch Improvement
3981 @cindex VAX branch improvement
3982 @cindex branch improvement, VAX
3983 @cindex pseudo-ops for branch, VAX
3984 Certain pseudo opcodes are permitted. They are for branch
3985 instructions. They expand to the shortest branch instruction that
3986 reaches the target. Generally these mnemonics are made by
3987 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
3988 This feature is included both for compatibility and to help
3989 compilers. If you do not need this feature, avoid these
3990 opcodes. Here are the mnemonics, and the code they can expand into.
3994 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
3996 @item (byte displacement)
3998 @item (word displacement)
4000 @item (long displacement)
4005 Unconditional branch.
4007 @item (byte displacement)
4009 @item (word displacement)
4011 @item (long displacement)
4015 @var{COND} may be any one of the conditional branches
4016 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
4017 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
4018 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
4019 @var{COND} may also be one of the bit tests
4020 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
4021 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
4022 @var{NOTCOND} is the opposite condition to @var{COND}.
4024 @item (byte displacement)
4025 @kbd{b@var{COND} @dots{}}
4026 @item (word displacement)
4027 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
4028 @item (long displacement)
4029 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
4032 @var{X} may be one of @code{b d f g h l w}.
4034 @item (word displacement)
4035 @kbd{@var{OPCODE} @dots{}}
4036 @item (long displacement)
4038 @var{OPCODE} @dots{}, foo ;
4045 @var{YYY} may be one of @code{lss leq}.
4047 @var{ZZZ} may be one of @code{geq gtr}.
4049 @item (byte displacement)
4050 @kbd{@var{OPCODE} @dots{}}
4051 @item (word displacement)
4053 @var{OPCODE} @dots{}, foo ;
4055 foo: brw @var{destination} ;
4058 @item (long displacement)
4060 @var{OPCODE} @dots{}, foo ;
4062 foo: jmp @var{destination} ;
4071 @item (byte displacement)
4072 @kbd{@var{OPCODE} @dots{}}
4073 @item (word displacement)
4075 @var{OPCODE} @dots{}, foo ;
4077 foo: brw @var{destination} ;
4080 @item (long displacement)
4082 @var{OPCODE} @dots{}, foo ;
4084 foo: jmp @var{destination} ;
4091 @section VAX Operands
4093 @cindex VAX operand notation
4094 @cindex operand notation, VAX
4095 @cindex immediate character, VAX
4096 @cindex VAX immediate character
4097 The immediate character is @samp{$} for Unix compatibility, not
4098 @samp{#} as DEC writes it.
4100 @cindex indirect character, VAX
4101 @cindex VAX indirect character
4102 The indirect character is @samp{*} for Unix compatibility, not
4103 @samp{@@} as DEC writes it.
4105 @cindex displacement sizing character, VAX
4106 @cindex VAX displacement sizing character
4107 The displacement sizing character is @samp{`} (an accent grave) for
4108 Unix compatibility, not @samp{^} as DEC writes it. The letter
4109 preceding @samp{`} may have either case. @samp{G} is not
4110 understood, but all other letters (@code{b i l s w}) are understood.
4112 @cindex register names, VAX
4113 @cindex VAX register names
4114 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
4115 pc}. Upper and lower case letters are equivalent.
4122 Any expression is permitted in an operand. Operands are comma
4125 @c There is some bug to do with recognizing expressions
4126 @c in operands, but I forget what it is. It is
4127 @c a syntax clash because () is used as an address mode
4128 @c and to encapsulate sub-expressions.
4131 @section Not Supported on VAX
4133 @cindex VAX bitfields not supported
4134 @cindex bitfields, not supported on VAX
4135 Vax bit fields can not be assembled with @code{@value{AS}}. Someone
4136 can add the required code if they really need it.
4142 @node AMD29K-Dependent
4143 @chapter AMD 29K Dependent Features
4146 @node Machine Dependencies
4147 @chapter AMD 29K Dependent Features
4150 @cindex AMD 29K support
4153 * AMD29K Options:: Options
4154 * AMD29K Syntax:: Syntax
4155 * AMD29K Floating Point:: Floating Point
4156 * AMD29K Directives:: AMD 29K Machine Directives
4157 * AMD29K Opcodes:: Opcodes
4160 @node AMD29K Options
4162 @cindex AMD 29K options (none)
4163 @cindex options for AMD29K (none)
4164 @code{@value{AS}} has no additional command-line options for the AMD
4170 * AMD29K-Chars:: Special Characters
4171 * AMD29K-Regs:: Register Names
4175 @subsection Special Characters
4177 @cindex line comment character, AMD 29K
4178 @cindex AMD 29K line comment character
4179 @samp{;} is the line comment character.
4181 @cindex line separator, AMD 29K
4182 @cindex AMD 29K line separator
4183 @cindex statement separator, AMD 29K
4184 @cindex AMD 29K statement separator
4185 @samp{@@} can be used instead of a newline to separate statements.
4187 @cindex identifiers, AMD 29K
4188 @cindex AMD 29K identifiers
4189 The character @samp{?} is permitted in identifiers (but may not begin
4193 @subsection Register Names
4195 @cindex AMD 29K register names
4196 @cindex register names, AMD 29K
4197 General-purpose registers are represented by predefined symbols of the
4198 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
4199 (for local registers), where @var{nnn} represents a number between
4200 @code{0} and @code{127}, written with no leading zeros. The leading
4201 letters may be in either upper or lower case; for example, @samp{gr13}
4202 and @samp{LR7} are both valid register names.
4204 You may also refer to general-purpose registers by specifying the
4205 register number as the result of an expression (prefixed with @samp{%%}
4206 to flag the expression as a register number):
4211 ---where @var{expression} must be an absolute expression evaluating to a
4212 number between @code{0} and @code{255}. The range [0, 127] refers to
4213 global registers, and the range [128, 255] to local registers.
4215 @cindex special purpose registers, AMD 29K
4216 @cindex AMD 29K special purpose registers
4217 @cindex protected registers, AMD 29K
4218 @cindex AMD 29K protected registers
4219 In addition, @code{@value{AS}} understands the following protected
4220 special-purpose register names for the AMD 29K family:
4230 These unprotected special-purpose register names are also recognized:
4238 @node AMD29K Floating Point
4239 @section Floating Point
4241 @cindex floating point, AMD 29K (@sc{ieee})
4242 @cindex AMD 29K floating point (@sc{ieee})
4243 The AMD 29K family uses @sc{ieee} floating-point numbers.
4245 @node AMD29K Directives
4246 @section AMD 29K Machine Directives
4248 @cindex machine directives, AMD 29K
4249 @cindex AMD 29K machine directives
4251 @item .block @var{size} , @var{fill}
4252 @cindex @code{block} directive, AMD 29K
4253 This directive emits @var{size} bytes, each of value @var{fill}. Both
4254 @var{size} and @var{fill} are absolute expressions. If the comma
4255 and @var{fill} are omitted, @var{fill} is assumed to be zero.
4257 In other versions of the GNU assembler, this directive is called
4263 @cindex @code{cputype} directive, AMD 29K
4264 This directive is ignored; it is accepted for compatibility with other
4268 @cindex @code{file} directive, AMD 29K
4269 This directive is ignored; it is accepted for compatibility with other
4273 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
4274 used for the directive called @code{.app-file} in the AMD 29K support.
4278 @cindex @code{line} directive, AMD 29K
4279 This directive is ignored; it is accepted for compatibility with other
4283 @c since we're ignoring .lsym...
4284 @item .reg @var{symbol}, @var{expression}
4285 @cindex @code{reg} directive, AMD 29K
4286 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
4290 @cindex @code{sect} directive, AMD 29K
4291 This directive is ignored; it is accepted for compatibility with other
4294 @item .use @var{section name}
4295 @cindex @code{use} directive, AMD 29K
4296 Establishes the section and subsection for the following code;
4297 @var{section name} may be one of @code{.text}, @code{.data},
4298 @code{.data1}, or @code{.lit}. With one of the first three @var{section
4299 name} options, @samp{.use} is equivalent to the machine directive
4300 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
4304 @node AMD29K Opcodes
4307 @cindex AMD 29K opcodes
4308 @cindex opcodes for AMD 29K
4309 @code{@value{AS}} implements all the standard AMD 29K opcodes. No
4310 additional pseudo-instructions are needed on this family.
4312 For information on the 29K machine instruction set, see @cite{Am29000
4313 User's Manual}, Advanced Micro Devices, Inc.
4318 @node Machine Dependencies
4319 @chapter Machine Dependent Features
4321 The machine instruction sets are different on each Hitachi chip family,
4322 and there are also some syntax differences among the families. This
4323 chapter describes the specific @code{@value{AS}} features for each
4327 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
4328 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
4329 * SH-Dependent:: Hitachi SH Dependent Features
4339 @node H8/300-Dependent
4340 @chapter H8/300 Dependent Features
4342 @cindex H8/300 support
4344 * H8/300 Options:: Options
4345 * H8/300 Syntax:: Syntax
4346 * H8/300 Floating Point:: Floating Point
4347 * H8/300 Directives:: H8/300 Machine Directives
4348 * H8/300 Opcodes:: Opcodes
4351 @node H8/300 Options
4354 @cindex H8/300 options (none)
4355 @cindex options, H8/300 (none)
4356 @code{@value{AS}} has no additional command-line options for the Hitachi
4362 * H8/300-Chars:: Special Characters
4363 * H8/300-Regs:: Register Names
4364 * H8/300-Addressing:: Addressing Modes
4368 @subsection Special Characters
4370 @cindex line comment character, H8/300
4371 @cindex H8/300 line comment character
4372 @samp{;} is the line comment character.
4374 @cindex line separator, H8/300
4375 @cindex statement separator, H8/300
4376 @cindex H8/300 line separator
4377 @samp{$} can be used instead of a newline to separate statements.
4378 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4381 @subsection Register Names
4383 @cindex H8/300 registers
4384 @cindex register names, H8/300
4385 You can use predefined symbols of the form @samp{r@var{n}h} and
4386 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4387 general-purpose registers. @var{n} is a digit from @samp{0} to
4388 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4391 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4392 to the H8/300 registers as 16-bit registers (you must use this form for
4395 On the H8/300H, you can also use the eight predefined symbols
4396 @samp{er@var{n}} (@samp{er0} @dots{} @samp{er7}) to refer to the 32-bit
4397 general purpose registers.
4399 The two control registers are called @code{pc} (program counter; a
4400 16-bit register, except on the H8/300H where it is 24 bits) and
4401 @code{ccr} (condition code register; an 8-bit register). @code{r7} is
4402 used as the stack pointer, and can also be called @code{sp}.
4404 @node H8/300-Addressing
4405 @subsection Addressing Modes
4407 @cindex addressing modes, H8/300
4408 @cindex H8/300 addressing modes
4409 @value{AS} understands the following addressing modes for the H8/300:
4417 @item @@(@var{d}, r@var{n})
4418 @itemx @@(@var{d}:16, r@var{n})
4419 @itemx @@(@var{d}:24, r@var{n})
4420 Register indirect: 16-bit or 24-bit displacement @var{d} from register
4421 @var{n}. (24-bit displacements are only meaningful on the H8/300H.)
4424 Register indirect with post-increment
4427 Register indirect with pre-decrement
4429 @item @code{@@}@var{aa}
4430 @itemx @code{@@}@var{aa}:8
4431 @itemx @code{@@}@var{aa}:16
4432 @itemx @code{@@}@var{aa}:24
4433 Absolute address @code{aa}. (The address size @samp{:24} only makes
4434 sense on the H8/300H.)
4440 Immediate data @var{xx}. You may specify the @samp{:8}, @samp{:16}, or
4441 @samp{:32} for clarity, if you wish; but @code{@value{AS}} neither
4442 requires this nor uses it---the data size required is taken from
4445 @item @code{@@}@code{@@}@var{aa}
4446 @itemx @code{@@}@code{@@}@var{aa}:8
4447 Memory indirect. You may specify the @samp{:8} for clarity, if you
4448 wish; but @code{@value{AS}} neither requires this nor uses it.
4451 @node H8/300 Floating Point
4452 @section Floating Point
4454 @cindex floating point, H8/300 (@sc{ieee})
4455 @cindex H8/300 floating point (@sc{ieee})
4456 The H8/300 family has no hardware floating point, but the @code{.float}
4457 directive generates @sc{ieee} floating-point numbers for compatibility
4458 with other development tools.
4461 @node H8/300 Directives
4462 @section H8/300 Machine Directives
4464 @cindex H8/300 machine directives (none)
4465 @cindex machine directives, H8/300 (none)
4466 @cindex @code{word} directive, H8/300
4467 @cindex @code{int} directive, H8/300
4468 @code{@value{AS}} has only one machine-dependent directive for the
4473 @cindex H8/300H, assembling for
4474 Recognize and emit additional instructions for the H8/300H variant, and
4475 also make @code{.int} emit 32-bit numbers rather than the usual (16-bit)
4476 for the H8/300 family.
4479 On the H8/300 family (including the H8/300H) @samp{.word} directives
4480 generate 16-bit numbers.
4482 @node H8/300 Opcodes
4485 @cindex H8/300 opcode summary
4486 @cindex opcode summary, H8/300
4487 @cindex mnemonics, H8/300
4488 @cindex instruction summary, H8/300
4489 For detailed information on the H8/300 machine instruction set, see
4490 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025). For
4491 information specific to the H8/300H, see @cite{H8/300H Series
4492 Programming Manual} (Hitachi).
4494 @code{@value{AS}} implements all the standard H8/300 opcodes. No additional
4495 pseudo-instructions are needed on this family.
4497 The following table summarizes the H8/300 opcodes, and their arguments.
4498 Entries marked @samp{*} are opcodes used only on the H8/300H.
4501 @c Using @group seems to use the normal baselineskip, not the smallexample
4502 @c baselineskip; looks approx doublespaced.
4504 Rs @r{source register}
4505 Rd @r{destination register}
4506 abs @r{absolute address}
4507 imm @r{immediate data}
4508 disp:N @r{N-bit displacement from a register}
4509 pcrel:N @r{N-bit displacement relative to program counter}
4511 add.b #imm,rd * andc #imm,ccr
4512 add.b rs,rd band #imm,rd
4513 add.w rs,rd band #imm,@@rd
4514 * add.w #imm,rd band #imm,@@abs:8
4515 * add.l rs,rd bra pcrel:8
4516 * add.l #imm,rd * bra pcrel:16
4517 adds #imm,rd bt pcrel:8
4518 addx #imm,rd * bt pcrel:16
4519 addx rs,rd brn pcrel:8
4520 and.b #imm,rd * brn pcrel:16
4521 and.b rs,rd bf pcrel:8
4522 * and.w rs,rd * bf pcrel:16
4523 * and.w #imm,rd bhi pcrel:8
4524 * and.l #imm,rd * bhi pcrel:16
4525 * and.l rs,rd bls pcrel:8
4527 * bls pcrel:16 bld #imm,rd
4528 bcc pcrel:8 bld #imm,@@rd
4529 * bcc pcrel:16 bld #imm,@@abs:8
4530 bhs pcrel:8 bnot #imm,rd
4531 * bhs pcrel:16 bnot #imm,@@rd
4532 bcs pcrel:8 bnot #imm,@@abs:8
4533 * bcs pcrel:16 bnot rs,rd
4534 blo pcrel:8 bnot rs,@@rd
4535 * blo pcrel:16 bnot rs,@@abs:8
4536 bne pcrel:8 bor #imm,rd
4537 * bne pcrel:16 bor #imm,@@rd
4538 beq pcrel:8 bor #imm,@@abs:8
4539 * beq pcrel:16 bset #imm,rd
4540 bvc pcrel:8 bset #imm,@@rd
4541 * bvc pcrel:16 bset #imm,@@abs:8
4542 bvs pcrel:8 bset rs,rd
4543 * bvs pcrel:16 bset rs,@@rd
4544 bpl pcrel:8 bset rs,@@abs:8
4545 * bpl pcrel:16 bsr pcrel:8
4546 bmi pcrel:8 bsr pcrel:16
4547 * bmi pcrel:16 bst #imm,rd
4548 bge pcrel:8 bst #imm,@@rd
4549 * bge pcrel:16 bst #imm,@@abs:8
4550 blt pcrel:8 btst #imm,rd
4551 * blt pcrel:16 btst #imm,@@rd
4552 bgt pcrel:8 btst #imm,@@abs:8
4553 * bgt pcrel:16 btst rs,rd
4554 ble pcrel:8 btst rs,@@rd
4555 * ble pcrel:16 btst rs,@@abs:8
4556 bclr #imm,rd bxor #imm,rd
4557 bclr #imm,@@rd bxor #imm,@@rd
4558 bclr #imm,@@abs:8 bxor #imm,@@abs:8
4559 bclr rs,rd cmp.b #imm,rd
4560 bclr rs,@@rd cmp.b rs,rd
4561 bclr rs,@@abs:8 cmp.w rs,rd
4562 biand #imm,rd cmp.w rs,rd
4563 biand #imm,@@rd * cmp.w #imm,rd
4564 biand #imm,@@abs:8 * cmp.l #imm,rd
4565 bild #imm,rd * cmp.l rs,rd
4566 bild #imm,@@rd daa rs
4567 bild #imm,@@abs:8 das rs
4568 bior #imm,rd dec.b rs
4569 bior #imm,@@rd * dec.w #imm,rd
4570 bior #imm,@@abs:8 * dec.l #imm,rd
4571 bist #imm,rd divxu.b rs,rd
4572 bist #imm,@@rd * divxu.w rs,rd
4573 bist #imm,@@abs:8 * divxs.b rs,rd
4574 bixor #imm,rd * divxs.w rs,rd
4575 bixor #imm,@@rd eepmov
4576 bixor #imm,@@abs:8 * eepmovw
4578 * exts.w rd mov.w rs,@@abs:16
4579 * exts.l rd * mov.l #imm,rd
4580 * extu.w rd * mov.l rs,rd
4581 * extu.l rd * mov.l @@rs,rd
4582 inc rs * mov.l @@(disp:16,rs),rd
4583 * inc.w #imm,rd * mov.l @@(disp:24,rs),rd
4584 * inc.l #imm,rd * mov.l @@rs+,rd
4585 jmp @@rs * mov.l @@abs:16,rd
4586 jmp abs * mov.l @@abs:24,rd
4587 jmp @@@@abs:8 * mov.l rs,@@rd
4588 jsr @@rs * mov.l rs,@@(disp:16,rd)
4589 jsr abs * mov.l rs,@@(disp:24,rd)
4590 jsr @@@@abs:8 * mov.l rs,@@-rd
4591 ldc #imm,ccr * mov.l rs,@@abs:16
4592 ldc rs,ccr * mov.l rs,@@abs:24
4593 * ldc @@abs:16,ccr movfpe @@abs:16,rd
4594 * ldc @@abs:24,ccr movtpe rs,@@abs:16
4595 * ldc @@(disp:16,rs),ccr mulxu.b rs,rd
4596 * ldc @@(disp:24,rs),ccr * mulxu.w rs,rd
4597 * ldc @@rs+,ccr * mulxs.b rs,rd
4598 * ldc @@rs,ccr * mulxs.w rs,rd
4599 * mov.b @@(disp:24,rs),rd neg.b rs
4600 * mov.b rs,@@(disp:24,rd) * neg.w rs
4601 mov.b @@abs:16,rd * neg.l rs
4603 mov.b @@abs:8,rd not.b rs
4604 mov.b rs,@@abs:8 * not.w rs
4605 mov.b rs,rd * not.l rs
4606 mov.b #imm,rd or.b #imm,rd
4607 mov.b @@rs,rd or.b rs,rd
4608 mov.b @@(disp:16,rs),rd * or.w #imm,rd
4609 mov.b @@rs+,rd * or.w rs,rd
4610 mov.b @@abs:8,rd * or.l #imm,rd
4611 mov.b rs,@@rd * or.l rs,rd
4612 mov.b rs,@@(disp:16,rd) orc #imm,ccr
4613 mov.b rs,@@-rd pop.w rs
4614 mov.b rs,@@abs:8 * pop.l rs
4615 mov.w rs,@@rd push.w rs
4616 * mov.w @@(disp:24,rs),rd * push.l rs
4617 * mov.w rs,@@(disp:24,rd) rotl.b rs
4618 * mov.w @@abs:24,rd * rotl.w rs
4619 * mov.w rs,@@abs:24 * rotl.l rs
4620 mov.w rs,rd rotr.b rs
4621 mov.w #imm,rd * rotr.w rs
4622 mov.w @@rs,rd * rotr.l rs
4623 mov.w @@(disp:16,rs),rd rotxl.b rs
4624 mov.w @@rs+,rd * rotxl.w rs
4625 mov.w @@abs:16,rd * rotxl.l rs
4626 mov.w rs,@@(disp:16,rd) rotxr.b rs
4627 mov.w rs,@@-rd * rotxr.w rs
4629 * rotxr.l rs * stc ccr,@@(disp:24,rd)
4631 rte * stc ccr,@@abs:16
4632 rts * stc ccr,@@abs:24
4633 shal.b rs sub.b rs,rd
4634 * shal.w rs sub.w rs,rd
4635 * shal.l rs * sub.w #imm,rd
4636 shar.b rs * sub.l rs,rd
4637 * shar.w rs * sub.l #imm,rd
4638 * shar.l rs subs #imm,rd
4639 shll.b rs subx #imm,rd
4640 * shll.w rs subx rs,rd
4641 * shll.l rs * trapa #imm
4642 shlr.b rs xor #imm,rd
4643 * shlr.w rs xor rs,rd
4644 * shlr.l rs * xor.w #imm,rd
4646 stc ccr,rd * xor.l #imm,rd
4647 * stc ccr,@@rs * xor.l rs,rd
4648 * stc ccr,@@(disp:16,rd) xorc #imm,ccr
4651 @cindex size suffixes, H8/300
4652 @cindex H8/300 size suffixes
4653 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4654 @code{sub}) are defined with variants using the suffixes @samp{.b},
4655 @samp{.w}, and @samp{.l} to specify the size of a memory operand.
4656 @code{@value{AS}} supports these suffixes, but does not require them;
4657 since one of the operands is always a register, @code{@value{AS}} can
4658 deduce the correct size.
4660 For example, since @code{r0} refers to a 16-bit register,
4663 @exdent is equivalent to
4667 If you use the size suffixes, @code{@value{AS}} issues a warning when
4668 the suffix and the register size do not match.
4673 @node H8/500-Dependent
4674 @chapter H8/500 Dependent Features
4676 @cindex H8/500 support
4678 * H8/500 Options:: Options
4679 * H8/500 Syntax:: Syntax
4680 * H8/500 Floating Point:: Floating Point
4681 * H8/500 Directives:: H8/500 Machine Directives
4682 * H8/500 Opcodes:: Opcodes
4685 @node H8/500 Options
4688 @cindex H8/500 options (none)
4689 @cindex options, H8/500 (none)
4690 @code{@value{AS}} has no additional command-line options for the Hitachi
4697 * H8/500-Chars:: Special Characters
4698 * H8/500-Regs:: Register Names
4699 * H8/500-Addressing:: Addressing Modes
4703 @subsection Special Characters
4705 @cindex line comment character, H8/500
4706 @cindex H8/500 line comment character
4707 @samp{!} is the line comment character.
4709 @cindex line separator, H8/500
4710 @cindex statement separator, H8/500
4711 @cindex H8/500 line separator
4712 @samp{;} can be used instead of a newline to separate statements.
4714 @cindex symbol names, @samp{$} in
4715 @cindex @code{$} in symbol names
4716 Since @samp{$} has no special meaning, you may use it in symbol names.
4719 @subsection Register Names
4721 @cindex H8/500 registers
4722 @cindex registers, H8/500
4723 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
4724 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, and @samp{r7} to refer to
4725 the H8/500 registers.
4727 The H8/500 also has these control registers:
4749 condition code register
4752 All registers are 16 bits long. To represent 32 bit numbers, use two
4753 adjacent registers; for distant memory addresses, use one of the segment
4754 pointers (@code{cp} for the program counter; @code{dp} for
4755 @code{r0}--@code{r3}; @code{ep} for @code{r4} and @code{r5}; and
4756 @code{tp} for @code{r6} and @code{r7}.
4758 @node H8/500-Addressing
4759 @subsection Addressing Modes
4761 @cindex addressing modes, H8/500
4762 @cindex H8/500 addressing modes
4763 @value{AS} understands the following addressing modes for the H8/500:
4771 @item @@(d:8, R@var{n})
4772 Register indirect with 8 bit signed displacement
4774 @item @@(d:16, R@var{n})
4775 Register indirect with 16 bit signed displacement
4778 Register indirect with pre-decrement
4781 Register indirect with post-increment
4784 8 bit absolute address
4787 16 bit absolute address
4796 @node H8/500 Floating Point
4797 @section Floating Point
4799 @cindex floating point, H8/500 (@sc{ieee})
4800 @cindex H8/500 floating point (@sc{ieee})
4801 The H8/500 family uses @sc{ieee} floating-point numbers.
4803 @node H8/500 Directives
4804 @section H8/500 Machine Directives
4806 @cindex H8/500 machine directives (none)
4807 @cindex machine directives, H8/500 (none)
4808 @cindex @code{word} directive, H8/500
4809 @cindex @code{int} directive, H8/500
4810 @code{@value{AS}} has no machine-dependent directives for the H8/500.
4811 However, on this platform the @samp{.int} and @samp{.word} directives
4812 generate 16-bit numbers.
4814 @node H8/500 Opcodes
4817 @cindex H8/500 opcode summary
4818 @cindex opcode summary, H8/500
4819 @cindex mnemonics, H8/500
4820 @cindex instruction summary, H8/500
4821 For detailed information on the H8/500 machine instruction set, see
4822 @cite{H8/500 Series Programming Manual} (Hitachi M21T001).
4824 @code{@value{AS}} implements all the standard H8/500 opcodes. No additional
4825 pseudo-instructions are needed on this family.
4827 The following table summarizes H8/500 opcodes and their operands:
4829 @c Use @group if it ever works, instead of @page
4833 abs8 @r{8-bit absolute address}
4834 abs16 @r{16-bit absolute address}
4835 abs24 @r{24-bit absolute address}
4836 crb @r{@code{ccr}, @code{br}, @code{ep}, @code{dp}, @code{tp}, @code{dp}}
4837 disp8 @r{8-bit displacement}
4838 ea @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4839 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16},}
4840 @r{@code{#xx:8}, @code{#xx:16}}
4841 ea_mem @r{@code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4842 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4843 ea_noimm @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4844 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4846 imm4 @r{4-bit immediate data}
4847 imm8 @r{8-bit immediate data}
4848 imm16 @r{16-bit immediate data}
4849 pcrel8 @r{8-bit offset from program counter}
4850 pcrel16 @r{16-bit offset from program counter}
4851 qim @r{@code{-2}, @code{-1}, @code{1}, @code{2}}
4853 rs @r{a register distinct from rd}
4854 rlist @r{comma-separated list of registers in parentheses;}
4855 @r{register ranges @code{rd-rs} are allowed}
4856 sp @r{stack pointer (@code{r7})}
4857 sr @r{status register}
4858 sz @r{size; @samp{.b} or @samp{.w}. If omitted, default @samp{.w}}
4860 ldc[.b] ea,crb bcc[.w] pcrel16
4861 ldc[.w] ea,sr bcc[.b] pcrel8
4862 add[:q] sz qim,ea_noimm bhs[.w] pcrel16
4863 add[:g] sz ea,rd bhs[.b] pcrel8
4864 adds sz ea,rd bcs[.w] pcrel16
4865 addx sz ea,rd bcs[.b] pcrel8
4866 and sz ea,rd blo[.w] pcrel16
4867 andc[.b] imm8,crb blo[.b] pcrel8
4868 andc[.w] imm16,sr bne[.w] pcrel16
4870 bra[.w] pcrel16 beq[.w] pcrel16
4871 bra[.b] pcrel8 beq[.b] pcrel8
4872 bt[.w] pcrel16 bvc[.w] pcrel16
4873 bt[.b] pcrel8 bvc[.b] pcrel8
4874 brn[.w] pcrel16 bvs[.w] pcrel16
4875 brn[.b] pcrel8 bvs[.b] pcrel8
4876 bf[.w] pcrel16 bpl[.w] pcrel16
4877 bf[.b] pcrel8 bpl[.b] pcrel8
4878 bhi[.w] pcrel16 bmi[.w] pcrel16
4879 bhi[.b] pcrel8 bmi[.b] pcrel8
4880 bls[.w] pcrel16 bge[.w] pcrel16
4881 bls[.b] pcrel8 bge[.b] pcrel8
4883 blt[.w] pcrel16 mov[:g][.b] imm8,ea_mem
4884 blt[.b] pcrel8 mov[:g][.w] imm16,ea_mem
4885 bgt[.w] pcrel16 movfpe[.b] ea,rd
4886 bgt[.b] pcrel8 movtpe[.b] rs,ea_noimm
4887 ble[.w] pcrel16 mulxu sz ea,rd
4888 ble[.b] pcrel8 neg sz ea
4889 bclr sz imm4,ea_noimm nop
4890 bclr sz rs,ea_noimm not sz ea
4891 bnot sz imm4,ea_noimm or sz ea,rd
4892 bnot sz rs,ea_noimm orc[.b] imm8,crb
4893 bset sz imm4,ea_noimm orc[.w] imm16,sr
4894 bset sz rs,ea_noimm pjmp abs24
4895 bsr[.b] pcrel8 pjmp @@rd
4896 bsr[.w] pcrel16 pjsr abs24
4897 btst sz imm4,ea_noimm pjsr @@rd
4898 btst sz rs,ea_noimm prtd imm8
4899 clr sz ea prtd imm16
4900 cmp[:e][.b] imm8,rd prts
4901 cmp[:i][.w] imm16,rd rotl sz ea
4902 cmp[:g].b imm8,ea_noimm rotr sz ea
4903 cmp[:g][.w] imm16,ea_noimm rotxl sz ea
4904 Cmp[:g] sz ea,rd rotxr sz ea
4906 divxu sz ea,rd rtd imm16
4908 exts[.b] rd scb/f rs,pcrel8
4909 extu[.b] rd scb/ne rs,pcrel8
4910 jmp @@rd scb/eq rs,pcrel8
4911 jmp @@(imm8,rd) shal sz ea
4912 jmp @@(imm16,rd) shar sz ea
4913 jmp abs16 shll sz ea
4915 jsr @@(imm8,rd) sleep
4916 jsr @@(imm16,rd) stc[.b] crb,ea_noimm
4917 jsr abs16 stc[.w] sr,ea_noimm
4918 ldm @@sp+,(rlist) stm (rlist),@@-sp
4919 link fp,imm8 sub sz ea,rd
4920 link fp,imm16 subs sz ea,rd
4921 mov[:e][.b] imm8,rd subx sz ea,rd
4922 mov[:i][.w] imm16,rd swap[.b] rd
4923 mov[:l][.w] abs8,rd tas[.b] ea
4924 mov[:l].b abs8,rd trapa imm4
4925 mov[:s][.w] rs,abs8 trap/vs
4926 mov[:s].b rs,abs8 tst sz ea
4927 mov[:f][.w] @@(disp8,fp),rd unlk fp
4928 mov[:f][.w] rs,@@(disp8,fp) xch[.w] rs,rd
4929 mov[:f].b @@(disp8,fp),rd xor sz ea,rd
4930 mov[:f].b rs,@@(disp8,fp) xorc.b imm8,crb
4931 mov[:g] sz rs,ea_mem xorc.w imm16,sr
4939 @node HPPA-Dependent
4940 @chapter HPPA Dependent Features
4944 * HPPA Notes:: Notes
4945 * HPPA Options:: Options
4946 * HPPA Syntax:: Syntax
4947 * HPPA Floating Point:: Floating Point
4948 * HPPA Directives:: HPPA Machine Directives
4949 * HPPA Opcodes:: Opcodes
4954 As a back end for GNU CC @code{@value{AS}} has been throughly tested and should
4955 work extremely well. We have tested it only minimally on hand written assembly
4956 code and no one has tested it much on the assembly output from the HP
4959 The format of the debugging sections has changed since the original
4960 @code{@value{AS}} port (version 1.3X) was released; therefore,
4961 you must rebuild all HPPA objects and libraries with the new
4962 assembler so that you can debug the final executable.
4964 The HPPA @code{@value{AS}} port generates a small subset of the relocations
4965 available in the SOM and ELF object file formats. Additional relocation
4966 support will be added as it becomes necessary.
4970 @code{@value{AS}} has no machine-dependent command-line options for the HPPA.
4975 The assembler syntax closely follows the HPPA instruction set
4976 reference manual; assembler directives and general syntax closely follow the
4977 HPPA assembly language reference manual, with a few noteworthy differences.
4979 First, a colon may immediately follow a label definition. This is
4980 simply for compatibility with how most assembly language programmers
4983 Some obscure expression parsing problems may affect hand written code which
4984 uses the @code{spop} instructions, or code which makes significant
4985 use of the @code{!} line separator.
4987 @code{@value{AS}} is much less forgiving about missing arguments and other
4988 similar oversights than the HP assembler. @code{@value{AS}} notifies you
4989 of missing arguments as syntax errors; this is regarded as a feature, not a
4992 Finally, @code{@value{AS}} allows you to use an external symbol without
4993 explicitly importing the symbol. @emph{Warning:} in the future this will be
4994 an error for HPPA targets.
4996 Special characters for HPPA targets include:
4998 @samp{;} is the line comment character.
5000 @samp{!} can be used instead of a newline to separate statements.
5002 Since @samp{$} has no special meaning, you may use it in symbol names.
5004 @node HPPA Floating Point
5005 @section Floating Point
5006 @cindex floating point, HPPA (@sc{ieee})
5007 @cindex HPPA floating point (@sc{ieee})
5008 The HPPA family uses @sc{ieee} floating-point numbers.
5010 @node HPPA Directives
5011 @section HPPA Assembler Directives
5013 @code{@value{AS}} for the HPPA supports many additional directives for
5014 compatibility with the native assembler. This section describes them only
5015 briefly. For detailed information on HPPA-specific assembler directives, see
5016 @cite{HP9000 Series 800 Assembly Language Reference Manual} (HP 92432-90001).
5018 @cindex HPPA directives not supported
5019 @code{@value{AS}} does @emph{not} support the following assembler directives
5020 described in the HP manual:
5029 @cindex @code{.param} on HPPA
5030 Beyond those implemented for compatibility, @code{@value{AS}} supports one
5031 additional assembler directive for the HPPA: @code{.param}. It conveys
5032 register argument locations for static functions. Its syntax closely follows
5033 the @code{.export} directive.
5035 @cindex HPPA-only directives
5036 These are the additional directives in @code{@value{AS}} for the HPPA:
5039 @item .block @var{n}
5040 @itemx .blockz @var{n}
5041 Reserve @var{n} bytes of storage, and initialize them to zero.
5044 Mark the beginning of a procedure call. Only the special case with @emph{no
5045 arguments} is allowed.
5047 @item .callinfo [ @var{param}=@var{value}, @dots{} ] [ @var{flag}, @dots{} ]
5048 Specify a number of parameters and flags that define the environment for a
5051 @var{param} may be any of @samp{frame} (frame size), @samp{entry_gr} (end of
5052 general register range), @samp{entry_fr} (end of float register range),
5053 @samp{entry_sr} (end of space register range).
5055 The values for @var{flag} are @samp{calls} or @samp{caller} (proc has
5056 subroutines), @samp{no_calls} (proc does not call subroutines), @samp{save_rp}
5057 (preserve return pointer), @samp{save_sp} (proc preserves stack pointer),
5058 @samp{no_unwind} (do not unwind this proc), @samp{hpux_int} (proc is interrupt
5062 @c ??? Not in HP manual
5063 Assemble into the code section.
5066 @item .copyright "@var{string}"
5067 In the SOM object format, insert @var{string} into the object code, marked as a
5072 @item .copyright "@var{string}"
5073 In the ELF object format, insert @var{string} into the object code, marked as a
5078 Not yet supported; the assembler rejects programs containing this directive.
5081 Mark the beginning of a procedure.
5084 Mark the end of a procedure.
5086 @item .export @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5087 Make a procedure @var{name} available to callers. @var{typ}, if present, must
5088 be one of @samp{absolute}, @samp{code} (ELF only, not SOM), @samp{data},
5089 @samp{entry}, @samp{data}, @samp{entry}, @samp{millicode}, @samp{plabel},
5090 @samp{pri_prog}, or @samp{sec_prog}.
5092 @var{param}, if present, provides either relocation information for the
5093 procedure arguments and result, or a privilege level. @var{param} may be
5094 @samp{argw@var{n}} (where @var{n} ranges from @code{0} to @code{3}, and
5095 indicates one of four one-word arguments); @samp{rtnval} (the procedure's
5096 result); or @samp{priv_lev} (privilege level). For arguments or the result,
5097 @var{r} specifies how to relocate, and must be one of @samp{no} (not
5098 relocatable), @samp{gr} (argument is in general register), @samp{fr} (in
5099 floating point register), or @samp{fu} (upper half of float register).
5100 For @samp{priv_lev}, @var{r} is an integer.
5103 @c ?? Not in HP manual
5104 Define a two-byte integer constant @var{n}; synonym for the portable
5105 @code{@value{AS}} directive @code{.short}.
5107 @item .import @var{name} [ ,@var{typ} ]
5108 Converse of @code{.export}; make a procedure available to call. The arguments
5109 use the same conventions as the first two arguments for @code{.export}.
5111 @item .label @var{name}
5112 Define @var{name} as a label for the current assembly location.
5115 @c ?? Not in HP manual
5116 Not yet supported; the assembler rejects programs containing this directive.
5118 @item .origin @var{lc}
5119 Advance location counter to @var{lc}. Synonym for the @code{@value{as}}
5120 portable directive @code{.org}.
5122 @item .param @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5124 Similar to @code{.export}, but used for static procedures.
5127 Use preceding the first statement of a procedure.
5130 Use following the last statement of a procedure.
5132 @item @var{label} .reg @var{expr}
5133 @c ?? Not in HP manual
5134 Synonym for @code{.equ}; define @var{label} with the absolute expression
5135 @var{expr} as its value.
5137 @item .space @var{secname}
5138 Switch to section @var{secname}, creating a new section by that name if
5139 necessary. You may only use @var{keywords} when creating a new section, not
5140 when switching to an existing one. @var{secname} may identify a section by
5141 number rather than by name.
5142 @c FIXME! Shouldn't there be optional parameters the first time? I don't see
5143 @c provision for them in pa_space.
5147 @c ?? Not in HP manual
5148 FIXME--- Comments in source indicate directive not well understood.
5151 @item .string "@var{str}"
5152 @cindex @code{string} directive on HPPA
5153 Copy the characters in @var{str} to the object file, after converting some
5154 @samp{\@var{x}} escape sequences to single characters. Use @samp{\x@var{dd}}
5155 to refer to a character in hexadecimal.
5156 @c FIXME! Is that all? HP manual mentions more, which I don't see in
5159 @emph{Warning!} The HPPA version of @code{.string} differs in two ways from the
5160 usual @code{@value{AS}} definition. First, it performs @samp{\} escape
5161 preprocessing, as described above; second, it does @emph{not} write a zero byte
5162 after copying @var{str}.
5164 @item .stringz "@var{str}"
5165 Like @code{.string}, but appends a zero byte after copying @var{str} to object
5168 @item .subspa @var{name} [ ,@var{params} ]
5169 Similar to @code{.space}, but selects a subsection @var{name} within the
5170 current section. You may only specify @var{params} when you create a
5171 subsection (in the first instance of @code{.subspa} for this @var{name}).
5173 If specified, @var{params} declare attributes of the subsection, identified by
5174 keywords. The keywords recognized are @samp{quad=@var{expr}} (``quadrant'' for
5175 this subsection), @samp{align=@var{expr}} (alignment for beginning of this
5176 subsection; a power of two), @samp{access=@var{expr}} (value for ``access
5177 rights'' field), @samp{sort=@var{expr}} (sorting order for this subspace in
5178 link), @samp{code_only} (subsection contains only code), @samp{unloadable}
5180 (subsection cannot be loaded into memory), @samp{common} (subsection is common
5181 block), @samp{dup_comm} (initialized data may have duplicate names),
5182 or @samp{zero} (subsection is all zeros, do not write in object file).
5184 @item .version "@var{str}"
5185 Write @var{str} as version identifier in object code.
5190 For detailed information on the HPPA machine instruction set, see
5191 @cite{PA-RISC Architecture and Instruction Set Reference Manual}
5198 @chapter Hitachi SH Dependent Features
5202 * SH Options:: Options
5203 * SH Syntax:: Syntax
5204 * SH Floating Point:: Floating Point
5205 * SH Directives:: SH Machine Directives
5206 * SH Opcodes:: Opcodes
5212 @cindex SH options (none)
5213 @cindex options, SH (none)
5214 @code{@value{AS}} has no additional command-line options for the Hitachi
5221 * SH-Chars:: Special Characters
5222 * SH-Regs:: Register Names
5223 * SH-Addressing:: Addressing Modes
5227 @subsection Special Characters
5229 @cindex line comment character, SH
5230 @cindex SH line comment character
5231 @samp{!} is the line comment character.
5233 @cindex line separator, SH
5234 @cindex statement separator, SH
5235 @cindex SH line separator
5236 You can use @samp{;} instead of a newline to separate statements.
5238 @cindex symbol names, @samp{$} in
5239 @cindex @code{$} in symbol names
5240 Since @samp{$} has no special meaning, you may use it in symbol names.
5243 @subsection Register Names
5245 @cindex SH registers
5246 @cindex registers, SH
5247 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
5248 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, @samp{r7}, @samp{r8},
5249 @samp{r9}, @samp{r10}, @samp{r11}, @samp{r12}, @samp{r13}, @samp{r14},
5250 and @samp{r15} to refer to the SH registers.
5252 The SH also has these control registers:
5256 procedure register (holds return address)
5263 high and low multiply accumulator registers
5269 global base register
5272 vector base register (for interrupt vectors)
5276 @subsection Addressing Modes
5278 @cindex addressing modes, SH
5279 @cindex SH addressing modes
5280 @code{@value{AS}} understands the following addressing modes for the SH.
5281 @code{R@var{n}} in the following refers to any of the numbered
5282 registers, but @emph{not} the control registers.
5292 Register indirect with pre-decrement
5295 Register indirect with post-increment
5297 @item @@(@var{disp}, R@var{n})
5298 Register indirect with displacement
5300 @item @@(R0, R@var{n})
5303 @item @@(@var{disp}, GBR)
5310 @itemx @@(@var{disp}, PC)
5311 PC relative address (for branch or for addressing memory). The
5312 @code{@value{AS}} implementation allows you to use the simpler form
5313 @var{addr} anywhere a PC relative address is called for; the alternate
5314 form is supported for compatibility with other assemblers.
5320 @node SH Floating Point
5321 @section Floating Point
5323 @cindex floating point, SH (@sc{ieee})
5324 @cindex SH floating point (@sc{ieee})
5325 The SH family uses @sc{ieee} floating-point numbers.
5328 @section SH Machine Directives
5330 @cindex SH machine directives (none)
5331 @cindex machine directives, SH (none)
5332 @cindex @code{word} directive, SH
5333 @cindex @code{int} directive, SH
5334 @code{@value{AS}} has no machine-dependent directives for the SH.
5339 @cindex SH opcode summary
5340 @cindex opcode summary, SH
5341 @cindex mnemonics, SH
5342 @cindex instruction summary, SH
5343 For detailed information on the SH machine instruction set, see
5344 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
5346 @code{@value{AS}} implements all the standard SH opcodes. No additional
5347 pseudo-instructions are needed on this family. Note, however, that
5348 because @code{@value{AS}} supports a simpler form of PC-relative
5349 addressing, you may simply write (for example)
5356 where other assemblers might require an explicit displacement to
5357 @code{bar} from the program counter:
5360 mov.l @@(@var{disp}, PC)
5363 Here is a summary of SH opcodes:
5368 Rn @r{a numbered register}
5369 Rm @r{another numbered register}
5370 #imm @r{immediate data}
5371 disp @r{displacement}
5372 disp8 @r{8-bit displacement}
5373 disp12 @r{12-bit displacement}
5375 add #imm,Rn lds.l @@Rn+,PR
5376 add Rm,Rn mac.w @@Rm+,@@Rn+
5377 addc Rm,Rn mov #imm,Rn
5378 addv Rm,Rn mov Rm,Rn
5379 and #imm,R0 mov.b Rm,@@(R0,Rn)
5380 and Rm,Rn mov.b Rm,@@-Rn
5381 and.b #imm,@@(R0,GBR) mov.b Rm,@@Rn
5382 bf disp8 mov.b @@(disp,Rm),R0
5383 bra disp12 mov.b @@(disp,GBR),R0
5384 bsr disp12 mov.b @@(R0,Rm),Rn
5385 bt disp8 mov.b @@Rm+,Rn
5386 clrmac mov.b @@Rm,Rn
5387 clrt mov.b R0,@@(disp,Rm)
5388 cmp/eq #imm,R0 mov.b R0,@@(disp,GBR)
5389 cmp/eq Rm,Rn mov.l Rm,@@(disp,Rn)
5390 cmp/ge Rm,Rn mov.l Rm,@@(R0,Rn)
5391 cmp/gt Rm,Rn mov.l Rm,@@-Rn
5392 cmp/hi Rm,Rn mov.l Rm,@@Rn
5393 cmp/hs Rm,Rn mov.l @@(disp,Rn),Rm
5394 cmp/pl Rn mov.l @@(disp,GBR),R0
5395 cmp/pz Rn mov.l @@(disp,PC),Rn
5396 cmp/str Rm,Rn mov.l @@(R0,Rm),Rn
5397 div0s Rm,Rn mov.l @@Rm+,Rn
5399 div1 Rm,Rn mov.l R0,@@(disp,GBR)
5400 exts.b Rm,Rn mov.w Rm,@@(R0,Rn)
5401 exts.w Rm,Rn mov.w Rm,@@-Rn
5402 extu.b Rm,Rn mov.w Rm,@@Rn
5403 extu.w Rm,Rn mov.w @@(disp,Rm),R0
5404 jmp @@Rn mov.w @@(disp,GBR),R0
5405 jsr @@Rn mov.w @@(disp,PC),Rn
5406 ldc Rn,GBR mov.w @@(R0,Rm),Rn
5407 ldc Rn,SR mov.w @@Rm+,Rn
5408 ldc Rn,VBR mov.w @@Rm,Rn
5409 ldc.l @@Rn+,GBR mov.w R0,@@(disp,Rm)
5410 ldc.l @@Rn+,SR mov.w R0,@@(disp,GBR)
5411 ldc.l @@Rn+,VBR mova @@(disp,PC),R0
5413 lds Rn,MACL muls Rm,Rn
5414 lds Rn,PR mulu Rm,Rn
5415 lds.l @@Rn+,MACH neg Rm,Rn
5416 lds.l @@Rn+,MACL negc Rm,Rn
5419 not Rm,Rn stc.l GBR,@@-Rn
5420 or #imm,R0 stc.l SR,@@-Rn
5421 or Rm,Rn stc.l VBR,@@-Rn
5422 or.b #imm,@@(R0,GBR) sts MACH,Rn
5423 rotcl Rn sts MACL,Rn
5425 rotl Rn sts.l MACH,@@-Rn
5426 rotr Rn sts.l MACL,@@-Rn
5431 shar Rn swap.b Rm,Rn
5432 shll Rn swap.w Rm,Rn
5433 shll16 Rn tas.b @@Rn
5435 shll8 Rn tst #imm,R0
5437 shlr16 Rn tst.b #imm,@@(R0,GBR)
5438 shlr2 Rn xor #imm,R0
5440 sleep xor.b #imm,@@(R0,GBR)
5441 stc GBR,Rn xtrct Rm,Rn
5455 @node i960-Dependent
5456 @chapter Intel 80960 Dependent Features
5459 @node Machine Dependencies
5460 @chapter Intel 80960 Dependent Features
5463 @cindex i960 support
5465 * Options-i960:: i960 Command-line Options
5466 * Floating Point-i960:: Floating Point
5467 * Directives-i960:: i960 Machine Directives
5468 * Opcodes for i960:: i960 Opcodes
5471 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
5472 @c long as they're not turned on for other machines than 960.
5476 @section i960 Command-line Options
5478 @cindex i960 options
5479 @cindex options, i960
5482 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
5483 @cindex i960 architecture options
5484 @cindex architecture options, i960
5485 @cindex @code{-A} options, i960
5486 Select the 80960 architecture. Instructions or features not supported
5487 by the selected architecture cause fatal errors.
5489 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
5490 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
5492 If none of these options is specified, @code{@value{AS}} generates code for any
5493 instruction or feature that is supported by @emph{some} version of the
5494 960 (even if this means mixing architectures!). In principle,
5495 @code{@value{AS}} attempts to deduce the minimal sufficient processor
5496 type if none is specified; depending on the object code format, the
5497 processor type may be recorded in the object file. If it is critical
5498 that the @code{@value{AS}} output match a specific architecture, specify that
5499 architecture explicitly.
5502 @cindex @code{-b} option, i960
5503 @cindex branch recording, i960
5504 @cindex i960 branch recording
5505 Add code to collect information about conditional branches taken, for
5506 later optimization using branch prediction bits. (The conditional branch
5507 instructions have branch prediction bits in the CA, CB, and CC
5508 architectures.) If @var{BR} represents a conditional branch instruction,
5509 the following represents the code generated by the assembler when
5510 @samp{-b} is specified:
5513 call @var{increment routine}
5514 .word 0 # pre-counter
5516 call @var{increment routine}
5517 .word 0 # post-counter
5520 The counter following a branch records the number of times that branch
5521 was @emph{not} taken; the differenc between the two counters is the
5522 number of times the branch @emph{was} taken.
5524 @cindex @code{gbr960}, i960 postprocessor
5525 @cindex branch statistics table, i960
5526 A table of every such @code{Label} is also generated, so that the
5527 external postprocessor @code{gbr960} (supplied by Intel) can locate all
5528 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
5529 this is a local symbol to permit collecting statistics for many separate
5530 object files. The table is word aligned, and begins with a two-word
5531 header. The first word, initialized to 0, is used in maintaining linked
5532 lists of branch tables. The second word is a count of the number of
5533 entries in the table, which follow immediately: each is a word, pointing
5534 to one of the labels illustrated above.
5538 @c END TEXI2ROFF-KILL
5540 +------------+------------+------------+ ... +------------+
5542 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
5544 +------------+------------+------------+ ... +------------+
5546 __BRANCH_TABLE__ layout
5552 \line{\leftskip=0pt\hskip\tableindent
5553 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
5554 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
5555 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
5557 @c END TEXI2ROFF-KILL
5559 The first word of the header is used to locate multiple branch tables,
5560 since each object file may contain one. Normally the links are
5561 maintained with a call to an initialization routine, placed at the
5562 beginning of each function in the file. The GNU C compiler
5563 generates these calls automatically when you give it a @samp{-b} option.
5564 For further details, see the documentation of @samp{gbr960}.
5567 @cindex @code{-norelax} option, i960
5568 Normally, Compare-and-Branch instructions with targets that require
5569 displacements greater than 13 bits (or that have external targets) are
5570 replaced with the corresponding compare (or @samp{chkbit}) and branch
5571 instructions. You can use the @samp{-norelax} option to specify that
5572 @code{@value{AS}} should generate errors instead, if the target displacement
5573 is larger than 13 bits.
5575 This option does not affect the Compare-and-Jump instructions; the code
5576 emitted for them is @emph{always} adjusted when necessary (depending on
5577 displacement size), regardless of whether you use @samp{-norelax}.
5580 @node Floating Point-i960
5581 @section Floating Point
5583 @cindex floating point, i960 (@sc{ieee})
5584 @cindex i960 floating point (@sc{ieee})
5585 @code{@value{AS}} generates @sc{ieee} floating-point numbers for the directives
5586 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
5588 @node Directives-i960
5589 @section i960 Machine Directives
5591 @cindex machine directives, i960
5592 @cindex i960 machine directives
5595 @cindex @code{bss} directive, i960
5596 @item .bss @var{symbol}, @var{length}, @var{align}
5597 Reserve @var{length} bytes in the bss section for a local @var{symbol},
5598 aligned to the power of two specified by @var{align}. @var{length} and
5599 @var{align} must be positive absolute expressions. This directive
5600 differs from @samp{.lcomm} only in that it permits you to specify
5601 an alignment. @xref{Lcomm,,@code{.lcomm}}.
5605 @item .extended @var{flonums}
5606 @cindex @code{extended} directive, i960
5607 @code{.extended} expects zero or more flonums, separated by commas; for
5608 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
5609 floating-point number.
5611 @item .leafproc @var{call-lab}, @var{bal-lab}
5612 @cindex @code{leafproc} directive, i960
5613 You can use the @samp{.leafproc} directive in conjunction with the
5614 optimized @code{callj} instruction to enable faster calls of leaf
5615 procedures. If a procedure is known to call no other procedures, you
5616 may define an entry point that skips procedure prolog code (and that does
5617 not depend on system-supplied saved context), and declare it as the
5618 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
5619 entry point that goes through the normal prolog, you can specify that
5620 entry point as @var{call-lab}.
5622 A @samp{.leafproc} declaration is meant for use in conjunction with the
5623 optimized call instruction @samp{callj}; the directive records the data
5624 needed later to choose between converting the @samp{callj} into a
5625 @code{bal} or a @code{call}.
5627 @var{call-lab} is optional; if only one argument is present, or if the
5628 two arguments are identical, the single argument is assumed to be the
5629 @code{bal} entry point.
5631 @item .sysproc @var{name}, @var{index}
5632 @cindex @code{sysproc} directive, i960
5633 The @samp{.sysproc} directive defines a name for a system procedure.
5634 After you define it using @samp{.sysproc}, you can use @var{name} to
5635 refer to the system procedure identified by @var{index} when calling
5636 procedures with the optimized call instruction @samp{callj}.
5638 Both arguments are required; @var{index} must be between 0 and 31
5642 @node Opcodes for i960
5643 @section i960 Opcodes
5645 @cindex opcodes, i960
5646 @cindex i960 opcodes
5647 All Intel 960 machine instructions are supported;
5648 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
5649 selecting the instruction subset for a particular 960
5650 architecture.@refill
5652 Some opcodes are processed beyond simply emitting a single corresponding
5653 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
5654 instructions with target displacements larger than 13 bits.
5657 * callj-i960:: @code{callj}
5658 * Compare-and-branch-i960:: Compare-and-Branch
5662 @subsection @code{callj}
5664 @cindex @code{callj}, i960 pseudo-opcode
5665 @cindex i960 @code{callj} pseudo-opcode
5666 You can write @code{callj} to have the assembler or the linker determine
5667 the most appropriate form of subroutine call: @samp{call},
5668 @samp{bal}, or @samp{calls}. If the assembly source contains
5669 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
5670 defining the operand---then @code{@value{AS}} translates the
5671 @code{callj}; if not, it simply emits the @code{callj}, leaving it
5672 for the linker to resolve.
5674 @node Compare-and-branch-i960
5675 @subsection Compare-and-Branch
5677 @cindex i960 compare/branch instructions
5678 @cindex compare/branch instructions, i960
5679 The 960 architectures provide combined Compare-and-Branch instructions
5680 that permit you to store the branch target in the lower 13 bits of the
5681 instruction word itself. However, if you specify a branch target far
5682 enough away that its address won't fit in 13 bits, the assembler can
5683 either issue an error, or convert your Compare-and-Branch instruction
5684 into separate instructions to do the compare and the branch.
5686 @cindex compare and jump expansions, i960
5687 @cindex i960 compare and jump expansions
5688 Whether @code{@value{AS}} gives an error or expands the instruction depends
5689 on two choices you can make: whether you use the @samp{-norelax} option,
5690 and whether you use a ``Compare and Branch'' instruction or a ``Compare
5691 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
5692 expanded if necessary; the ``Branch'' instructions are expanded when
5693 necessary @emph{unless} you specify @code{-norelax}---in which case
5694 @code{@value{AS}} gives an error instead.
5696 These are the Compare-and-Branch instructions, their ``Jump'' variants,
5697 and the instruction pairs they may expand into:
5701 @c END TEXI2ROFF-KILL
5704 Branch Jump Expanded to
5705 ------ ------ ------------
5708 cmpibe cmpije cmpi; be
5709 cmpibg cmpijg cmpi; bg
5710 cmpibge cmpijge cmpi; bge
5711 cmpibl cmpijl cmpi; bl
5712 cmpible cmpijle cmpi; ble
5713 cmpibno cmpijno cmpi; bno
5714 cmpibne cmpijne cmpi; bne
5715 cmpibo cmpijo cmpi; bo
5716 cmpobe cmpoje cmpo; be
5717 cmpobg cmpojg cmpo; bg
5718 cmpobge cmpojge cmpo; bge
5719 cmpobl cmpojl cmpo; bl
5720 cmpoble cmpojle cmpo; ble
5721 cmpobne cmpojne cmpo; bne
5727 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
5728 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
5729 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
5730 bbc& & chkbit; bno\cr
5731 bbs& & chkbit; bo\cr
5732 cmpibe& cmpije& cmpi; be\cr
5733 cmpibg& cmpijg& cmpi; bg\cr
5734 cmpibge& cmpijge& cmpi; bge\cr
5735 cmpibl& cmpijl& cmpi; bl\cr
5736 cmpible& cmpijle& cmpi; ble\cr
5737 cmpibno& cmpijno& cmpi; bno\cr
5738 cmpibne& cmpijne& cmpi; bne\cr
5739 cmpibo& cmpijo& cmpi; bo\cr
5740 cmpobe& cmpoje& cmpo; be\cr
5741 cmpobg& cmpojg& cmpo; bg\cr
5742 cmpobge& cmpojge& cmpo; bge\cr
5743 cmpobl& cmpojl& cmpo; bl\cr
5744 cmpoble& cmpojle& cmpo; ble\cr
5745 cmpobne& cmpojne& cmpo; bne\cr}
5747 @c END TEXI2ROFF-KILL
5753 @node M68K-Dependent
5754 @chapter M680x0 Dependent Features
5757 @node Machine Dependencies
5758 @chapter M680x0 Dependent Features
5761 @cindex M680x0 support
5763 * M68K-Opts:: M680x0 Options
5764 * M68K-Syntax:: Syntax
5765 * M68K-Moto-Syntax:: Motorola Syntax
5766 * M68K-Float:: Floating Point
5767 * M68K-Directives:: 680x0 Machine Directives
5768 * M68K-opcodes:: Opcodes
5772 @section M680x0 Options
5774 @cindex options, M680x0
5775 @cindex M680x0 options
5776 The Motorola 680x0 version of @code{@value{AS}} has two machine dependent options.
5777 One shortens undefined references from 32 to 16 bits, while the
5778 other is used to tell @code{@value{AS}} what kind of machine it is
5781 @cindex @code{-l} option, M680x0
5782 You can use the @samp{-l} option to shorten the size of references to undefined
5783 symbols. If you do not use the @samp{-l} option, references to undefined
5784 symbols are wide enough for a full @code{long} (32 bits). (Since
5785 @code{@value{AS}} cannot know where these symbols end up, @code{@value{AS}} can
5786 only allocate space for the linker to fill in later. Since @code{@value{AS}}
5787 doesn't know how far away these symbols are, it allocates as much space as it
5788 can.) If you use this option, the references are only one word wide (16 bits).
5789 This may be useful if you want the object file to be as small as possible, and
5790 you know that the relevant symbols are always less than 17 bits away.
5792 @cindex @code{-m68000} and related options
5793 @cindex architecture options, M680x0
5794 @cindex M680x0 architecture options
5795 The 680x0 version of @code{@value{AS}} is most frequently used to assemble
5796 programs for the Motorola MC68020 microprocessor. Occasionally it is
5797 used to assemble programs for the mostly similar, but slightly different
5798 MC68000 or MC68010 microprocessors. You can give @code{@value{AS}} the options
5799 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
5800 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
5807 This syntax for the Motorola 680x0 was developed at @sc{mit}.
5809 @cindex M680x0 syntax
5810 @cindex syntax, M680x0
5811 @cindex M680x0 size modifiers
5812 @cindex size modifiers, M680x0
5813 The 680x0 version of @code{@value{AS}} uses syntax compatible with the Sun
5814 assembler. Intervening periods are ignored; for example, @samp{movl} is
5815 equivalent to @samp{move.l}.
5818 If @code{@value{AS}} is compiled with SUN_ASM_SYNTAX defined, it
5819 also allows Sun-style local labels of the form @samp{1$} through
5823 In the following table @dfn{apc} stands for any of the address
5824 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
5825 Program Counter (@samp{pc}), or the zero-address relative to the
5826 program counter (@samp{zpc}).
5828 @cindex M680x0 addressing modes
5829 @cindex addressing modes, M680x0
5830 The following addressing modes are understood:
5833 @samp{#@var{digits}}
5836 @samp{d0} through @samp{d7}
5838 @item Address Register
5839 @samp{a0} through @samp{a7}@*
5840 @samp{a7} is also known as @samp{sp}, i.e. the Stack Pointer. @code{a6}
5841 is also known as @samp{fp}, the Frame Pointer.
5843 @item Address Register Indirect
5844 @samp{a0@@} through @samp{a7@@}
5846 @item Address Register Postincrement
5847 @samp{a0@@+} through @samp{a7@@+}
5849 @item Address Register Predecrement
5850 @samp{a0@@-} through @samp{a7@@-}
5852 @item Indirect Plus Offset
5853 @samp{@var{apc}@@(@var{digits})}
5856 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
5858 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
5861 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
5863 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
5866 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5868 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5870 @item Memory Indirect
5871 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
5874 @samp{@var{symbol}}, or @samp{@var{digits}}
5876 @c pesch@cygnus.com: gnu, rich concur the following needs careful
5877 @c research before documenting.
5878 , or either of the above followed
5879 by @samp{:b}, @samp{:w}, or @samp{:l}.
5883 For some configurations, especially those where the compiler normally
5884 does not prepend an underscore to the names of user variables, the
5885 assembler requires a @samp{%} before any use of a register name. This
5886 is intended to let the assembler distinguish between user variables and
5887 registers named @samp{a0} through @samp{a7}, and so on. The @samp{%} is
5888 always accepted, but is only required for some configurations, notably
5891 @node M68K-Moto-Syntax
5892 @section Motorola Syntax
5894 @cindex Motorola syntax for the 680x0
5895 @cindex alternate syntax for the 680x0
5897 The standard Motorola syntax for this chip differs from the syntax
5898 already discussed (@pxref{M68K-Syntax,,Syntax}). @code{@value{AS}} can
5899 accept both kinds of syntax, even within a single instruction. The
5900 two kinds of syntax are fully compatible.
5902 @c FIXME! I can't figure out what this means. Surely the "always" is in some
5903 @c restricted context, for instance. It's not necessary for the preceding text
5904 @c to explain this, so just ignore it for now; re-enable someday when someone
5905 @c has time to explain it better.
5906 , because the Motorola syntax never uses
5907 the @samp{@@} character and the @sc{mit} syntax always does, except in
5908 cases where the syntaxes are identical.
5911 @cindex M680x0 syntax
5912 @cindex syntax, M680x0
5913 In particular, you may write or generate M68K assembler with the
5914 following conventions:
5916 (In the following table @dfn{apc} stands for any of the address
5917 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
5918 Program Counter (@samp{pc}), or the zero-address relative to the
5919 program counter (@samp{zpc}).)
5921 @cindex M680x0 addressing modes
5922 @cindex addressing modes, M680x0
5923 The following additional addressing modes are understood:
5925 @item Address Register Indirect
5926 @samp{a0} through @samp{a7}@*
5927 @samp{a7} is also known as @samp{sp}, i.e. the Stack Pointer. @code{a6}
5928 is also known as @samp{fp}, the Frame Pointer.
5930 @item Address Register Postincrement
5931 @samp{(a0)+} through @samp{(a7)+}
5933 @item Address Register Predecrement
5934 @samp{-(a0)} through @samp{-(a7)}
5936 @item Indirect Plus Offset
5937 @samp{@var{digits}(@var{apc})}
5940 @samp{@var{digits}(@var{apc},(@var{register}.@var{size}*@var{scale})}@*
5941 or @samp{(@var{apc},@var{register}.@var{size}*@var{scale})}@*
5942 In either case, @var{size} and @var{scale} are optional
5943 (@var{scale} defaults to @samp{1}, @var{size} defaults to @samp{l}).
5944 @var{scale} can be @samp{1}, @samp{2}, @samp{4}, or @samp{8}.
5945 @var{size} can be @samp{w} or @samp{l}. @var{scale} is only supported
5946 on the 68020 and greater.
5950 @section Floating Point
5952 @cindex floating point, M680x0
5953 @cindex M680x0 floating point
5954 @c FIXME is this "not too well tested" crud STILL true?
5955 The floating point code is not too well tested, and may have
5958 Packed decimal (P) format floating literals are not supported.
5959 Feel free to add the code!
5961 The floating point formats generated by directives are these.
5965 @cindex @code{float} directive, M680x0
5966 @code{Single} precision floating point constants.
5969 @cindex @code{double} directive, M680x0
5970 @code{Double} precision floating point constants.
5973 There is no directive to produce regions of memory holding
5974 extended precision numbers, however they can be used as
5975 immediate operands to floating-point instructions. Adding a
5976 directive to create extended precision numbers would not be
5977 hard, but it has not yet seemed necessary.
5979 @node M68K-Directives
5980 @section 680x0 Machine Directives
5982 @cindex M680x0 directives
5983 @cindex directives, M680x0
5984 In order to be compatible with the Sun assembler the 680x0 assembler
5985 understands the following directives.
5989 @cindex @code{data1} directive, M680x0
5990 This directive is identical to a @code{.data 1} directive.
5993 @cindex @code{data2} directive, M680x0
5994 This directive is identical to a @code{.data 2} directive.
5997 @cindex @code{even} directive, M680x0
5998 This directive is identical to a @code{.align 1} directive.
5999 @c Is this true? does it work???
6002 @cindex @code{skip} directive, M680x0
6003 This directive is identical to a @code{.space} directive.
6009 @cindex M680x0 opcodes
6010 @cindex opcodes, M680x0
6011 @cindex instruction set, M680x0
6012 @c pesch@cygnus.com: I don't see any point in the following
6013 @c paragraph. Bugs are bugs; how does saying this
6016 Danger: Several bugs have been found in the opcode table (and
6017 fixed). More bugs may exist. Be careful when using obscure
6022 * M68K-Branch:: Branch Improvement
6023 * M68K-Chars:: Special Characters
6027 @subsection Branch Improvement
6029 @cindex pseudo-opcodes, M680x0
6030 @cindex M680x0 pseudo-opcodes
6031 @cindex branch improvement, M680x0
6032 @cindex M680x0 branch improvement
6033 Certain pseudo opcodes are permitted for branch instructions.
6034 They expand to the shortest branch instruction that reach the
6035 target. Generally these mnemonics are made by substituting @samp{j} for
6036 @samp{b} at the start of a Motorola mnemonic.
6038 The following table summarizes the pseudo-operations. A @code{*} flags
6039 cases that are more fully described after the table:
6043 +-------------------------------------------------
6045 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
6046 +-------------------------------------------------
6047 jbsr |bsrs bsr bsrl jsr jsr
6048 jra |bras bra bral jmp jmp
6049 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
6050 * dbXX |dbXX dbXX dbXX; bra; jmpl
6051 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
6054 NX: negative of condition XX
6057 @center @code{*}---see full description below
6062 These are the simplest jump pseudo-operations; they always map to one
6063 particular machine instruction, depending on the displacement to the
6067 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
6068 where @var{XX} is a conditional branch or condition-code test. The full
6069 list of pseudo-ops in this family is:
6071 jhi jls jcc jcs jne jeq jvc
6072 jvs jpl jmi jge jlt jgt jle
6075 For the cases of non-PC relative displacements and long displacements on
6076 the 68000 or 68010, @code{@value{AS}} issues a longer code fragment in terms of
6077 @var{NX}, the opposite condition to @var{XX}. For example, for the
6078 non-PC relative case:
6090 The full family of pseudo-operations covered here is
6092 dbhi dbls dbcc dbcs dbne dbeq dbvc
6093 dbvs dbpl dbmi dbge dblt dbgt dble
6097 Other than for word and byte displacements, when the source reads
6098 @samp{db@var{XX} foo}, @code{@value{AS}} emits
6107 This family includes
6109 fjne fjeq fjge fjlt fjgt fjle fjf
6110 fjt fjgl fjgle fjnge fjngl fjngle fjngt
6111 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
6112 fjor fjseq fjsf fjsne fjst fjueq fjuge
6113 fjugt fjule fjult fjun
6116 For branch targets that are not PC relative, @code{@value{AS}} emits
6122 when it encounters @samp{fj@var{XX} foo}.
6127 @subsection Special Characters
6129 @cindex special characters, M680x0
6130 @cindex M680x0 immediate character
6131 @cindex immediate character, M680x0
6132 @cindex M680x0 line comment character
6133 @cindex line comment character, M680x0
6134 @cindex comments, M680x0
6135 The immediate character is @samp{#} for Sun compatibility. The
6136 line-comment character is @samp{|}. If a @samp{#} appears at the
6137 beginning of a line, it is treated as a comment unless it looks like
6138 @samp{# line file}, in which case it is treated normally.
6142 @c FIXME! Stop ignoring when filled in.
6147 The 32x32 version of @code{@value{AS}} accepts a @samp{-m32032} option to
6148 specify thiat it is compiling for a 32032 processor, or a
6149 @samp{-m32532} to specify that it is compiling for a 32532 option.
6150 The default (if neither is specified) is chosen when the assembler
6154 I don't know anything about the 32x32 syntax assembled by
6155 @code{@value{AS}}. Someone who undersands the processor (I've never seen
6156 one) and the possible syntaxes should write this section.
6158 @section Floating Point
6159 The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{AS}}
6160 only creates single or double precision values. I don't know if the
6161 32x32 understands extended precision numbers.
6163 @section 32x32 Machine Directives
6164 The 32x32 has no machine dependent directives.
6170 @node Sparc-Dependent
6171 @chapter SPARC Dependent Features
6174 @node Machine Dependencies
6175 @chapter SPARC Dependent Features
6178 @cindex SPARC support
6180 * Sparc-Opts:: Options
6181 * Sparc-Float:: Floating Point
6182 * Sparc-Directives:: Sparc Machine Directives
6188 @cindex options for SPARC
6189 @cindex SPARC options
6190 @cindex architectures, SPARC
6191 @cindex SPARC architectures
6192 The SPARC chip family includes several successive levels (or other
6193 variants) of chip, using the same core instruction set, but including
6194 a few additional instructions at each level.
6196 By default, @code{@value{AS}} assumes the core instruction set (SPARC
6197 v6), but ``bumps'' the architecture level as needed: it switches to
6198 successively higher architectures as it encounters instructions that
6199 only exist in the higher levels.
6202 @item -Av6 | -Av7 | -Av8 | -Asparclite
6207 Use one of the @samp{-A} options to select one of the SPARC
6208 architectures explicitly. If you select an architecture explicitly,
6209 @code{@value{AS}} reports a fatal error if it encounters an instruction
6210 or feature requiring a higher level.
6213 Permit the assembler to ``bump'' the architecture level as required, but
6214 warn whenever it is necessary to switch to another level.
6218 @c FIXME: (sparc) Fill in "syntax" section!
6219 @c subsection syntax
6220 I don't know anything about Sparc syntax. Someone who does
6221 will have to write this section.
6225 @section Floating Point
6227 @cindex floating point, SPARC (@sc{ieee})
6228 @cindex SPARC floating point (@sc{ieee})
6229 The Sparc uses @sc{ieee} floating-point numbers.
6231 @node Sparc-Directives
6232 @section Sparc Machine Directives
6234 @cindex SPARC machine directives
6235 @cindex machine directives, SPARC
6236 The Sparc version of @code{@value{AS}} supports the following additional
6241 @cindex @code{common} directive, SPARC
6242 This must be followed by a symbol name, a positive number, and
6243 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
6244 syntax is different.
6247 @cindex @code{half} directive, SPARC
6248 This is functionally identical to @code{.short}.
6251 @cindex @code{proc} directive, SPARC
6252 This directive is ignored. Any text following it on the same
6253 line is also ignored.
6256 @cindex @code{reserve} directive, SPARC
6257 This must be followed by a symbol name, a positive number, and
6258 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
6259 syntax is different.
6262 @cindex @code{seg} directive, SPARC
6263 This must be followed by @code{"text"}, @code{"data"}, or
6264 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
6268 @cindex @code{skip} directive, SPARC
6269 This is functionally identical to the @code{.space} directive.
6272 @cindex @code{word} directive, SPARC
6273 On the Sparc, the .word directive produces 32 bit values,
6274 instead of the 16 bit values it produces on many other machines.
6281 @node i386-Dependent
6282 @chapter 80386 Dependent Features
6285 @node Machine Dependencies
6286 @chapter 80386 Dependent Features
6289 @cindex i386 support
6290 @cindex i80306 support
6292 * i386-Options:: Options
6293 * i386-Syntax:: AT&T Syntax versus Intel Syntax
6294 * i386-Opcodes:: Opcode Naming
6295 * i386-Regs:: Register Naming
6296 * i386-prefixes:: Opcode Prefixes
6297 * i386-Memory:: Memory References
6298 * i386-jumps:: Handling of Jump Instructions
6299 * i386-Float:: Floating Point
6300 * i386-Notes:: Notes
6306 @cindex options for i386 (none)
6307 @cindex i386 options (none)
6308 The 80386 has no machine dependent options.
6311 @section AT&T Syntax versus Intel Syntax
6313 @cindex i386 syntax compatibility
6314 @cindex syntax compatibility, i386
6315 In order to maintain compatibility with the output of @code{@value{GCC}},
6316 @code{@value{AS}} supports AT&T System V/386 assembler syntax. This is quite
6317 different from Intel syntax. We mention these differences because
6318 almost all 80386 documents used only Intel syntax. Notable differences
6319 between the two syntaxes are:
6323 @cindex immediate operands, i386
6324 @cindex i386 immediate operands
6325 @cindex register operands, i386
6326 @cindex i386 register operands
6327 @cindex jump/call operands, i386
6328 @cindex i386 jump/call operands
6329 @cindex operand delimiters, i386
6330 AT&T immediate operands are preceded by @samp{$}; Intel immediate
6331 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
6332 AT&T register operands are preceded by @samp{%}; Intel register operands
6333 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
6334 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
6337 @cindex i386 source, destination operands
6338 @cindex source, destination operands; i386
6339 AT&T and Intel syntax use the opposite order for source and destination
6340 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
6341 @samp{source, dest} convention is maintained for compatibility with
6342 previous Unix assemblers.
6345 @cindex opcode suffixes, i386
6346 @cindex sizes operands, i386
6347 @cindex i386 size suffixes
6348 In AT&T syntax the size of memory operands is determined from the last
6349 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
6350 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
6351 memory references. Intel syntax accomplishes this by prefixes memory
6352 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
6353 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
6354 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
6357 @cindex return instructions, i386
6358 @cindex i386 jump, call, return
6359 Immediate form long jumps and calls are
6360 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
6362 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
6364 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
6365 @samp{ret far @var{stack-adjust}}.
6368 @cindex sections, i386
6369 @cindex i386 sections
6370 The AT&T assembler does not provide support for multiple section
6371 programs. Unix style systems expect all programs to be single sections.
6375 @section Opcode Naming
6377 @cindex i386 opcode naming
6378 @cindex opcode naming, i386
6379 Opcode names are suffixed with one character modifiers which specify the
6380 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
6381 byte, word, and long operands. If no suffix is specified by an
6382 instruction and it contains no memory operands then @code{@value{AS}} tries to
6383 fill in the missing suffix based on the destination register operand
6384 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
6385 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
6386 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
6387 assembler which assumes that a missing opcode suffix implies long
6388 operand size. (This incompatibility does not affect compiler output
6389 since compilers always explicitly specify the opcode suffix.)
6391 Almost all opcodes have the same names in AT&T and Intel format. There
6392 are a few exceptions. The sign extend and zero extend instructions need
6393 two sizes to specify them. They need a size to sign/zero extend
6394 @emph{from} and a size to zero extend @emph{to}. This is accomplished
6395 by using two opcode suffixes in AT&T syntax. Base names for sign extend
6396 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
6397 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
6398 suffixes are tacked on to this base name, the @emph{from} suffix before
6399 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
6400 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
6401 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
6402 and @samp{wl} (from word to long).
6404 @cindex conversion instructions, i386
6405 @cindex i386 conversion instructions
6406 The Intel-syntax conversion instructions
6410 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
6413 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
6416 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
6419 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
6423 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
6424 AT&T naming. @code{@value{AS}} accepts either naming for these instructions.
6426 @cindex jump instructions, i386
6427 @cindex call instructions, i386
6428 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
6429 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
6433 @section Register Naming
6435 @cindex i386 registers
6436 @cindex registers, i386
6437 Register operands are always prefixes with @samp{%}. The 80386 registers
6442 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
6443 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
6444 frame pointer), and @samp{%esp} (the stack pointer).
6447 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
6448 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
6451 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
6452 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
6453 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
6454 @samp{%cx}, and @samp{%dx})
6457 the 6 section registers @samp{%cs} (code section), @samp{%ds}
6458 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
6462 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
6466 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
6467 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
6470 the 2 test registers @samp{%tr6} and @samp{%tr7}.
6473 the 8 floating point register stack @samp{%st} or equivalently
6474 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
6475 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
6479 @section Opcode Prefixes
6481 @cindex i386 opcode prefixes
6482 @cindex opcode prefixes, i386
6483 @cindex prefixes, i386
6484 Opcode prefixes are used to modify the following opcode. They are used
6485 to repeat string instructions, to provide section overrides, to perform
6486 bus lock operations, and to give operand and address size (16-bit
6487 operands are specified in an instruction by prefixing what would
6488 normally be 32-bit operands with a ``operand size'' opcode prefix).
6489 Opcode prefixes are usually given as single-line instructions with no
6490 operands, and must directly precede the instruction they act upon. For
6491 example, the @samp{scas} (scan string) instruction is repeated with:
6497 Here is a list of opcode prefixes:
6501 @cindex section override prefixes, i386
6502 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
6503 @samp{fs}, @samp{gs}. These are automatically added by specifying
6504 using the @var{section}:@var{memory-operand} form for memory references.
6507 @cindex size prefixes, i386
6508 Operand/Address size prefixes @samp{data16} and @samp{addr16}
6509 change 32-bit operands/addresses into 16-bit operands/addresses. Note
6510 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
6511 are not supported (yet).
6514 @cindex bus lock prefixes, i386
6515 @cindex inhibiting interrupts, i386
6516 The bus lock prefix @samp{lock} inhibits interrupts during
6517 execution of the instruction it precedes. (This is only valid with
6518 certain instructions; see a 80386 manual for details).
6521 @cindex coprocessor wait, i386
6522 The wait for coprocessor prefix @samp{wait} waits for the
6523 coprocessor to complete the current instruction. This should never be
6524 needed for the 80386/80387 combination.
6527 @cindex repeat prefixes, i386
6528 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
6529 to string instructions to make them repeat @samp{%ecx} times.
6533 @section Memory References
6535 @cindex i386 memory references
6536 @cindex memory references, i386
6537 An Intel syntax indirect memory reference of the form
6540 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
6544 is translated into the AT&T syntax
6547 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
6551 where @var{base} and @var{index} are the optional 32-bit base and
6552 index registers, @var{disp} is the optional displacement, and
6553 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
6554 to calculate the address of the operand. If no @var{scale} is
6555 specified, @var{scale} is taken to be 1. @var{section} specifies the
6556 optional section register for the memory operand, and may override the
6557 default section register (see a 80386 manual for section register
6558 defaults). Note that section overrides in AT&T syntax @emph{must} have
6559 be preceded by a @samp{%}. If you specify a section override which
6560 coincides with the default section register, @code{@value{AS}} does @emph{not}
6561 output any section register override prefixes to assemble the given
6562 instruction. Thus, section overrides can be specified to emphasize which
6563 section register is used for a given memory operand.
6565 Here are some examples of Intel and AT&T style memory references:
6568 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
6569 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
6570 missing, and the default section is used (@samp{%ss} for addressing with
6571 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
6573 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
6574 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
6575 @samp{foo}. All other fields are missing. The section register here
6576 defaults to @samp{%ds}.
6578 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
6579 This uses the value pointed to by @samp{foo} as a memory operand.
6580 Note that @var{base} and @var{index} are both missing, but there is only
6581 @emph{one} @samp{,}. This is a syntactic exception.
6583 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
6584 This selects the contents of the variable @samp{foo} with section
6585 register @var{section} being @samp{%gs}.
6588 Absolute (as opposed to PC relative) call and jump operands must be
6589 prefixed with @samp{*}. If no @samp{*} is specified, @code{@value{AS}}
6590 always chooses PC relative addressing for jump/call labels.
6592 Any instruction that has a memory operand @emph{must} specify its size (byte,
6593 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
6597 @section Handling of Jump Instructions
6599 @cindex jump optimization, i386
6600 @cindex i386 jump optimization
6601 Jump instructions are always optimized to use the smallest possible
6602 displacements. This is accomplished by using byte (8-bit) displacement
6603 jumps whenever the target is sufficiently close. If a byte displacement
6604 is insufficient a long (32-bit) displacement is used. We do not support
6605 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
6606 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
6607 @samp{%eip} to 16 bits after the word displacement is added.
6609 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
6610 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in byte
6611 displacements, so that if you use these instructions (@code{@value{GCC}} does
6612 not use them) you may get an error message (and incorrect code). The AT&T
6613 80386 assembler tries to get around this problem by expanding @samp{jcxz foo}
6624 @section Floating Point
6626 @cindex i386 floating point
6627 @cindex floating point, i386
6628 All 80387 floating point types except packed BCD are supported.
6629 (BCD support may be added without much difficulty). These data
6630 types are 16-, 32-, and 64- bit integers, and single (32-bit),
6631 double (64-bit), and extended (80-bit) precision floating point.
6632 Each supported type has an opcode suffix and a constructor
6633 associated with it. Opcode suffixes specify operand's data
6634 types. Constructors build these data types into memory.
6638 @cindex @code{float} directive, i386
6639 @cindex @code{single} directive, i386
6640 @cindex @code{double} directive, i386
6641 @cindex @code{tfloat} directive, i386
6642 Floating point constructors are @samp{.float} or @samp{.single},
6643 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
6644 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
6645 @samp{t} stands for temporary real, and that the 80387 only supports
6646 this format via the @samp{fldt} (load temporary real to stack top) and
6647 @samp{fstpt} (store temporary real and pop stack) instructions.
6650 @cindex @code{word} directive, i386
6651 @cindex @code{long} directive, i386
6652 @cindex @code{int} directive, i386
6653 @cindex @code{quad} directive, i386
6654 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
6655 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
6656 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
6657 (quad). As with the temporary real format the 64-bit @samp{q} format is
6658 only present in the @samp{fildq} (load quad integer to stack top) and
6659 @samp{fistpq} (store quad integer and pop stack) instructions.
6662 Register to register operations do not require opcode suffixes,
6663 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
6665 @cindex i386 @code{fwait} instruction
6666 @cindex @code{fwait instruction}, i386
6667 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
6668 instructions are almost never needed (this is not the case for the
6669 80286/80287 and 8086/8087 combinations). Therefore, @code{@value{AS}} suppresses
6670 the @samp{fwait} instruction whenever it is implicitly selected by one
6671 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
6672 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
6673 instructions are made equivalent to @samp{f@dots{}} instructions. If
6674 @samp{fwait} is desired it must be explicitly coded.
6679 @cindex i386 @code{mul}, @code{imul} instructions
6680 @cindex @code{mul} instruction, i386
6681 @cindex @code{imul} instruction, i386
6682 There is some trickery concerning the @samp{mul} and @samp{imul}
6683 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
6684 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
6685 for @samp{imul}) can be output only in the one operand form. Thus,
6686 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
6687 the expanding multiply would clobber the @samp{%edx} register, and this
6688 would confuse @code{@value{GCC}} output. Use @samp{imul %ebx} to get the
6689 64-bit product in @samp{%edx:%eax}.
6691 We have added a two operand form of @samp{imul} when the first operand
6692 is an immediate mode expression and the second operand is a register.
6693 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
6694 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
6701 @node Z8000-Dependent
6702 @chapter Z8000 Dependent Features
6705 @node Machine Dependencies
6706 @chapter Z8000 Dependent Features
6709 @cindex Z8000 support
6710 The Z8000 @value{AS} supports both members of the Z8000 family: the
6711 unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with
6714 When the assembler is in unsegmented mode (specified with the
6715 @code{unsegm} directive), an address takes up one word (16 bit)
6716 sized register. When the assembler is in segmented mode (specified with
6717 the @code{segm} directive), a 24-bit address takes up a long (32 bit)
6718 register. @xref{Z8000 Directives,,Assembler Directives for the Z8000},
6719 for a list of other Z8000 specific assembler directives.
6722 * Z8000 Options:: No special command-line options for Z8000
6723 * Z8000 Syntax:: Assembler syntax for the Z8000
6724 * Z8000 Directives:: Special directives for the Z8000
6725 * Z8000 Opcodes:: Opcodes
6731 @cindex Z8000 options
6732 @cindex options, Z8000
6733 @code{@value{AS}} has no additional command-line options for the Zilog
6739 * Z8000-Chars:: Special Characters
6740 * Z8000-Regs:: Register Names
6741 * Z8000-Addressing:: Addressing Modes
6745 @subsection Special Characters
6747 @cindex line comment character, Z8000
6748 @cindex Z8000 line comment character
6749 @samp{!} is the line comment character.
6751 @cindex line separator, Z8000
6752 @cindex statement separator, Z8000
6753 @cindex Z8000 line separator
6754 You can use @samp{;} instead of a newline to separate statements.
6757 @subsection Register Names
6759 @cindex Z8000 registers
6760 @cindex registers, Z8000
6761 The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer
6762 to different sized groups of registers by register number, with the
6763 prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and
6764 @samp{rq} for 64 bit registers. You can also refer to the contents of
6765 the first eight (of the sixteen 16 bit registers) by bytes. They are
6766 named @samp{r@var{n}h} and @samp{r@var{n}l}.
6769 @exdent @emph{byte registers}
6770 r0l r0h r1h r1l r2h r2l r3h r3l
6771 r4h r4l r5h r5l r6h r6l r7h r7l
6773 @exdent @emph{word registers}
6774 r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15
6776 @exdent @emph{long word registers}
6777 rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14
6779 @exdent @emph{quad word registers}
6783 @node Z8000-Addressing
6784 @subsection Addressing Modes
6786 @cindex addressing modes, Z8000
6787 @cindex Z800 addressing modes
6788 @value{AS} understands the following addressing modes for the Z8000:
6798 Direct: the 16 bit or 24 bit address (depending on whether the assembler
6799 is in segmented or unsegmented mode) of the operand is in the instruction.
6801 @item address(r@var{n})
6802 Indexed: the 16 or 24 bit address is added to the 16 bit register to produce
6803 the final address in memory of the operand.
6805 @item r@var{n}(#@var{imm})
6806 Base Address: the 16 or 24 bit register is added to the 16 bit sign
6807 extended immediate displacement to produce the final address in memory
6810 @item r@var{n}(r@var{m})
6811 Base Index: the 16 or 24 bit register r@var{n} is added to the sign
6812 extended 16 bit index register r@var{m} to produce the final address in
6813 memory of the operand.
6816 Immediate data @var{xx}.
6819 @node Z8000 Directives
6820 @section Assembler Directives for the Z8000
6822 @cindex Z8000 directives
6823 @cindex directives, Z8000
6824 The Z8000 port of @value{AS} includes these additional assembler directives,
6825 for compatibility with other Z8000 assemblers. As shown, these do not
6826 begin with @samp{.} (unlike the ordinary @value{AS} directives).
6831 Generates code for the segmented Z8001.
6835 Generates code for the unsegmented Z8002.
6839 Synonym for @code{.file}
6843 Synonum for @code{.global}
6847 Synonym for @code{.word}
6851 Synonym for @code{.long}
6855 Synonym for @code{.byte}
6859 Assemble a string. @code{sval} expects one string literal, delimited by
6860 single quotes. It assembles each byte of the string into consecutive
6861 addresses. You can use the escape sequence @samp{%@var{xx}} (where
6862 @var{xx} represents a two-digit hexadecimal number) to represent the
6863 character whose @sc{ascii} value is @var{xx}. Use this feature to
6864 describe single quote and other characters that may not appear in string
6865 literals as themselves. For example, the C statement @w{@samp{char *a =
6866 "he said \"it's 50% off\"";}} is represented in Z8000 assembly language
6867 (shown with the assembler output in hex at the left) as
6871 @let@nonarrowing=@comment
6874 68652073 sval 'he said %22it%27s 50%25 off%22%00'
6887 synonym for @code{.section}
6891 synonym for @code{.space}
6895 synonym for @code{.align 1}
6901 @cindex Z8000 opcode summary
6902 @cindex opcode summary, Z8000
6903 @cindex mnemonics, Z8000
6904 @cindex instruction summary, Z8000
6905 For detailed information on the Z8000 machine instruction set, see
6906 @cite{Z8000 Technical Manual}.
6908 The following table summarizes the opcodes and their arguments:
6911 @let@nonarrowing=@comment
6915 rs @r{16 bit source register}
6916 rd @r{16 bit destination register}
6917 rbs @r{8 bit source register}
6918 rbd @r{8 bit destination register}
6919 rrs @r{32 bit source register}
6920 rrd @r{32 bit destination register}
6921 rqs @r{64 bit source register}
6922 rqd @r{64 bit destination register}
6923 addr @r{16/24 bit address}
6924 imm @r{immediate data}
6926 adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc
6927 adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc
6928 add rd,@@rs clrb rbd dab rbd
6929 add rd,addr com @@rd dbjnz rbd,disp7
6930 add rd,addr(rs) com addr dec @@rd,imm4m1
6931 add rd,imm16 com addr(rd) dec addr(rd),imm4m1
6932 add rd,rs com rd dec addr,imm4m1
6933 addb rbd,@@rs comb @@rd dec rd,imm4m1
6934 addb rbd,addr comb addr decb @@rd,imm4m1
6935 addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1
6936 addb rbd,imm8 comb rbd decb addr,imm4m1
6937 addb rbd,rbs comflg flags decb rbd,imm4m1
6938 addl rrd,@@rs cp @@rd,imm16 di i2
6939 addl rrd,addr cp addr(rd),imm16 div rrd,@@rs
6940 addl rrd,addr(rs) cp addr,imm16 div rrd,addr
6941 addl rrd,imm32 cp rd,@@rs div rrd,addr(rs)
6942 addl rrd,rrs cp rd,addr div rrd,imm16
6943 and rd,@@rs cp rd,addr(rs) div rrd,rs
6944 and rd,addr cp rd,imm16 divl rqd,@@rs
6945 and rd,addr(rs) cp rd,rs divl rqd,addr
6946 and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs)
6947 and rd,rs cpb addr(rd),imm8 divl rqd,imm32
6948 andb rbd,@@rs cpb addr,imm8 divl rqd,rrs
6949 andb rbd,addr cpb rbd,@@rs djnz rd,disp7
6950 andb rbd,addr(rs) cpb rbd,addr ei i2
6951 andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs
6952 andb rbd,rbs cpb rbd,imm8 ex rd,addr
6953 bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs)
6954 bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs
6955 bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs
6956 bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr
6957 bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs)
6958 bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs
6959 bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8
6960 bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8
6961 bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8
6962 bitb rbd,rs cpl rrd,@@rs ext8f imm8
6963 bpt cpl rrd,addr exts rrd
6964 call @@rd cpl rrd,addr(rs) extsb rd
6965 call addr cpl rrd,imm32 extsl rqd
6966 call addr(rd) cpl rrd,rrs halt
6967 calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs
6968 clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16
6969 clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs
6970 clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16
6971 clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1
6972 clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1
6973 inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs)
6974 inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16
6975 incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs
6976 incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs
6977 incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr
6978 incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs)
6979 ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32
6980 indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs
6981 inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd
6982 inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr
6983 iret ldib @@rd,@@rs,rr neg addr(rd)
6984 jp cc,@@rd ldir @@rd,@@rs,rr neg rd
6985 jp cc,addr ldirb @@rd,@@rs,rr negb @@rd
6986 jp cc,addr(rd) ldk rd,imm4 negb addr
6987 jr cc,disp8 ldl @@rd,rrs negb addr(rd)
6988 ld @@rd,imm16 ldl addr(rd),rrs negb rbd
6989 ld @@rd,rs ldl addr,rrs nop
6990 ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs
6991 ld addr(rd),rs ldl rd(rx),rrs or rd,addr
6992 ld addr,imm16 ldl rrd,@@rs or rd,addr(rs)
6993 ld addr,rs ldl rrd,addr or rd,imm16
6994 ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs
6995 ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs
6996 ld rd,@@rs ldl rrd,rrs orb rbd,addr
6997 ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs)
6998 ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8
6999 ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs
7000 ld rd,rs ldm addr(rd),rs,n out @@rd,rs
7001 ld rd,rs(imm16) ldm addr,rs,n out imm16,rs
7002 ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs
7003 lda rd,addr ldm rd,addr(rs),n outb imm16,rbs
7004 lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra
7005 lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba
7006 lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra
7007 ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra
7008 ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs
7009 ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs
7010 ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs
7011 ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs
7012 ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs
7013 ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs
7014 ldb rbd,@@rs mbit popl addr,@@rs
7015 ldb rbd,addr mreq rd popl rrd,@@rs
7016 ldb rbd,addr(rs) mres push @@rd,@@rs
7017 ldb rbd,imm8 mset push @@rd,addr
7018 ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs)
7019 ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16
7020 push @@rd,rs set addr,imm4 subl rrd,imm32
7021 pushl @@rd,@@rs set rd,imm4 subl rrd,rrs
7022 pushl @@rd,addr set rd,rs tcc cc,rd
7023 pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd
7024 pushl @@rd,rrs setb addr(rd),imm4 test @@rd
7025 res @@rd,imm4 setb addr,imm4 test addr
7026 res addr(rd),imm4 setb rbd,imm4 test addr(rd)
7027 res addr,imm4 setb rbd,rs test rd
7028 res rd,imm4 setflg imm4 testb @@rd
7029 res rd,rs sinb rbd,imm16 testb addr
7030 resb @@rd,imm4 sinb rd,imm16 testb addr(rd)
7031 resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd
7032 resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd
7033 resb rbd,imm4 sinib @@rd,@@rs,ra testl addr
7034 resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd)
7035 resflg imm4 sla rd,imm8 testl rrd
7036 ret cc slab rbd,imm8 trdb @@rd,@@rs,rba
7037 rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba
7038 rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr
7039 rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr
7040 rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr
7041 rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr
7042 rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr
7043 rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr
7044 rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd
7045 rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr
7046 rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd)
7047 rsvd36 sra rd,imm8 tset rd
7048 rsvd38 srab rbd,imm8 tsetb @@rd
7049 rsvd78 sral rrd,imm8 tsetb addr
7050 rsvd7e srl rd,imm8 tsetb addr(rd)
7051 rsvd9d srlb rbd,imm8 tsetb rbd
7052 rsvd9f srll rrd,imm8 xor rd,@@rs
7053 rsvdb9 sub rd,@@rs xor rd,addr
7054 rsvdbf sub rd,addr xor rd,addr(rs)
7055 sbc rd,rs sub rd,addr(rs) xor rd,imm16
7056 sbcb rbd,rbs sub rd,imm16 xor rd,rs
7057 sc imm8 sub rd,rs xorb rbd,@@rs
7058 sda rd,rs subb rbd,@@rs xorb rbd,addr
7059 sdab rbd,rs subb rbd,addr xorb rbd,addr(rs)
7060 sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8
7061 sdl rd,rs subb rbd,imm8 xorb rbd,rbs
7062 sdlb rbd,rs subb rbd,rbs xorb rbd,rbs
7063 sdll rrd,rs subl rrd,@@rs
7064 set @@rd,imm4 subl rrd,addr
7065 set addr(rd),imm4 subl rrd,addr(rs)
7076 @node MIPS-Dependent
7077 @chapter MIPS Dependent Features
7080 @node Machine Dependencies
7081 @chapter MIPS Dependent Features
7083 The MIPS @value{AS} supports the MIPS R2000 and R3000 processors.
7085 It ignores the @samp{-nocpp} option.
7087 Not all traditional MIPS macro instructions are currently supported.
7088 Specifically, @code{li.d} and @code{li.s} are not currently supported.
7090 Assembling for a MIPS ECOFF target supports some additional sections
7091 besides the usual @code{.text}, @code{.data} and @code{.bss}. The
7092 additional sections are @code{.rdata}, used for read-only data,
7093 @code{.sdata}, used for small data, and @code{.sbss}, used for small
7096 When assembling for ECOFF, the assembler automatically uses the @code{$gp}
7097 (@code{$28}) register when forming the address of a small object. Any object
7098 in the @code{.sdata} or @code{.sbss} sections is considered ``small''. For
7099 external objects or objects in the @code{.bss} section, you may use the
7100 @samp{-G} option to control the size of objects for which the @code{$gp}
7101 register is used; the default value is 8, meaning that a reference to any
7102 object eight bytes or smaller uses @code{$gp}. Passing @samp{-G 0} to
7103 @value{AS} prevents it from using the @code{$gp} register at all. The size of
7104 an object in the @code{.bss} section is set by the @code{.comm} or
7105 @code{.lcomm} directive that defines it. The size of an external object may be
7106 set using the @code{.extern} directive. For example, @samp{.extern sym,4}
7107 declares that the object at @code{sym} is 4 bytes in length, while leaving
7108 @code{sym} otherwise undefined.
7110 Using small ECOFF objects requires linker support, and assumes that the
7111 @code{$gp} register was initialized correctly (normally done automatically
7112 by the startup code). MIPS ECOFF assembly code must avoid modifying the
7113 @code{$gp} register.
7115 MIPS ECOFF @code{@value{AS}} supports several directives used for generating
7116 debugging information which are not support by traditional MIPS
7117 assemblers. These are @code{.def}, @code{.endef}, @code{.dim},
7118 @code{.file}, @code{.scl}, @code{.size}, @code{.tag}, @code{.type},
7119 @code{.val}, @code{.stabd}, @code{.stabn}, and @code{.stabs}. The
7120 debugging information generated by the three @code{.stab} directives can
7121 only be read by GDB, not by traditional MIPS debuggers (this enhancement
7122 is required to fully support C++ debugging). These directives are
7123 primarily used by compilers, not assembly language programmers, and are
7124 described elsewhere in this manual.
7128 @c reverse effect of @down at top of generic Machine-Dep chapter
7132 @node Acknowledgements
7133 @chapter Acknowledgements
7135 If you have contributed to @code{@value{AS}} and your name isn't listed here,
7136 it is not meant as a slight. We just don't know about it. Send mail to the
7137 maintainer, and we'll correct the situation. Currently (January 1994), the
7138 maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
7140 Dean Elsner wrote the original GNU assembler for the VAX.@footnote{Any more
7143 Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
7144 information and the 68k series machines, most of the preprocessing pass, and
7145 extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}.
7147 K. Richard Pixley maintained GAS for a while, adding various enhancements and
7148 many bug fixes, including merging support for several processors, breaking GAS
7149 up to handle multiple object file format back ends (including heavy rewrite,
7150 testing, an integration of the coff and b.out back ends), adding configuration
7151 including heavy testing and verification of cross assemblers and file splits
7152 and renaming, converted GAS to strictly ANSI C including full prototypes, added
7153 support for m680[34]0 and cpu32, did considerable work on i960 including a COFF
7154 port (including considerable amounts of reverse engineering), a SPARC opcode
7155 file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know''
7156 assertions and made them work, much other reorganization, cleanup, and lint.
7158 Ken Raeburn wrote the high-level BFD interface code to replace most of the code
7159 in format-specific I/O modules.
7161 The original VMS support was contributed by David L. Kashtan. Eric Youngdale
7162 has done much work with it since.
7164 The Intel 80386 machine description was written by Eliot Dresselhaus.
7166 Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
7168 The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
7169 University and Torbjorn Granlund of the Swedish Institute of Computer Science.
7171 Keith Knowles at the Open Software Foundation wrote the original MIPS back end
7172 (@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support
7173 (which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to
7174 support a.out format.
7176 Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k,
7177 tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
7178 Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
7179 use BFD for some low-level operations, for use with the H8/300 and AMD 29k
7182 John Gilmore built the AMD 29000 support, added @code{.include} support, and
7183 simplified the configuration of which versions accept which directives. He
7184 updated the 68k machine description so that Motorola's opcodes always produced
7185 fixed-size instructions (e.g. @code{jsr}), while synthetic instructions
7186 remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested
7187 cross-compilation support, and one bug in relaxation that took a week and
7188 required the proverbial one-bit fix.
7190 Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
7191 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
7192 and made a few other minor patches.
7194 Steve Chamberlain made @code{@value{AS}} able to generate listings.
7196 Hewlett-Packard contributed support for the HP9000/300.
7198 Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
7199 along with a fairly extensive HPPA testsuite (for both SOM and ELF object
7200 formats). This work was supported by both the Center for Software Science at
7201 the University of Utah and Cygnus Support.
7203 Support for ELF format files has been worked on by Mark Eichin of Cygnus
7204 Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
7205 Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
7206 Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
7207 and some initial 64-bit support).
7209 Several engineers at Cygnus Support have also provided many small bug fixes and
7210 configuration enhancements.
7212 Many others have contributed large or small bugfixes and enhancements. If
7213 you have contributed significant work and are not mentioned on this list, and
7214 want to be, let us know. Some of the history has been lost; we are not
7215 intentionally leaving anyone out.
7220 @include gpl.texinfo