1 \input texinfo @c -*-Texinfo-*-
2 @c Copyright (c) 1991 1992 1993 Free Software Foundation, Inc.
6 @c defaults, config file may override:
9 @include asdoc-config.texi
11 @c common OR combinations of conditions
28 @set abnormal-separator
32 @settitle Using @value{AS}
35 @settitle Using @value{AS} (@value{TARGET})
37 @setchapternewpage odd
43 * As: (as). The GNU assembler.
52 This file documents the GNU Assembler "@value{AS}".
54 Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc.
56 Permission is granted to make and distribute verbatim copies of
57 this manual provided the copyright notice and this permission notice
58 are preserved on all copies.
61 Permission is granted to process this file through Tex and print the
62 results, provided the printed document carries copying permission
63 notice identical to this one except for the removal of this paragraph
64 (this paragraph not being relevant to the printed manual).
67 Permission is granted to copy and distribute modified versions of this
68 manual under the conditions for verbatim copying, provided also that the
69 section entitled ``GNU General Public License'' is included exactly as
70 in the original, and provided that the entire resulting derived work is
71 distributed under the terms of a permission notice identical to this
74 Permission is granted to copy and distribute translations of this manual
75 into another language, under the above conditions for modified versions,
76 except that the section entitled ``GNU General Public License'' may be
77 included in a translation approved by the Free Software Foundation
78 instead of in the original English.
82 @title Using @value{AS}
83 @subtitle The GNU Assembler
85 @subtitle for the @value{TARGET} family
91 The Free Software Foundation Inc. thanks The Nice Computer
92 Company of Australia for loaning Dean Elsner to write the
93 first (Vax) version of @code{as} for Project GNU.
94 The proprietors, management and staff of TNCCA thank FSF for
95 distracting the boss while they got some work
98 @author Dean Elsner, Jay Fenlason & friends
102 \hfill {\it Using {\tt @value{AS}}}\par
103 \hfill Edited by Roland Pesch for Cygnus Support\par
105 %"boxit" macro for figures:
106 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
107 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
108 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
109 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
110 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
113 @vskip 0pt plus 1filll
114 Copyright @copyright{} 1991, 1992, 1993 Free Software Foundation, Inc.
116 Permission is granted to make and distribute verbatim copies of
117 this manual provided the copyright notice and this permission notice
118 are preserved on all copies.
120 Permission is granted to copy and distribute modified versions of this
121 manual under the conditions for verbatim copying, provided also that the
122 section entitled ``GNU General Public License'' is included exactly as
123 in the original, and provided that the entire resulting derived work is
124 distributed under the terms of a permission notice identical to this
127 Permission is granted to copy and distribute translations of this manual
128 into another language, under the above conditions for modified versions,
129 except that the section entitled ``GNU General Public License'' may be
130 included in a translation approved by the Free Software Foundation
131 instead of in the original English.
136 @top Using @value{AS}
138 This file is a user guide to the GNU assembler @code{@value{AS}}.
140 This version of the file describes @code{@value{AS}} configured to generate
141 code for @value{TARGET} architectures.
144 * Overview:: Overview
145 * Invoking:: Command-Line Options
147 * Sections:: Sections and Relocation
149 * Expressions:: Expressions
150 * Pseudo Ops:: Assembler Directives
151 * Machine Dependencies:: Machine Dependent Features
153 * Copying:: GNU GENERAL PUBLIC LICENSE
156 * Acknowledgements:: Who Did What
165 This manual is a user guide to the GNU assembler @code{@value{AS}}.
167 This version of the manual describes @code{@value{AS}} configured to generate
168 code for @value{TARGET} architectures.
172 @cindex invocation summary
173 @cindex option summary
174 @cindex summary of options
175 Here is a brief summary of how to invoke @code{@value{AS}}. For details,
176 @pxref{Invoking,,Comand-Line Options}.
178 @c We don't use deffn and friends for the following because they seem
179 @c to be limited to one line for the header.
181 @value{AS} [ -a[dhlns] ] [ -D ] [ -f ]
182 [ -I @var{path} ] [ -K ] [ -L ]
183 [ -o @var{objfile} ] [ -R ] [ -v ] [ -w ]
185 @c am29k has no machine-dependent assembler options
188 @c Hitachi family chips have no machine-dependent assembler options
191 @c HPPA has no machine-dependent assembler options (yet).
194 [ -Av6 | -Av7 | -Av8 | -Asparclite | -bump ]
197 @c Z8000 has no machine-dependent assembler options
200 @c see md_parse_option in tc-i960.c
201 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
205 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
208 [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ]
210 [ -- | @var{files} @dots{} ]
215 Turn on listings, in any of a variety of ways:
219 omit debugging directives from listing
222 include high-level source
234 You may combine these options; for example, use @samp{-aln} for assembly
235 listing without forms processing. By itself, @samp{-a} defaults to
236 @samp{-ahls}---that is, all listings turned on.
239 This option is accepted only for script compatibility with calls to
240 other assemblers; it has no effect on @code{@value{AS}}.
243 ``fast''---skip whitespace and comment preprocessing (assume source is
247 Add @var{path} to the search list for @code{.include} directives
250 @ifclear DIFF-TBL-KLUGE
251 This option is accepted but has no effect on the @value{TARGET} family.
253 @ifset DIFF-TBL-KLUGE
254 Issue warnings when difference tables altered for long displacements.
258 Keep (in symbol table) local symbols, starting with @samp{L}
260 @item -o @var{objfile}
261 Name the object-file output from @code{@value{AS}}
264 Fold data section into text section
267 Announce @code{as} version
270 Suppress warning messages
272 @item -- | @var{files} @dots{}
273 Standard input, or source files to assemble.
278 The following options are available when @value{AS} is configured for the
279 Intel 80960 processor.
282 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
283 Specify which variant of the 960 architecture is the target.
286 Add code to collect statistics about branches taken.
289 Do not alter compare-and-branch instructions for long displacements;
296 The following options are available when @value{AS} is configured for the
297 Motorola 68000 series.
302 Shorten references to undefined symbols, to one word instead of two.
304 @item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040
305 @itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32
306 Specify what processor in the 68000 family is the target. The default
307 is normally the 68020, but this can be changed at configuration time.
309 @item -m68881 | -m68882 | -mno-68881 | -mno-68882
310 The target machine does (or does not) have a floating-point coprocessor.
311 The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
312 the basic 68000 is not compatible with the 68881, a combination of the
313 two can be specified, since it's possible to do emulation of the
314 coprocessor instructions with the main processor.
316 @item -m68851 | -mno-68851
317 The target machine does (or does not) have a memory-management
318 unit coprocessor. The default is to assume an MMU for 68020 and up.
324 The following options are available when @code{@value{AS}} is configured
325 for the SPARC architecture:
328 @item -Av6 | -Av7 | -Av8 | -Asparclite
329 Explicitly select a variant of the SPARC architecture.
332 Warn when the assembler switches to another architecture.
337 The following options are available when @value{AS} is configured for
338 the MIPS R2000/R3000 processors.
342 This option sets the largest size of an object that can be referenced
343 implicitly with the @code{gp} register. It is only accepted for targets
344 that use ECOFF format, such as a DECstation running Ultrix. The default
347 @cindex MIPS endianness
348 @cindex endianness, MIPS
350 @cindex big endian output, MIPS
351 Generate ``big endian'' format output.
354 @cindex little endian output, MIPS
355 Generate ``little endian'' format output.
358 This option is ignored. It is accepted for compatibility with the native
364 * Manual:: Structure of this Manual
365 * GNU Assembler:: @value{AS}, the GNU Assembler
366 * Object Formats:: Object File Formats
367 * Command Line:: Command Line
368 * Input Files:: Input Files
369 * Object:: Output (Object) File
370 * Errors:: Error and Warning Messages
374 @section Structure of this Manual
376 @cindex manual, structure and purpose
377 This manual is intended to describe what you need to know to use
378 @sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including
379 notation for symbols, constants, and expressions; the directives that
380 @code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}.
383 We also cover special features in the @value{TARGET}
384 configuration of @code{@value{AS}}, including assembler directives.
387 This manual also describes some of the machine-dependent features of
388 various flavors of the assembler.
391 @cindex machine instructions (not covered)
392 On the other hand, this manual is @emph{not} intended as an introduction
393 to programming in assembly language---let alone programming in general!
394 In a similar vein, we make no attempt to introduce the machine
395 architecture; we do @emph{not} describe the instruction set, standard
396 mnemonics, registers or addressing modes that are standard to a
397 particular architecture.
399 You may want to consult the manufacturer's
400 machine architecture manual for this information.
404 For information on the H8/300 machine instruction set, see @cite{H8/300
405 Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H,
406 see @cite{H8/300H Series Programming Manual} (Hitachi).
409 For information on the H8/500 machine instruction set, see @cite{H8/500
410 Series Programming Manual} (Hitachi M21T001).
413 For information on the Hitachi SH machine instruction set, see
414 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
417 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
421 @c I think this is premature---pesch@cygnus.com, 17jan1991
423 Throughout this manual, we assume that you are running @dfn{GNU},
424 the portable operating system from the @dfn{Free Software
425 Foundation, Inc.}. This restricts our attention to certain kinds of
426 computer (in particular, the kinds of computers that GNU can run on);
427 once this assumption is granted examples and definitions need less
430 @code{@value{AS}} is part of a team of programs that turn a high-level
431 human-readable series of instructions into a low-level
432 computer-readable series of instructions. Different versions of
433 @code{@value{AS}} are used for different kinds of computer.
436 @c There used to be a section "Terminology" here, which defined
437 @c "contents", "byte", "word", and "long". Defining "word" to any
438 @c particular size is confusing when the .word directive may generate 16
439 @c bits on one machine and 32 bits on another; in general, for the user
440 @c version of this manual, none of these terms seem essential to define.
441 @c They were used very little even in the former draft of the manual;
442 @c this draft makes an effort to avoid them (except in names of
446 @section @value{AS}, the GNU Assembler
448 GNU @code{as} is really a family of assemblers.
450 This manual describes @code{@value{AS}}, a member of that family which is
451 configured for the @value{TARGET} architectures.
453 If you use (or have used) the GNU assembler on one architecture, you
454 should find a fairly similar environment when you use it on another
455 architecture. Each version has much in common with the others,
456 including object file formats, most assembler directives (often called
457 @dfn{pseudo-ops}) and assembler syntax.@refill
459 @cindex purpose of @sc{gnu} @code{@value{AS}}
460 @code{@value{AS}} is primarily intended to assemble the output of the
461 GNU C compiler @code{@value{GCC}} for use by the linker
462 @code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}}
463 assemble correctly everything that other assemblers for the same
464 machine would assemble.
466 Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
469 @c This remark should appear in generic version of manual; assumption
470 @c here is that generic version sets M680x0.
471 This doesn't mean @code{@value{AS}} always uses the same syntax as another
472 assembler for the same architecture; for example, we know of several
473 incompatible versions of 680x0 assembly language syntax.
476 Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
477 program in one pass of the source file. This has a subtle impact on the
478 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
481 @section Object File Formats
483 @cindex object file format
484 The GNU assembler can be configured to produce several alternative
485 object file formats. For the most part, this does not affect how you
486 write assembly language programs; but directives for debugging symbols
487 are typically different in different file formats. @xref{Symbol
488 Attributes,,Symbol Attributes}.
491 On the @value{TARGET}, @code{@value{AS}} is configured to produce
492 @value{OBJ-NAME} format object files.
494 @c The following should exhaust all configs that set MULTI-OBJ, ideally
496 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
497 @code{a.out} or COFF format object files.
500 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
501 @code{b.out} or COFF format object files.
504 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
505 SOM or ELF format object files.
510 @section Command Line
512 @cindex command line conventions
513 After the program name @code{@value{AS}}, the command line may contain
514 options and file names. Options may appear in any order, and may be
515 before, after, or between file names. The order of file names is
518 @cindex standard input, as input file
520 @file{--} (two hyphens) by itself names the standard input file
521 explicitly, as one of the files for @code{@value{AS}} to assemble.
523 @cindex options, command line
524 Except for @samp{--} any command line argument that begins with a
525 hyphen (@samp{-}) is an option. Each option changes the behavior of
526 @code{@value{AS}}. No option changes the way another option works. An
527 option is a @samp{-} followed by one or more letters; the case of
528 the letter is important. All options are optional.
530 Some options expect exactly one file name to follow them. The file
531 name may either immediately follow the option's letter (compatible
532 with older assemblers) or it may be the next command argument (GNU
533 standard). These two command lines are equivalent:
536 @value{AS} -o my-object-file.o mumble.s
537 @value{AS} -omy-object-file.o mumble.s
544 @cindex source program
546 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
547 describe the program input to one run of @code{@value{AS}}. The program may
548 be in one or more files; how the source is partitioned into files
549 doesn't change the meaning of the source.
551 @c I added "con" prefix to "catenation" just to prove I can overcome my
552 @c APL training... pesch@cygnus.com
553 The source program is a concatenation of the text in all the files, in the
556 Each time you run @code{@value{AS}} it assembles exactly one source
557 program. The source program is made up of one or more files.
558 (The standard input is also a file.)
560 You give @code{@value{AS}} a command line that has zero or more input file
561 names. The input files are read (from left file name to right). A
562 command line argument (in any position) that has no special meaning
563 is taken to be an input file name.
565 If you give @code{@value{AS}} no file names it attempts to read one input file
566 from the @code{@value{AS}} standard input, which is normally your terminal. You
567 may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program
570 Use @samp{--} if you need to explicitly name the standard input file
571 in your command line.
573 If the source is empty, @code{@value{AS}} produces a small, empty object
576 @subheading Filenames and Line-numbers
578 @cindex input file linenumbers
579 @cindex line numbers, in input files
580 There are two ways of locating a line in the input file (or files) and
581 either may be used in reporting error messages. One way refers to a line
582 number in a physical file; the other refers to a line number in a
583 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
585 @dfn{Physical files} are those files named in the command line given
586 to @code{@value{AS}}.
588 @dfn{Logical files} are simply names declared explicitly by assembler
589 directives; they bear no relation to physical files. Logical file names
590 help error messages reflect the original source file, when @code{@value{AS}}
591 source is itself synthesized from other files.
592 @xref{App-File,,@code{.app-file}}.
595 @section Output (Object) File
601 Every time you run @code{@value{AS}} it produces an output file, which is
602 your assembly language program translated into numbers. This file
603 is the object file, named
607 if @code{@value{AS}} is configured for the Intel 80960, or
613 unless you tell @code{@value{AS}} to
614 give it another name by using the @code{-o} option. Conventionally,
615 object file names end with @file{.o}. The default name of
616 @file{a.out} is used for historical reasons: older assemblers were
617 capable of assembling self-contained programs directly into a
619 (For some formats, this isn't currently possible, but it can be done for
620 @code{a.out} format.)
624 The object file is meant for input to the linker @code{@value{LD}}. It contains
625 assembled program code, information to help @code{@value{LD}} integrate
626 the assembled program into a runnable file, and (optionally) symbolic
627 information for the debugger.
629 @c link above to some info file(s) like the description of a.out.
630 @c don't forget to describe GNU info as well as Unix lossage.
633 @section Error and Warning Messages
635 @cindex error messsages
636 @cindex warning messages
637 @cindex messages from @code{@value{AS}}
638 @code{@value{AS}} may write warnings and error messages to the standard error
639 file (usually your terminal). This should not happen when a compiler
640 runs @code{@value{AS}} automatically. Warnings report an assumption made so
641 that @code{@value{AS}} could keep assembling a flawed program; errors report a
642 grave problem that stops the assembly.
644 @cindex format of warning messages
645 Warning messages have the format
648 file_name:@b{NNN}:Warning Message Text
652 @cindex line numbers, in warnings/errors
653 (where @b{NNN} is a line number). If a logical file name has been given
654 (@pxref{App-File,,@code{.app-file}}) it is used for the filename,
655 otherwise the name of the current input file is used. If a logical line
658 (@pxref{Line,,@code{.line}})
662 (@pxref{Line,,@code{.line}})
665 (@pxref{Ln,,@code{.ln}})
668 then it is used to calculate the number printed,
669 otherwise the actual line in the current source file is printed. The
670 message text is intended to be self explanatory (in the grand Unix
673 @cindex format of error messages
674 Error messages have the format
676 file_name:@b{NNN}:FATAL:Error Message Text
678 The file name and line number are derived as for warning
679 messages. The actual message text may be rather less explanatory
680 because many of them aren't supposed to happen.
683 @chapter Command-Line Options
685 @cindex options, all versions of @code{@value{AS}}
686 This chapter describes command-line options available in @emph{all}
687 versions of the GNU assembler; @pxref{Machine Dependencies}, for options specific
689 to the @value{TARGET}.
692 to particular machine architectures.
695 If you are invoking @code{@value{AS}} via the GNU C compiler (version 2), you
696 can use the @samp{-Wa} option to pass arguments through to the
697 assembler. The assembler arguments must be separated from each other
698 (and the @samp{-Wa}) by commas. For example:
701 gcc -c -g -O -Wa,-alh,-L file.c
705 emits a listing to standard output with high-level
708 Many compiler command-line options, such as @samp{-R} and many machine-specific
709 options, are automatically passed to the assembler by the compiler, so usually
710 you do not need to use this @samp{-Wa} mechanism. (You can call the GNU
711 compiler driver with the @samp{-v} option to see precisely what options it
712 passes to each compilation pass, including the assembler.)
715 * a:: -a[dhlns] enable listings
716 * D:: -D for compatibility
717 * f:: -f to work faster
718 * I:: -I for .include search path
719 @ifclear DIFF-TBL-KLUGE
720 * K:: -K for compatibility
722 @ifset DIFF-TBL-KLUGE
723 * K:: -K for difference tables
726 * L:: -L to retain local labels
727 * o:: -o to name the object file
728 * R:: -R to join data and text sections
729 * v:: -v to announce version
730 * W:: -W to suppress warnings
734 @section Enable Listings: @code{-a[dhlns]}
742 @cindex listings, enabling
743 @cindex assembly listings, enabling
745 These options enable listing output from the assembler. By itself,
746 @samp{-a} requests high-level, assembly, and symbols listing.
747 Other letters may be used to select specific options for the list:
748 @samp{-ah} requests a high-level language listing,
749 @samp{-al} requests an output-program assembly listing, and
750 @samp{-as} requests a symbol table listing.
751 High-level listings require that a compiler debugging option like
752 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
755 The @samp{-ad} option may be used to omit debugging directives from the
758 Once you have specified one of these options, you can further control
759 listing output and its appearance using the directives @code{.list},
760 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
762 The @samp{-an} option turns off all forms processing.
763 If you do not request listing output with one of the @samp{-a} options, the
764 listing-control directives have no effect.
766 The letters after @samp{-a} may be combined into one option,
767 @emph{e.g.}, @samp{-aln}.
773 This option has no effect whatsoever, but it is accepted to make it more
774 likely that scripts written for other assemblers also work with
778 @section Work Faster: @code{-f}
781 @cindex trusted compiler
782 @cindex faster processing (@code{-f})
783 @samp{-f} should only be used when assembling programs written by a
784 (trusted) compiler. @samp{-f} stops the assembler from doing whitespace
785 and comment preprocessing on
786 the input file(s) before assembling them. @xref{Preprocessing,
790 @emph{Warning:} if you use @samp{-f} when the files actually need to be
791 preprocessed (if they contain comments, for example), @code{@value{AS}} does
796 @section @code{.include} search path: @code{-I} @var{path}
798 @kindex -I @var{path}
799 @cindex paths for @code{.include}
800 @cindex search path for @code{.include}
801 @cindex @code{include} directive search path
802 Use this option to add a @var{path} to the list of directories
803 @code{@value{AS}} searches for files specified in @code{.include}
804 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
805 many times as necessary to include a variety of paths. The current
806 working directory is always searched first; after that, @code{@value{AS}}
807 searches any @samp{-I} directories in the same order as they were
808 specified (left to right) on the command line.
811 @section Difference Tables: @code{-K}
814 @ifclear DIFF-TBL-KLUGE
815 On the @value{TARGET} family, this option is allowed, but has no effect. It is
816 permitted for compatibility with the GNU assembler on other platforms,
817 where it can be used to warn when the assembler alters the machine code
818 generated for @samp{.word} directives in difference tables. The @value{TARGET}
819 family does not have the addressing limitations that sometimes lead to this
820 alteration on other platforms.
823 @ifset DIFF-TBL-KLUGE
824 @cindex difference tables, warning
825 @cindex warning for altered difference tables
826 @code{@value{AS}} sometimes alters the code emitted for directives of the form
827 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
828 You can use the @samp{-K} option if you want a warning issued when this
833 @section Include Local Labels: @code{-L}
836 @cindex local labels, retaining in output
837 Labels beginning with @samp{L} (upper case only) are called @dfn{local
838 labels}. @xref{Symbol Names}. Normally you do not see such labels when
839 debugging, because they are intended for the use of programs (like
840 compilers) that compose assembler programs, not for your notice.
841 Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not
842 normally debug with them.
844 This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols
845 in the object file. Usually if you do this you also tell the linker
846 @code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
848 By default, a local label is any label beginning with @samp{L}, but each
849 target is allowed to redefine the local label prefix.
851 On the HPPA local labels begin with @samp{L$}.
855 @section Name the Object File: @code{-o}
858 @cindex naming object file
859 @cindex object file name
860 There is always one object file output when you run @code{@value{AS}}. By
861 default it has the name
864 @file{a.out} (or @file{b.out}, for Intel 960 targets only).
878 You use this option (which takes exactly one filename) to give the
879 object file a different name.
881 Whatever the object file is called, @code{@value{AS}} overwrites any
882 existing file of the same name.
885 @section Join Data and Text Sections: @code{-R}
888 @cindex data and text sections, joining
889 @cindex text and data sections, joining
890 @cindex joining text and data sections
891 @cindex merging text and data sections
892 @code{-R} tells @code{@value{AS}} to write the object file as if all
893 data-section data lives in the text section. This is only done at
894 the very last moment: your binary data are the same, but data
895 section parts are relocated differently. The data section part of
896 your object file is zero bytes long because all its bytes are
897 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
899 When you specify @code{-R} it would be possible to generate shorter
900 address displacements (because we do not have to cross between text and
901 data section). We refrain from doing this simply for compatibility with
902 older versions of @code{@value{AS}}. In future, @code{-R} may work this way.
905 When @code{@value{AS}} is configured for COFF output,
906 this option is only useful if you use sections named @samp{.text} and
911 @code{-R} is not supported for any of the HPPA targets. Using
912 @code{-R} generates a warning from @code{@value{AS}}.
916 @section Announce Version: @code{-v}
920 @cindex @code{@value{AS}} version
921 @cindex version of @code{@value{AS}}
922 You can find out what version of as is running by including the
923 option @samp{-v} (which you can also spell as @samp{-version}) on the
927 @section Suppress Warnings: @code{-W}
930 @cindex suppressing warnings
931 @cindex warnings, suppressing
932 @code{@value{AS}} should never give a warning or error message when
933 assembling compiler output. But programs written by people often
934 cause @code{@value{AS}} to give a warning that a particular assumption was
935 made. All such warnings are directed to the standard error file.
936 If you use this option, no warnings are issued. This option only
937 affects the warning messages: it does not change any particular of how
938 @code{@value{AS}} assembles your file. Errors, which stop the assembly, are
944 @cindex machine-independent syntax
945 @cindex syntax, machine-independent
946 This chapter describes the machine-independent syntax allowed in a
947 source file. @code{@value{AS}} syntax is similar to what many other
948 assemblers use; it is inspired by the BSD 4.2
953 assembler, except that @code{@value{AS}} does not assemble Vax bit-fields.
957 * Preprocessing:: Preprocessing
958 * Whitespace:: Whitespace
959 * Comments:: Comments
960 * Symbol Intro:: Symbols
961 * Statements:: Statements
962 * Constants:: Constants
966 @section Preprocessing
968 @cindex preprocessing
969 The @code{@value{AS}} internal preprocessor:
971 @cindex whitespace, removed by preprocessor
973 adjusts and removes extra whitespace. It leaves one space or tab before
974 the keywords on a line, and turns any other whitespace on the line into
977 @cindex comments, removed by preprocessor
979 removes all comments, replacing them with a single space, or an
980 appropriate number of newlines.
982 @cindex constants, converted by preprocessor
984 converts character constants into the appropriate numeric values.
987 Note that it does not do macro processing, include file handling, or
988 anything else you may get from your C compiler's preprocessor. You can
989 do include file processing with the @code{.include} directive
990 (@pxref{Include,,@code{.include}}). Other ``CPP'' style preprocessing
991 can be done with the @sc{GNU} C compiler, by giving the input file a
992 @samp{.S} suffix; see the compiler documentation for details.
994 Excess whitespace, comments, and character constants
995 cannot be used in the portions of the input text that are not
998 @cindex turning preprocessing on and off
999 @cindex preprocessing, turning on and off
1002 If the first line of an input file is @code{#NO_APP} or if you use the
1003 @samp{-f} option, whitespace and comments are not removed from the input file.
1004 Within an input file, you can ask for whitespace and comment removal in
1005 specific portions of the by putting a line that says @code{#APP} before the
1006 text that may contain whitespace or comments, and putting a line that says
1007 @code{#NO_APP} after this text. This feature is mainly intend to support
1008 @code{asm} statements in compilers whose output is otherwise free of comments
1015 @dfn{Whitespace} is one or more blanks or tabs, in any order.
1016 Whitespace is used to separate symbols, and to make programs neater for
1017 people to read. Unless within character constants
1018 (@pxref{Characters,,Character Constants}), any whitespace means the same
1019 as exactly one space.
1025 There are two ways of rendering comments to @code{@value{AS}}. In both
1026 cases the comment is equivalent to one space.
1028 Anything from @samp{/*} through the next @samp{*/} is a comment.
1029 This means you may not nest these comments.
1033 The only way to include a newline ('\n') in a comment
1034 is to use this sort of comment.
1037 /* This sort of comment does not nest. */
1040 @cindex line comment character
1041 Anything from the @dfn{line comment} character to the next newline
1042 is considered a comment and is ignored. The line comment character is
1044 @samp{#} on the Vax;
1047 @samp{#} on the i960;
1050 @samp{!} on the SPARC;
1053 @samp{|} on the 680x0;
1056 @samp{;} for the AMD 29K family;
1059 @samp{;} for the H8/300 family;
1062 @samp{!} for the H8/500 family;
1065 @samp{;} for the HPPA;
1068 @samp{!} for the Hitachi SH;
1071 @samp{!} for the Z8000;
1073 see @ref{Machine Dependencies}. @refill
1074 @c FIXME What about i386, m88k, i860?
1077 On some machines there are two different line comment characters. One
1078 character only begins a comment if it is the first non-whitespace character on
1079 a line, while the other always begins a comment.
1083 @cindex lines starting with @code{#}
1084 @cindex logical line numbers
1085 To be compatible with past assemblers, a special interpretation is given to
1086 lines that begin with @samp{#}. Following the @samp{#} should be an absolute
1087 expression (@pxref{Expressions}): the logical line number of the @emph{next}
1088 line. Then a string (@xref{Strings}.) is allowed: if present it is a new
1089 logical file name. The rest of the line, if any, should be whitespace.
1091 If the first non-whitespace characters on the line are not numeric,
1092 the line is ignored. (Just like a comment.)
1094 # This is an ordinary comment.
1095 # 42-6 "new_file_name" # New logical file name
1096 # This is logical line # 36.
1098 This feature is deprecated, and may disappear from future versions
1099 of @code{@value{AS}}.
1104 @cindex characters used in symbols
1105 @ifclear SPECIAL-SYMS
1106 A @dfn{symbol} is one or more characters chosen from the set of all
1107 letters (both upper and lower case), digits and the three characters
1113 A @dfn{symbol} is one or more characters chosen from the set of all
1114 letters (both upper and lower case), digits and the three characters
1115 @samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in
1121 On most machines, you can also use @code{$} in symbol names; exceptions
1122 are noted in @ref{Machine Dependencies}.
1124 No symbol may begin with a digit. Case is significant.
1125 There is no length limit: all characters are significant. Symbols are
1126 delimited by characters not in that set, or by the beginning of a file
1127 (since the source program must end with a newline, the end of a file is
1128 not a possible symbol delimiter). @xref{Symbols}.
1129 @cindex length of symbols
1134 @cindex statements, structure of
1135 @cindex line separator character
1136 @cindex statement separator character
1138 @ifclear abnormal-separator
1139 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
1140 semicolon (@samp{;}). The newline or semicolon is considered part of
1141 the preceding statement. Newlines and semicolons within character
1142 constants are an exception: they do not end statements.
1144 @ifset abnormal-separator
1146 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
1147 sign (@samp{@@}). The newline or at sign is considered part of the
1148 preceding statement. Newlines and at signs within character constants
1149 are an exception: they do not end statements.
1152 A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation
1153 point (@samp{!}). The newline or exclamation point is considered part of the
1154 preceding statement. Newlines and exclamation points within character
1155 constants are an exception: they do not end statements.
1158 A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
1159 H8/300) a dollar sign (@samp{$}); or (for the
1162 (@samp{;}). The newline or separator character is considered part of
1163 the preceding statement. Newlines and separators within character
1164 constants are an exception: they do not end statements.
1169 A @dfn{statement} ends at a newline character (@samp{\n}) or line
1170 separator character. (The line separator is usually @samp{;}, unless
1171 this conflicts with the comment character; @pxref{Machine Dependencies}.) The
1172 newline or separator character is considered part of the preceding
1173 statement. Newlines and separators within character constants are an
1174 exception: they do not end statements.
1177 @cindex newline, required at file end
1178 @cindex EOF, newline must precede
1179 It is an error to end any statement with end-of-file: the last
1180 character of any input file should be a newline.@refill
1182 @cindex continuing statements
1183 @cindex multi-line statements
1184 @cindex statement on multiple lines
1185 You may write a statement on more than one line if you put a
1186 backslash (@kbd{\}) immediately in front of any newlines within the
1187 statement. When @code{@value{AS}} reads a backslashed newline both
1188 characters are ignored. You can even put backslashed newlines in
1189 the middle of symbol names without changing the meaning of your
1192 An empty statement is allowed, and may include whitespace. It is ignored.
1194 @cindex instructions and directives
1195 @cindex directives and instructions
1196 @c "key symbol" is not used elsewhere in the document; seems pedantic to
1197 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
1199 A statement begins with zero or more labels, optionally followed by a
1200 key symbol which determines what kind of statement it is. The key
1201 symbol determines the syntax of the rest of the statement. If the
1202 symbol begins with a dot @samp{.} then the statement is an assembler
1203 directive: typically valid for any computer. If the symbol begins with
1204 a letter the statement is an assembly language @dfn{instruction}: it
1205 assembles into a machine language instruction.
1207 Different versions of @code{@value{AS}} for different computers
1208 recognize different instructions. In fact, the same symbol may
1209 represent a different instruction in a different computer's assembly
1213 @cindex @code{:} (label)
1214 @cindex label (@code{:})
1215 A label is a symbol immediately followed by a colon (@code{:}).
1216 Whitespace before a label or after a colon is permitted, but you may not
1217 have whitespace between a label's symbol and its colon. @xref{Labels}.
1220 For HPPA targets, labels need not be immediately followed by a colon, but
1221 the definition of a label must begin in column zero. This also implies that
1222 only one label may be defined on each line.
1226 label: .directive followed by something
1227 another_label: # This is an empty statement.
1228 instruction operand_1, operand_2, @dots{}
1235 A constant is a number, written so that its value is known by
1236 inspection, without knowing any context. Like this:
1239 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
1240 .ascii "Ring the bell\7" # A string constant.
1241 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
1242 .float 0f-314159265358979323846264338327\
1243 95028841971.693993751E-40 # - pi, a flonum.
1248 * Characters:: Character Constants
1249 * Numbers:: Number Constants
1253 @subsection Character Constants
1255 @cindex character constants
1256 @cindex constants, character
1257 There are two kinds of character constants. A @dfn{character} stands
1258 for one character in one byte and its value may be used in
1259 numeric expressions. String constants (properly called string
1260 @emph{literals}) are potentially many bytes and their values may not be
1261 used in arithmetic expressions.
1265 * Chars:: Characters
1269 @subsubsection Strings
1271 @cindex string constants
1272 @cindex constants, string
1273 A @dfn{string} is written between double-quotes. It may contain
1274 double-quotes or null characters. The way to get special characters
1275 into a string is to @dfn{escape} these characters: precede them with
1276 a backslash @samp{\} character. For example @samp{\\} represents
1277 one backslash: the first @code{\} is an escape which tells
1278 @code{@value{AS}} to interpret the second character literally as a backslash
1279 (which prevents @code{@value{AS}} from recognizing the second @code{\} as an
1280 escape character). The complete list of escapes follows.
1282 @cindex escape codes, character
1283 @cindex character escape codes
1286 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1289 @cindex @code{\b} (backspace character)
1290 @cindex backspace (@code{\b})
1291 Mnemonic for backspace; for ASCII this is octal code 010.
1294 @c Mnemonic for EOText; for ASCII this is octal code 004.
1297 @cindex @code{\f} (formfeed character)
1298 @cindex formfeed (@code{\f})
1299 Mnemonic for FormFeed; for ASCII this is octal code 014.
1302 @cindex @code{\n} (newline character)
1303 @cindex newline (@code{\n})
1304 Mnemonic for newline; for ASCII this is octal code 012.
1307 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1310 @cindex @code{\r} (carriage return character)
1311 @cindex carriage return (@code{\r})
1312 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1315 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1316 @c other assemblers.
1319 @cindex @code{\t} (tab)
1320 @cindex tab (@code{\t})
1321 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1324 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1325 @c @item \x @var{digit} @var{digit} @var{digit}
1326 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1328 @item \ @var{digit} @var{digit} @var{digit}
1329 @cindex @code{\@var{ddd}} (octal character code)
1330 @cindex octal character code (@code{\@var{ddd}})
1331 An octal character code. The numeric code is 3 octal digits.
1332 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1333 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1336 @item \@code{x} @var{hex-digit} @var{hex-digit}
1337 @cindex @code{\@var{xdd}} (hex character code)
1338 @cindex hex character code (@code{\@var{xdd}})
1339 A hex character code. The numeric code is 2 hexadecimal digits. Either
1340 upper or lower case @code{x} works.
1344 @cindex @code{\\} (@samp{\} character)
1345 @cindex backslash (@code{\\})
1346 Represents one @samp{\} character.
1349 @c Represents one @samp{'} (accent acute) character.
1350 @c This is needed in single character literals
1351 @c (@xref{Characters,,Character Constants}.) to represent
1355 @cindex @code{\"} (doublequote character)
1356 @cindex doublequote (@code{\"})
1357 Represents one @samp{"} character. Needed in strings to represent
1358 this character, because an unescaped @samp{"} would end the string.
1360 @item \ @var{anything-else}
1361 Any other character when escaped by @kbd{\} gives a warning, but
1362 assemble as if the @samp{\} was not present. The idea is that if
1363 you used an escape sequence you clearly didn't want the literal
1364 interpretation of the following character. However @code{@value{AS}} has no
1365 other interpretation, so @code{@value{AS}} knows it is giving you the wrong
1366 code and warns you of the fact.
1369 Which characters are escapable, and what those escapes represent,
1370 varies widely among assemblers. The current set is what we think
1371 the BSD 4.2 assembler recognizes, and is a subset of what most C
1372 compilers recognize. If you are in doubt, do not use an escape
1376 @subsubsection Characters
1378 @cindex single character constant
1379 @cindex character, single
1380 @cindex constant, single character
1381 A single character may be written as a single quote immediately
1382 followed by that character. The same escapes apply to characters as
1383 to strings. So if you want to write the character backslash, you
1384 must write @kbd{'\\} where the first @code{\} escapes the second
1385 @code{\}. As you can see, the quote is an acute accent, not a
1386 grave accent. A newline
1388 @ifclear abnormal-separator
1389 (or semicolon @samp{;})
1391 @ifset abnormal-separator
1393 (or at sign @samp{@@})
1396 (or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
1402 immediately following an acute accent is taken as a literal character
1403 and does not count as the end of a statement. The value of a character
1404 constant in a numeric expression is the machine's byte-wide code for
1405 that character. @code{@value{AS}} assumes your character code is ASCII:
1406 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1409 @subsection Number Constants
1411 @cindex constants, number
1412 @cindex number constants
1413 @code{@value{AS}} distinguishes three kinds of numbers according to how they
1414 are stored in the target machine. @emph{Integers} are numbers that
1415 would fit into an @code{int} in the C language. @emph{Bignums} are
1416 integers, but they are stored in more than 32 bits. @emph{Flonums}
1417 are floating point numbers, described below.
1420 * Integers:: Integers
1425 * Bit Fields:: Bit Fields
1431 @subsubsection Integers
1433 @cindex constants, integer
1435 @cindex binary integers
1436 @cindex integers, binary
1437 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1438 the binary digits @samp{01}.
1440 @cindex octal integers
1441 @cindex integers, octal
1442 An octal integer is @samp{0} followed by zero or more of the octal
1443 digits (@samp{01234567}).
1445 @cindex decimal integers
1446 @cindex integers, decimal
1447 A decimal integer starts with a non-zero digit followed by zero or
1448 more digits (@samp{0123456789}).
1450 @cindex hexadecimal integers
1451 @cindex integers, hexadecimal
1452 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1453 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1455 Integers have the usual values. To denote a negative integer, use
1456 the prefix operator @samp{-} discussed under expressions
1457 (@pxref{Prefix Ops,,Prefix Operators}).
1460 @subsubsection Bignums
1463 @cindex constants, bignum
1464 A @dfn{bignum} has the same syntax and semantics as an integer
1465 except that the number (or its negative) takes more than 32 bits to
1466 represent in binary. The distinction is made because in some places
1467 integers are permitted while bignums are not.
1470 @subsubsection Flonums
1472 @cindex floating point numbers
1473 @cindex constants, floating point
1475 @cindex precision, floating point
1476 A @dfn{flonum} represents a floating point number. The translation is
1477 indirect: a decimal floating point number from the text is converted by
1478 @code{@value{AS}} to a generic binary floating point number of more than
1479 sufficient precision. This generic floating point number is converted
1480 to a particular computer's floating point format (or formats) by a
1481 portion of @code{@value{AS}} specialized to that computer.
1483 A flonum is written by writing (in order)
1488 (@samp{0} is optional on the HPPA.)
1492 A letter, to tell @code{@value{AS}} the rest of the number is a flonum.
1494 @kbd{e} is recommended. Case is not important.
1496 @c FIXME: verify if flonum syntax really this vague for most cases
1497 (Any otherwise illegal letter works here, but that might be changed. Vax BSD
1498 4.2 assembler seems to allow any of @samp{defghDEFGH}.)
1501 On the H8/300, H8/500,
1503 and AMD 29K architectures, the letter must be
1504 one of the letters @samp{DFPRSX} (in upper or lower case).
1506 On the Intel 960 architecture, the letter must be
1507 one of the letters @samp{DFT} (in upper or lower case).
1509 On the HPPA architecture, the letter must be @samp{E} (upper case only).
1513 One of the letters @samp{DFPRSX} (in upper or lower case).
1516 One of the letters @samp{DFPRSX} (in upper or lower case).
1519 One of the letters @samp{DFT} (in upper or lower case).
1522 The letter @samp{E} (upper case only).
1527 An optional sign: either @samp{+} or @samp{-}.
1530 An optional @dfn{integer part}: zero or more decimal digits.
1533 An optional @dfn{fractional part}: @samp{.} followed by zero
1534 or more decimal digits.
1537 An optional exponent, consisting of:
1541 An @samp{E} or @samp{e}.
1542 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1543 @c principle this can perfectly well be different on different targets.
1545 Optional sign: either @samp{+} or @samp{-}.
1547 One or more decimal digits.
1552 At least one of the integer part or the fractional part must be
1553 present. The floating point number has the usual base-10 value.
1555 @code{@value{AS}} does all processing using integers. Flonums are computed
1556 independently of any floating point hardware in the computer running
1561 @c Bit fields are written as a general facility but are also controlled
1562 @c by a conditional-compilation flag---which is as of now (21mar91)
1563 @c turned on only by the i960 config of GAS.
1565 @subsubsection Bit Fields
1568 @cindex constants, bit field
1569 You can also define numeric constants as @dfn{bit fields}.
1570 specify two numbers separated by a colon---
1572 @var{mask}:@var{value}
1575 @code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
1578 The resulting number is then packed
1580 @c this conditional paren in case bit fields turned on elsewhere than 960
1581 (in host-dependent byte order)
1583 into a field whose width depends on which assembler directive has the
1584 bit-field as its argument. Overflow (a result from the bitwise and
1585 requiring more binary digits to represent) is not an error; instead,
1586 more constants are generated, of the specified width, beginning with the
1587 least significant digits.@refill
1589 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1590 @code{.short}, and @code{.word} accept bit-field arguments.
1595 @chapter Sections and Relocation
1600 * Secs Background:: Background
1601 * Ld Sections:: @value{LD} Sections
1602 * As Sections:: @value{AS} Internal Sections
1603 * Sub-Sections:: Sub-Sections
1607 @node Secs Background
1610 Roughly, a section is a range of addresses, with no gaps; all data
1611 ``in'' those addresses is treated the same for some particular purpose.
1612 For example there may be a ``read only'' section.
1614 @cindex linker, and assembler
1615 @cindex assembler, and linker
1616 The linker @code{@value{LD}} reads many object files (partial programs) and
1617 combines their contents to form a runnable program. When @code{@value{AS}}
1618 emits an object file, the partial program is assumed to start at address 0.
1619 @code{@value{LD}} assigns the final addresses for the partial program, so that
1620 different partial programs do not overlap. This is actually an
1621 oversimplification, but it suffices to explain how @code{@value{AS}} uses
1624 @code{@value{LD}} moves blocks of bytes of your program to their run-time
1625 addresses. These blocks slide to their run-time addresses as rigid
1626 units; their length does not change and neither does the order of bytes
1627 within them. Such a rigid unit is called a @emph{section}. Assigning
1628 run-time addresses to sections is called @dfn{relocation}. It includes
1629 the task of adjusting mentions of object-file addresses so they refer to
1630 the proper run-time addresses.
1632 For the H8/300 and H8/500,
1633 and for the Hitachi SH,
1634 @code{@value{AS}} pads sections if needed to
1635 ensure they end on a word (sixteen bit) boundary.
1638 @cindex standard @code{@value{AS}} sections
1639 An object file written by @code{@value{AS}} has at least three sections, any
1640 of which may be empty. These are named @dfn{text}, @dfn{data} and
1645 When it generates COFF output,
1647 @code{@value{AS}} can also generate whatever other named sections you specify
1648 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1649 If you do not use any directives that place output in the @samp{.text}
1650 or @samp{.data} sections, these sections still exist, but are empty.
1655 When @code{@value{AS}} generates SOM or ELF output for the HPPA,
1657 @code{@value{AS}} can also generate whatever other named sections you
1658 specify using the @samp{.space} and @samp{.subspace} directives. See
1659 @cite{HP9000 Series 800 Assembly Language Reference Manual}
1660 (HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
1661 assembler directives.
1664 Additionally, @code{@value{AS}} uses different names for the standard
1665 text, data, and bss sections when generating SOM output. Program text
1666 is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
1667 BSS into @samp{$BSS$}.
1671 Within the object file, the text section starts at address @code{0}, the
1672 data section follows, and the bss section follows the data section.
1675 When generating either SOM or ELF output files on the HPPA, the text
1676 section starts at address @code{0}, the data section at address
1677 @code{0x4000000}, and the bss section follows the data section.
1680 To let @code{@value{LD}} know which data changes when the sections are
1681 relocated, and how to change that data, @code{@value{AS}} also writes to the
1682 object file details of the relocation needed. To perform relocation
1683 @code{@value{LD}} must know, each time an address in the object
1687 Where in the object file is the beginning of this reference to
1690 How long (in bytes) is this reference?
1692 Which section does the address refer to? What is the numeric value of
1694 (@var{address}) @minus{} (@var{start-address of section})?
1697 Is the reference to an address ``Program-Counter relative''?
1700 @cindex addresses, format of
1701 @cindex section-relative addressing
1702 In fact, every address @code{@value{AS}} ever uses is expressed as
1704 (@var{section}) + (@var{offset into section})
1707 Further, every expression @code{@value{AS}} computes is of this section-relative
1708 nature. @dfn{Absolute expression} means an expression with section
1709 ``absolute'' (@pxref{Ld Sections}). A @dfn{pass1 expression} means
1710 an expression with section ``pass1'' (@pxref{As Sections,,@value{AS}
1711 Internal Sections}). In this manual we use the notation @{@var{secname}
1712 @var{N}@} to mean ``offset @var{N} into section @var{secname}''.
1714 Apart from text, data and bss sections you need to know about the
1715 @dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
1716 addresses in the absolute section remain unchanged. For example, address
1717 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
1718 @code{@value{LD}}. Although the linker never arranges two partial programs'
1719 data sections with overlapping addresses after linking, @emph{by definition}
1720 their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one
1721 part of a program is always the same address when the program is running as
1722 address @code{@{absolute@ 239@}} in any other part of the program.
1724 The idea of sections is extended to the @dfn{undefined} section. Any
1725 address whose section is unknown at assembly time is by definition
1726 rendered @{undefined @var{U}@}---where @var{U} is filled in later.
1727 Since numbers are always defined, the only way to generate an undefined
1728 address is to mention an undefined symbol. A reference to a named
1729 common block would be such a symbol: its value is unknown at assembly
1730 time so it has section @emph{undefined}.
1732 By analogy the word @emph{section} is used to describe groups of sections in
1733 the linked program. @code{@value{LD}} puts all partial programs' text
1734 sections in contiguous addresses in the linked program. It is
1735 customary to refer to the @emph{text section} of a program, meaning all
1736 the addresses of all partial programs' text sections. Likewise for
1737 data and bss sections.
1739 Some sections are manipulated by @code{@value{LD}}; others are invented for
1740 use of @code{@value{AS}} and have no meaning except during assembly.
1743 @section @value{LD} Sections
1744 @code{@value{LD}} deals with just four kinds of sections, summarized below.
1749 @cindex named sections
1750 @cindex sections, named
1751 @item named sections
1754 @cindex text section
1755 @cindex data section
1759 These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as
1760 separate but equal sections. Anything you can say of one section is
1763 When the program is running, however, it is
1764 customary for the text section to be unalterable. The
1765 text section is often shared among processes: it contains
1766 instructions, constants and the like. The data section of a running
1767 program is usually alterable: for example, C variables would be stored
1768 in the data section.
1773 This section contains zeroed bytes when your program begins running. It
1774 is used to hold unitialized variables or common storage. The length of
1775 each partial program's bss section is important, but because it starts
1776 out containing zeroed bytes there is no need to store explicit zero
1777 bytes in the object file. The bss section was invented to eliminate
1778 those explicit zeros from object files.
1780 @cindex absolute section
1781 @item absolute section
1782 Address 0 of this section is always ``relocated'' to runtime address 0.
1783 This is useful if you want to refer to an address that @code{@value{LD}} must
1784 not change when relocating. In this sense we speak of absolute
1785 addresses being ``unrelocatable'': they do not change during relocation.
1787 @cindex undefined section
1788 @item undefined section
1789 This ``section'' is a catch-all for address references to objects not in
1790 the preceding sections.
1791 @c FIXME: ref to some other doc on obj-file formats could go here.
1794 @cindex relocation example
1795 An idealized example of three relocatable sections follows.
1797 The example uses the traditional section names @samp{.text} and @samp{.data}.
1799 Memory addresses are on the horizontal axis.
1803 @c END TEXI2ROFF-KILL
1806 partial program # 1: |ttttt|dddd|00|
1813 partial program # 2: |TTT|DDD|000|
1816 +--+---+-----+--+----+---+-----+~~
1817 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1818 +--+---+-----+--+----+---+-----+~~
1820 addresses: 0 @dots{}
1824 @c FIXME make sure no page breaks inside figure!!
1827 \line{\it Partial program \#1: \hfil}
1828 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1829 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1831 \line{\it Partial program \#2: \hfil}
1832 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1833 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1835 \line{\it linked program: \hfil}
1836 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1837 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1838 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1839 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1841 \line{\it addresses: \hfil}
1845 @c END TEXI2ROFF-KILL
1848 @section @value{AS} Internal Sections
1850 @cindex internal @code{@value{AS}} sections
1851 @cindex sections in messages, internal
1852 These sections are meant only for the internal use of @code{@value{AS}}. They
1853 have no meaning at run-time. You do not really need to know about these
1854 sections for most purposes; but they can be mentioned in @code{@value{AS}}
1855 warning messages, so it might be helpful to have an idea of their
1856 meanings to @code{@value{AS}}. These sections are used to permit the
1857 value of every expression in your assembly language program to be a
1858 section-relative address.
1861 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
1862 @cindex assembler internal logic error
1863 An internal assembler logic error has been found. This means there is a
1864 bug in the assembler.
1867 @cindex expr (internal section)
1868 The assembler stores complex expression internally as combinations of
1869 symbols. When it needs to represent an expression as a symbol, it puts
1870 it in the expr section.
1872 @c FIXME item transfer[t] vector preload
1873 @c FIXME item transfer[t] vector postload
1874 @c FIXME item register
1878 @section Sub-Sections
1880 @cindex numbered subsections
1881 @cindex grouping data
1887 fall into two sections: text and data.
1889 You may have separate groups of
1891 data in named sections
1895 data in named sections
1901 that you want to end up near to each other in the object file, even though they
1902 are not contiguous in the assembler source. @code{@value{AS}} allows you to
1903 use @dfn{subsections} for this purpose. Within each section, there can be
1904 numbered subsections with values from 0 to 8192. Objects assembled into the
1905 same subsection go into the object file together with other objects in the same
1906 subsection. For example, a compiler might want to store constants in the text
1907 section, but might not want to have them interspersed with the program being
1908 assembled. In this case, the compiler could issue a @samp{.text 0} before each
1909 section of code being output, and a @samp{.text 1} before each group of
1910 constants being output.
1912 Subsections are optional. If you do not use subsections, everything
1913 goes in subsection number zero.
1916 Each subsection is zero-padded up to a multiple of four bytes.
1917 (Subsections may be padded a different amount on different flavors
1918 of @code{@value{AS}}.)
1922 On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
1923 boundary (two bytes).
1924 The same is true on the Hitachi SH.
1927 @c FIXME section padding (alignment)?
1928 @c Rich Pixley says padding here depends on target obj code format; that
1929 @c doesn't seem particularly useful to say without further elaboration,
1930 @c so for now I say nothing about it. If this is a generic BFD issue,
1931 @c these paragraphs might need to vanish from this manual, and be
1932 @c discussed in BFD chapter of binutils (or some such).
1935 On the AMD 29K family, no particular padding is added to section or
1936 subsection sizes; @value{AS} forces no alignment on this platform.
1940 Subsections appear in your object file in numeric order, lowest numbered
1941 to highest. (All this to be compatible with other people's assemblers.)
1942 The object file contains no representation of subsections; @code{@value{LD}} and
1943 other programs that manipulate object files see no trace of them.
1944 They just see all your text subsections as a text section, and all your
1945 data subsections as a data section.
1947 To specify which subsection you want subsequent statements assembled
1948 into, use a numeric argument to specify it, in a @samp{.text
1949 @var{expression}} or a @samp{.data @var{expression}} statement.
1952 When generating COFF output, you
1957 can also use an extra subsection
1958 argument with arbitrary named sections: @samp{.section @var{name},
1961 @var{Expression} should be an absolute expression.
1962 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
1963 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
1964 begins in @code{text 0}. For instance:
1966 .text 0 # The default subsection is text 0 anyway.
1967 .ascii "This lives in the first text subsection. *"
1969 .ascii "But this lives in the second text subsection."
1971 .ascii "This lives in the data section,"
1972 .ascii "in the first data subsection."
1974 .ascii "This lives in the first text section,"
1975 .ascii "immediately following the asterisk (*)."
1978 Each section has a @dfn{location counter} incremented by one for every byte
1979 assembled into that section. Because subsections are merely a convenience
1980 restricted to @code{@value{AS}} there is no concept of a subsection location
1981 counter. There is no way to directly manipulate a location counter---but the
1982 @code{.align} directive changes it, and any label definition captures its
1983 current value. The location counter of the section where statements are being
1984 assembled is said to be the @dfn{active} location counter.
1987 @section bss Section
1990 @cindex common variable storage
1991 The bss section is used for local common variable storage.
1992 You may allocate address space in the bss section, but you may
1993 not dictate data to load into it before your program executes. When
1994 your program starts running, all the contents of the bss
1995 section are zeroed bytes.
1997 Addresses in the bss section are allocated with special directives; you
1998 may not assemble anything directly into the bss section. Hence there
1999 are no bss subsections. @xref{Comm,,@code{.comm}},
2000 @pxref{Lcomm,,@code{.lcomm}}.
2006 Symbols are a central concept: the programmer uses symbols to name
2007 things, the linker uses symbols to link, and the debugger uses symbols
2011 @cindex debuggers, and symbol order
2012 @emph{Warning:} @code{@value{AS}} does not place symbols in the object file in
2013 the same order they were declared. This may break some debuggers.
2018 * Setting Symbols:: Giving Symbols Other Values
2019 * Symbol Names:: Symbol Names
2020 * Dot:: The Special Dot Symbol
2021 * Symbol Attributes:: Symbol Attributes
2028 A @dfn{label} is written as a symbol immediately followed by a colon
2029 @samp{:}. The symbol then represents the current value of the
2030 active location counter, and is, for example, a suitable instruction
2031 operand. You are warned if you use the same symbol to represent two
2032 different locations: the first definition overrides any other
2036 On the HPPA, a label need not be immediately followed by a colon,
2037 but instead must start in column zero. Only one label may be
2038 defined on a single line.
2041 @node Setting Symbols
2042 @section Giving Symbols Other Values
2044 @cindex assigning values to symbols
2045 @cindex symbol values, assigning
2046 A symbol can be given an arbitrary value by writing a symbol, followed
2047 by an equals sign @samp{=}, followed by an expression
2048 (@pxref{Expressions}). This is equivalent to using the @code{.set}
2049 directive. @xref{Set,,@code{.set}}.
2052 @section Symbol Names
2054 @cindex symbol names
2055 @cindex names, symbol
2056 @ifclear SPECIAL-SYMS
2057 Symbol names begin with a letter or with one of @samp{._}. On most
2058 machines, you can also use @code{$} in symbol names; exceptions are
2059 noted in @ref{Machine Dependencies}. That character may be followed by any
2060 string of digits, letters, dollar signs (unless otherwise noted in
2061 @ref{Machine Dependencies}), and underscores.
2064 For the AMD 29K family, @samp{?} is also allowed in the
2065 body of a symbol name, though not at its beginning.
2070 Symbol names begin with a letter or with one of @samp{._}. On the
2072 H8/500, you can also use @code{$} in symbol names. That character may
2073 be followed by any string of digits, letters, dollar signs (save on the
2074 H8/300), and underscores.
2078 Case of letters is significant: @code{foo} is a different symbol name
2081 Each symbol has exactly one name. Each name in an assembly language program
2082 refers to exactly one symbol. You may use that symbol name any number of times
2085 @subheading Local Symbol Names
2087 @cindex local symbol names
2088 @cindex symbol names, local
2089 @cindex temporary symbol names
2090 @cindex symbol names, temporary
2091 Local symbols help compilers and programmers use names temporarily.
2092 There are ten local symbol names, which are re-used throughout the
2093 program. You may refer to them using the names @samp{0} @samp{1}
2094 @dots{} @samp{9}. To define a local symbol, write a label of the form
2095 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
2096 recent previous definition of that symbol write @samp{@b{N}b}, using the
2097 same digit as when you defined the label. To refer to the next
2098 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
2099 a choice of 10 forward references. The @samp{b} stands for
2100 ``backwards'' and the @samp{f} stands for ``forwards''.
2102 Local symbols are not emitted by the current GNU C compiler.
2104 There is no restriction on how you can use these labels, but
2105 remember that at any point in the assembly you can refer to at most
2106 10 prior local labels and to at most 10 forward local labels.
2108 Local symbol names are only a notation device. They are immediately
2109 transformed into more conventional symbol names before the assembler
2110 uses them. The symbol names stored in the symbol table, appearing in
2111 error messages and optionally emitted to the object file have these
2116 All local labels begin with @samp{L}. Normally both @code{@value{AS}} and
2117 @code{@value{LD}} forget symbols that start with @samp{L}. These labels are
2118 used for symbols you are never intended to see. If you use the
2119 @samp{-L} option then @code{@value{AS}} retains these symbols in the
2120 object file. If you also instruct @code{@value{LD}} to retain these symbols,
2121 you may use them in debugging.
2124 If the label is written @samp{0:} then the digit is @samp{0}.
2125 If the label is written @samp{1:} then the digit is @samp{1}.
2126 And so on up through @samp{9:}.
2129 This unusual character is included so you do not accidentally invent
2130 a symbol of the same name. The character has ASCII value
2133 @item @emph{ordinal number}
2134 This is a serial number to keep the labels distinct. The first
2135 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
2136 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
2140 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
2141 @code{3:} is named @code{L3@ctrl{A}44}.
2144 @section The Special Dot Symbol
2146 @cindex dot (symbol)
2147 @cindex @code{.} (symbol)
2148 @cindex current address
2149 @cindex location counter
2150 The special symbol @samp{.} refers to the current address that
2151 @code{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
2152 .long .} defines @code{melvin} to contain its own address.
2153 Assigning a value to @code{.} is treated the same as a @code{.org}
2154 directive. Thus, the expression @samp{.=.+4} is the same as saying
2155 @ifclear no-space-dir
2164 @node Symbol Attributes
2165 @section Symbol Attributes
2167 @cindex symbol attributes
2168 @cindex attributes, symbol
2169 Every symbol has, as well as its name, the attributes ``Value'' and
2170 ``Type''. Depending on output format, symbols can also have auxiliary
2173 The detailed definitions are in @file{a.out.h}.
2176 If you use a symbol without defining it, @code{@value{AS}} assumes zero for
2177 all these attributes, and probably won't warn you. This makes the
2178 symbol an externally defined symbol, which is generally what you
2182 * Symbol Value:: Value
2183 * Symbol Type:: Type
2186 * a.out Symbols:: Symbol Attributes: @code{a.out}
2190 * a.out Symbols:: Symbol Attributes: @code{a.out}
2193 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
2198 * COFF Symbols:: Symbol Attributes for COFF
2201 * SOM Symbols:: Symbol Attributes for SOM
2208 @cindex value of a symbol
2209 @cindex symbol value
2210 The value of a symbol is (usually) 32 bits. For a symbol which labels a
2211 location in the text, data, bss or absolute sections the value is the
2212 number of addresses from the start of that section to the label.
2213 Naturally for text, data and bss sections the value of a symbol changes
2214 as @code{@value{LD}} changes section base addresses during linking. Absolute
2215 symbols' values do not change during linking: that is why they are
2218 The value of an undefined symbol is treated in a special way. If it is
2219 0 then the symbol is not defined in this assembler source file, and
2220 @code{@value{LD}} tries to determine its value from other files linked into the
2221 same program. You make this kind of symbol simply by mentioning a symbol
2222 name without defining it. A non-zero value represents a @code{.comm}
2223 common declaration. The value is how much common storage to reserve, in
2224 bytes (addresses). The symbol refers to the first address of the
2230 @cindex type of a symbol
2232 The type attribute of a symbol contains relocation (section)
2233 information, any flag settings indicating that a symbol is external, and
2234 (optionally), other information for linkers and debuggers. The exact
2235 format depends on the object-code output format in use.
2240 @c The following avoids a "widow" subsection title. @group would be
2241 @c better if it were available outside examples.
2244 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
2246 @cindex @code{b.out} symbol attributes
2247 @cindex symbol attributes, @code{b.out}
2248 These symbol attributes appear only when @code{@value{AS}} is configured for
2249 one of the Berkeley-descended object output formats---@code{a.out} or
2255 @subsection Symbol Attributes: @code{a.out}
2257 @cindex @code{a.out} symbol attributes
2258 @cindex symbol attributes, @code{a.out}
2264 @subsection Symbol Attributes: @code{a.out}
2266 @cindex @code{a.out} symbol attributes
2267 @cindex symbol attributes, @code{a.out}
2271 * Symbol Desc:: Descriptor
2272 * Symbol Other:: Other
2276 @subsubsection Descriptor
2278 @cindex descriptor, of @code{a.out} symbol
2279 This is an arbitrary 16-bit value. You may establish a symbol's
2280 descriptor value by using a @code{.desc} statement
2281 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
2285 @subsubsection Other
2287 @cindex other attribute, of @code{a.out} symbol
2288 This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}.
2293 @subsection Symbol Attributes for COFF
2295 @cindex COFF symbol attributes
2296 @cindex symbol attributes, COFF
2298 The COFF format supports a multitude of auxiliary symbol attributes;
2299 like the primary symbol attributes, they are set between @code{.def} and
2300 @code{.endef} directives.
2302 @subsubsection Primary Attributes
2304 @cindex primary attributes, COFF symbols
2305 The symbol name is set with @code{.def}; the value and type,
2306 respectively, with @code{.val} and @code{.type}.
2308 @subsubsection Auxiliary Attributes
2310 @cindex auxiliary attributes, COFF symbols
2311 The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
2312 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2313 information for COFF.
2318 @subsection Symbol Attributes for SOM
2320 @cindex SOM symbol attributes
2321 @cindex symbol attributes, SOM
2323 The SOM format for the HPPA supports a multitude of symbol attributes set with
2324 the @code{.EXPORT} and @code{.IMPORT} directives.
2326 The attributes are described in @cite{HP9000 Series 800 Assembly
2327 Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
2328 @code{EXPORT} assembler directive documentation.
2332 @chapter Expressions
2336 @cindex numeric values
2337 An @dfn{expression} specifies an address or numeric value.
2338 Whitespace may precede and/or follow an expression.
2341 * Empty Exprs:: Empty Expressions
2342 * Integer Exprs:: Integer Expressions
2346 @section Empty Expressions
2348 @cindex empty expressions
2349 @cindex expressions, empty
2350 An empty expression has no value: it is just whitespace or null.
2351 Wherever an absolute expression is required, you may omit the
2352 expression, and @code{@value{AS}} assumes a value of (absolute) 0. This
2353 is compatible with other assemblers.
2356 @section Integer Expressions
2358 @cindex integer expressions
2359 @cindex expressions, integer
2360 An @dfn{integer expression} is one or more @emph{arguments} delimited
2361 by @emph{operators}.
2364 * Arguments:: Arguments
2365 * Operators:: Operators
2366 * Prefix Ops:: Prefix Operators
2367 * Infix Ops:: Infix Operators
2371 @subsection Arguments
2373 @cindex expression arguments
2374 @cindex arguments in expressions
2375 @cindex operands in expressions
2376 @cindex arithmetic operands
2377 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2378 contexts arguments are sometimes called ``arithmetic operands''. In
2379 this manual, to avoid confusing them with the ``instruction operands'' of
2380 the machine language, we use the term ``argument'' to refer to parts of
2381 expressions only, reserving the word ``operand'' to refer only to machine
2382 instruction operands.
2384 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2385 @var{section} is one of text, data, bss, absolute,
2386 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2389 Numbers are usually integers.
2391 A number can be a flonum or bignum. In this case, you are warned
2392 that only the low order 32 bits are used, and @code{@value{AS}} pretends
2393 these 32 bits are an integer. You may write integer-manipulating
2394 instructions that act on exotic constants, compatible with other
2397 @cindex subexpressions
2398 Subexpressions are a left parenthesis @samp{(} followed by an integer
2399 expression, followed by a right parenthesis @samp{)}; or a prefix
2400 operator followed by an argument.
2403 @subsection Operators
2405 @cindex operators, in expressions
2406 @cindex arithmetic functions
2407 @cindex functions, in expressions
2408 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2409 operators are followed by an argument. Infix operators appear
2410 between their arguments. Operators may be preceded and/or followed by
2414 @subsection Prefix Operator
2416 @cindex prefix operators
2417 @code{@value{AS}} has the following @dfn{prefix operators}. They each take
2418 one argument, which must be absolute.
2420 @c the tex/end tex stuff surrounding this small table is meant to make
2421 @c it align, on the printed page, with the similar table in the next
2422 @c section (which is inside an enumerate).
2424 \global\advance\leftskip by \itemindent
2429 @dfn{Negation}. Two's complement negation.
2431 @dfn{Complementation}. Bitwise not.
2435 \global\advance\leftskip by -\itemindent
2439 @subsection Infix Operators
2441 @cindex infix operators
2442 @cindex operators, permitted arguments
2443 @dfn{Infix operators} take two arguments, one on either side. Operators
2444 have precedence, but operations with equal precedence are performed left
2445 to right. Apart from @code{+} or @code{-}, both arguments must be
2446 absolute, and the result is absolute.
2449 @cindex operator precedence
2450 @cindex precedence of operators
2457 @dfn{Multiplication}.
2460 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2467 @dfn{Shift Left}. Same as the C operator @samp{<<}.
2471 @dfn{Shift Right}. Same as the C operator @samp{>>}.
2475 Intermediate precedence
2480 @dfn{Bitwise Inclusive Or}.
2486 @dfn{Bitwise Exclusive Or}.
2489 @dfn{Bitwise Or Not}.
2497 @cindex addition, permitted arguments
2498 @cindex plus, permitted arguments
2499 @cindex arguments for addition
2500 @dfn{Addition}. If either argument is absolute, the result
2501 has the section of the other argument.
2502 If either argument is pass1 or undefined, the result is pass1.
2503 Otherwise @code{+} is illegal.
2506 @cindex subtraction, permitted arguments
2507 @cindex minus, permitted arguments
2508 @cindex arguments for subtraction
2509 @dfn{Subtraction}. If the right argument is absolute, the
2510 result has the section of the left argument.
2511 If either argument is pass1 the result is pass1.
2512 If either argument is undefined the result is difference section.
2513 If both arguments are in the same section, the result is absolute---provided
2514 that section is one of text, data or bss.
2515 Otherwise subtraction is illegal.
2519 The sense of the rule for addition is that it's only meaningful to add
2520 the @emph{offsets} in an address; you can only have a defined section in
2521 one of the two arguments.
2523 Similarly, you can't subtract quantities from two different sections.
2526 @chapter Assembler Directives
2528 @cindex directives, machine independent
2529 @cindex pseudo-ops, machine independent
2530 @cindex machine independent directives
2531 All assembler directives have names that begin with a period (@samp{.}).
2532 The rest of the name is letters, usually in lower case.
2534 This chapter discusses directives that are available regardless of the
2535 target machine configuration for the GNU assembler.
2537 Some machine configurations provide additional directives.
2538 @xref{Machine Dependencies}.
2541 @ifset machine-directives
2542 @xref{Machine Dependencies} for additional directives.
2547 * Abort:: @code{.abort}
2549 * ABORT:: @code{.ABORT}
2552 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2553 * App-File:: @code{.app-file @var{string}}
2554 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2555 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2556 * Byte:: @code{.byte @var{expressions}}
2557 * Comm:: @code{.comm @var{symbol} , @var{length} }
2558 * Data:: @code{.data @var{subsection}}
2560 * Def:: @code{.def @var{name}}
2563 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2569 * Double:: @code{.double @var{flonums}}
2570 * Eject:: @code{.eject}
2571 * Else:: @code{.else}
2573 * Endef:: @code{.endef}
2576 * Endif:: @code{.endif}
2577 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2578 * Extern:: @code{.extern}
2579 @ifclear no-file-dir
2580 * File:: @code{.file @var{string}}
2583 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2584 * Float:: @code{.float @var{flonums}}
2585 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2586 * hword:: @code{.hword @var{expressions}}
2587 * Ident:: @code{.ident}
2588 * If:: @code{.if @var{absolute expression}}
2589 * Include:: @code{.include "@var{file}"}
2590 * Int:: @code{.int @var{expressions}}
2591 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2592 * Lflags:: @code{.lflags}
2593 @ifclear no-line-dir
2594 * Line:: @code{.line @var{line-number}}
2597 * Ln:: @code{.ln @var{line-number}}
2598 * List:: @code{.list}
2599 * Long:: @code{.long @var{expressions}}
2601 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2604 * Nolist:: @code{.nolist}
2605 * Octa:: @code{.octa @var{bignums}}
2606 * Org:: @code{.org @var{new-lc} , @var{fill}}
2607 * Psize:: @code{.psize @var{lines}, @var{columns}}
2608 * Quad:: @code{.quad @var{bignums}}
2609 * Sbttl:: @code{.sbttl "@var{subheading}"}
2611 * Scl:: @code{.scl @var{class}}
2614 * Section:: @code{.section @var{name}, @var{subsection}}
2617 * Set:: @code{.set @var{symbol}, @var{expression}}
2618 * Short:: @code{.short @var{expressions}}
2619 * Single:: @code{.single @var{flonums}}
2621 * Size:: @code{.size}
2624 * Space:: @code{.space @var{size} , @var{fill}}
2626 * Stab:: @code{.stabd, .stabn, .stabs}
2629 * Tag:: @code{.tag @var{structname}}
2632 * Text:: @code{.text @var{subsection}}
2633 * Title:: @code{.title "@var{heading}"}
2635 * Type:: @code{.type @var{int}}
2636 * Val:: @code{.val @var{addr}}
2639 * Word:: @code{.word @var{expressions}}
2640 * Deprecated:: Deprecated Directives
2644 @section @code{.abort}
2646 @cindex @code{abort} directive
2647 @cindex stopping the assembly
2648 This directive stops the assembly immediately. It is for
2649 compatibility with other assemblers. The original idea was that the
2650 assembly language source would be piped into the assembler. If the sender
2651 of the source quit, it could use this directive tells @code{@value{AS}} to
2652 quit also. One day @code{.abort} will not be supported.
2656 @section @code{.ABORT}
2658 @cindex @code{ABORT} directive
2659 When producing COFF output, @code{@value{AS}} accepts this directive as a
2660 synonym for @samp{.abort}.
2663 When producing @code{b.out} output, @code{@value{AS}} accepts this directive,
2669 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2671 @cindex padding the location counter
2672 @cindex @code{align} directive
2673 Pad the location counter (in the current subsection) to a particular
2674 storage boundary. The first expression (which must be absolute) is the
2675 number of low-order zero bits the location counter must have after
2676 advancement. For example @samp{.align 3} advances the location
2677 counter until it a multiple of 8. If the location counter is already a
2678 multiple of 8, no change is needed.
2681 For the HPPA, the first expression (which must be absolute) is the
2682 alignment request in bytes. For example @samp{.align 8} advances
2683 the location counter until it is a multiple of 8. If the location counter
2684 is already a multiple of 8, no change is needed.
2687 The second expression (also absolute) gives the value to be stored in
2688 the padding bytes. It (and the comma) may be omitted. If it is
2689 omitted, the padding bytes are zero.
2692 @section @code{.app-file @var{string}}
2694 @cindex logical file name
2695 @cindex file name, logical
2696 @cindex @code{app-file} directive
2698 @ifclear no-file-dir
2699 (which may also be spelled @samp{.file})
2701 tells @code{@value{AS}} that we are about to start a new
2702 logical file. @var{string} is the new file name. In general, the
2703 filename is recognized whether or not it is surrounded by quotes @samp{"};
2704 but if you wish to specify an empty file name is permitted,
2705 you must give the quotes--@code{""}. This statement may go away in
2706 future: it is only recognized to be compatible with old @code{@value{AS}}
2710 @section @code{.ascii "@var{string}"}@dots{}
2712 @cindex @code{ascii} directive
2713 @cindex string literals
2714 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2715 separated by commas. It assembles each string (with no automatic
2716 trailing zero byte) into consecutive addresses.
2719 @section @code{.asciz "@var{string}"}@dots{}
2721 @cindex @code{asciz} directive
2722 @cindex zero-terminated strings
2723 @cindex null-terminated strings
2724 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2725 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2728 @section @code{.byte @var{expressions}}
2730 @cindex @code{byte} directive
2731 @cindex integers, one byte
2732 @code{.byte} expects zero or more expressions, separated by commas.
2733 Each expression is assembled into the next byte.
2736 @section @code{.comm @var{symbol} , @var{length} }
2738 @cindex @code{comm} directive
2739 @cindex symbol, common
2740 @code{.comm} declares a named common area in the bss section. Normally
2741 @code{@value{LD}} reserves memory addresses for it during linking, so no partial
2742 program defines the location of the symbol. Use @code{.comm} to tell
2743 @code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}}
2744 allocates space for each @code{.comm} symbol that is at least as
2745 long as the longest @code{.comm} request in any of the partial programs
2746 linked. @var{length} is an absolute expression.
2749 The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
2750 @samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
2754 @section @code{.data @var{subsection}}
2756 @cindex @code{data} directive
2757 @code{.data} tells @code{@value{AS}} to assemble the following statements onto the
2758 end of the data subsection numbered @var{subsection} (which is an
2759 absolute expression). If @var{subsection} is omitted, it defaults
2764 @section @code{.def @var{name}}
2766 @cindex @code{def} directive
2767 @cindex COFF symbols, debugging
2768 @cindex debugging COFF symbols
2769 Begin defining debugging information for a symbol @var{name}; the
2770 definition extends until the @code{.endef} directive is encountered.
2773 This directive is only observed when @code{@value{AS}} is configured for COFF
2774 format output; when producing @code{b.out}, @samp{.def} is recognized,
2781 @section @code{.desc @var{symbol}, @var{abs-expression}}
2783 @cindex @code{desc} directive
2784 @cindex COFF symbol descriptor
2785 @cindex symbol descriptor, COFF
2786 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2787 to the low 16 bits of an absolute expression.
2790 The @samp{.desc} directive is not available when @code{@value{AS}} is
2791 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2792 object format. For the sake of compatibility, @code{@value{AS}} accepts
2793 it, but produces no output, when configured for COFF.
2799 @section @code{.dim}
2801 @cindex @code{dim} directive
2802 @cindex COFF auxiliary symbol information
2803 @cindex auxiliary symbol information, COFF
2804 This directive is generated by compilers to include auxiliary debugging
2805 information in the symbol table. It is only permitted inside
2806 @code{.def}/@code{.endef} pairs.
2809 @samp{.dim} is only meaningful when generating COFF format output; when
2810 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
2816 @section @code{.double @var{flonums}}
2818 @cindex @code{double} directive
2819 @cindex floating point numbers (double)
2820 @code{.double} expects zero or more flonums, separated by commas. It
2821 assembles floating point numbers.
2823 The exact kind of floating point numbers emitted depends on how
2824 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
2828 On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
2829 in @sc{ieee} format.
2834 @section @code{.eject}
2836 @cindex @code{eject} directive
2837 @cindex new page, in listings
2838 @cindex page, in listings
2839 @cindex listing control: new page
2840 Force a page break at this point, when generating assembly listings.
2843 @section @code{.else}
2845 @cindex @code{else} directive
2846 @code{.else} is part of the @code{@value{AS}} support for conditional
2847 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2848 of code to be assembled if the condition for the preceding @code{.if}
2852 @node End, Endef, Else, Pseudo Ops
2853 @section @code{.end}
2855 @cindex @code{end} directive
2856 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2857 meant to do something eventually (which is why it isn't documented here
2858 as "for compatibility with blah").
2863 @section @code{.endef}
2865 @cindex @code{endef} directive
2866 This directive flags the end of a symbol definition begun with
2870 @samp{.endef} is only meaningful when generating COFF format output; if
2871 @code{@value{AS}} is configured to generate @code{b.out}, it accepts this
2872 directive but ignores it.
2877 @section @code{.endif}
2879 @cindex @code{endif} directive
2880 @code{.endif} is part of the @code{@value{AS}} support for conditional assembly;
2881 it marks the end of a block of code that is only assembled
2882 conditionally. @xref{If,,@code{.if}}.
2885 @section @code{.equ @var{symbol}, @var{expression}}
2887 @cindex @code{equ} directive
2888 @cindex assigning values to symbols
2889 @cindex symbols, assigning values to
2890 This directive sets the value of @var{symbol} to @var{expression}.
2891 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
2894 The syntax for @code{equ} on the HPPA is
2895 @samp{@var{symbol} .equ @var{expression}}.
2899 @section @code{.extern}
2901 @cindex @code{extern} directive
2902 @code{.extern} is accepted in the source program---for compatibility
2903 with other assemblers---but it is ignored. @code{@value{AS}} treats
2904 all undefined symbols as external.
2906 @ifclear no-file-dir
2908 @section @code{.file @var{string}}
2910 @cindex @code{file} directive
2911 @cindex logical file name
2912 @cindex file name, logical
2913 @code{.file} (which may also be spelled @samp{.app-file}) tells
2914 @code{@value{AS}} that we are about to start a new logical file.
2915 @var{string} is the new file name. In general, the filename is
2916 recognized whether or not it is surrounded by quotes @samp{"}; but if
2917 you wish to specify an empty file name, you must give the
2918 quotes--@code{""}. This statement may go away in future: it is only
2919 recognized to be compatible with old @code{@value{AS}} programs.
2921 In some configurations of @code{@value{AS}}, @code{.file} has already been
2922 removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}.
2927 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
2929 @cindex @code{fill} directive
2930 @cindex writing patterns in memory
2931 @cindex patterns, writing in memory
2932 @var{result}, @var{size} and @var{value} are absolute expressions.
2933 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
2934 may be zero or more. @var{Size} may be zero or more, but if it is
2935 more than 8, then it is deemed to have the value 8, compatible with
2936 other people's assemblers. The contents of each @var{repeat} bytes
2937 is taken from an 8-byte number. The highest order 4 bytes are
2938 zero. The lowest order 4 bytes are @var{value} rendered in the
2939 byte-order of an integer on the computer @code{@value{AS}} is assembling for.
2940 Each @var{size} bytes in a repetition is taken from the lowest order
2941 @var{size} bytes of this number. Again, this bizarre behavior is
2942 compatible with other people's assemblers.
2944 @var{size} and @var{value} are optional.
2945 If the second comma and @var{value} are absent, @var{value} is
2946 assumed zero. If the first comma and following tokens are absent,
2947 @var{size} is assumed to be 1.
2950 @section @code{.float @var{flonums}}
2952 @cindex floating point numbers (single)
2953 @cindex @code{float} directive
2954 This directive assembles zero or more flonums, separated by commas. It
2955 has the same effect as @code{.single}.
2957 The exact kind of floating point numbers emitted depends on how
2958 @code{@value{AS}} is configured.
2959 @xref{Machine Dependencies}.
2963 On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
2964 in @sc{ieee} format.
2969 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2971 @cindex @code{global} directive
2972 @cindex symbol, making visible to linker
2973 @code{.global} makes the symbol visible to @code{@value{LD}}. If you define
2974 @var{symbol} in your partial program, its value is made available to
2975 other partial programs that are linked with it. Otherwise,
2976 @var{symbol} takes its attributes from a symbol of the same name
2977 from another file linked into the same program.
2979 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
2980 compatibility with other assemblers.
2983 On the HPPA symbols are made visible to @code{@value{LD}} with the
2984 @code{.EXPORT} directive.
2988 @section @code{.hword @var{expressions}}
2990 @cindex @code{hword} directive
2991 @cindex integers, 16-bit
2992 @cindex numbers, 16-bit
2993 @cindex sixteen bit integers
2994 This expects zero or more @var{expressions}, and emits
2995 a 16 bit number for each.
2998 This directive is a synonym for @samp{.short}; depending on the target
2999 architecture, it may also be a synonym for @samp{.word}.
3003 This directive is a synonym for @samp{.short}.
3006 This directive is a synonym for both @samp{.short} and @samp{.word}.
3011 @section @code{.ident}
3013 @cindex @code{ident} directive
3014 This directive is used by some assemblers to place tags in object files.
3015 @code{@value{AS}} simply accepts the directive for source-file
3016 compatibility with such assemblers, but does not actually emit anything
3020 @section @code{.if @var{absolute expression}}
3022 @cindex conditional assembly
3023 @cindex @code{if} directive
3024 @code{.if} marks the beginning of a section of code which is only
3025 considered part of the source program being assembled if the argument
3026 (which must be an @var{absolute expression}) is non-zero. The end of
3027 the conditional section of code must be marked by @code{.endif}
3028 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
3029 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
3031 The following variants of @code{.if} are also supported:
3033 @item .ifdef @var{symbol}
3034 @cindex @code{ifdef} directive
3035 Assembles the following section of code if the specified @var{symbol}
3040 @cindex @code{ifeqs} directive
3041 Not yet implemented.
3044 @item .ifndef @var{symbol}
3045 @itemx ifnotdef @var{symbol}
3046 @cindex @code{ifndef} directive
3047 @cindex @code{ifnotdef} directive
3048 Assembles the following section of code if the specified @var{symbol}
3049 has not been defined. Both spelling variants are equivalent.
3053 Not yet implemented.
3058 @section @code{.include "@var{file}"}
3060 @cindex @code{include} directive
3061 @cindex supporting files, including
3062 @cindex files, including
3063 This directive provides a way to include supporting files at specified
3064 points in your source program. The code from @var{file} is assembled as
3065 if it followed the point of the @code{.include}; when the end of the
3066 included file is reached, assembly of the original file continues. You
3067 can control the search paths used with the @samp{-I} command-line option
3068 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
3072 @section @code{.int @var{expressions}}
3074 @cindex @code{int} directive
3075 @cindex integers, 32-bit
3076 Expect zero or more @var{expressions}, of any section, separated by commas.
3077 For each expression, emit a number that, at run time, is the value of that
3078 expression. The byte order and bit size of the number depends on what kind
3079 of target the assembly is for.
3083 On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
3084 integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits
3090 @section @code{.lcomm @var{symbol} , @var{length}}
3092 @cindex @code{lcomm} directive
3093 @cindex local common symbols
3094 @cindex symbols, local common
3095 Reserve @var{length} (an absolute expression) bytes for a local common
3096 denoted by @var{symbol}. The section and value of @var{symbol} are
3097 those of the new local common. The addresses are allocated in the bss
3098 section, so that at run-time the bytes start off zeroed. @var{Symbol}
3099 is not declared global (@pxref{Global,,@code{.global}}), so is normally
3100 not visible to @code{@value{LD}}.
3103 The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
3104 @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
3108 @section @code{.lflags}
3110 @cindex @code{lflags} directive (ignored)
3111 @code{@value{AS}} accepts this directive, for compatibility with other
3112 assemblers, but ignores it.
3114 @ifclear no-line-dir
3116 @section @code{.line @var{line-number}}
3118 @cindex @code{line} directive
3122 @section @code{.ln @var{line-number}}
3124 @cindex @code{ln} directive
3126 @cindex logical line number
3128 Change the logical line number. @var{line-number} must be an absolute
3129 expression. The next line has that logical line number. Therefore any other
3130 statements on the current line (after a statement separator character) are
3131 reported as on logical line number @var{line-number} @minus{} 1. One day
3132 @code{@value{AS}} will no longer support this directive: it is recognized only
3133 for compatibility with existing assembler programs.
3137 @emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
3138 only available with the name @code{.ln}, rather than as either
3139 @code{.line} or @code{.ln}.
3144 @ifclear no-line-dir
3145 Even though this is a directive associated with the @code{a.out} or
3146 @code{b.out} object-code formats, @code{@value{AS}} still recognizes it
3147 when producing COFF output, and treats @samp{.line} as though it
3148 were the COFF @samp{.ln} @emph{if} it is found outside a
3149 @code{.def}/@code{.endef} pair.
3151 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
3152 used by compilers to generate auxiliary symbol information for
3157 @section @code{.ln @var{line-number}}
3159 @cindex @code{ln} directive
3160 @ifclear no-line-dir
3161 @samp{.ln} is a synonym for @samp{.line}.
3164 Tell @code{@value{AS}} to change the logical line number. @var{line-number}
3165 must be an absolute expression. The next line has that logical
3166 line number, so any other statements on the current line (after a
3167 statement separator character @code{;}) are reported as on logical
3168 line number @var{line-number} @minus{} 1.
3171 This directive is accepted, but ignored, when @code{@value{AS}} is
3172 configured for @code{b.out}; its effect is only associated with COFF
3178 @section @code{.list}
3180 @cindex @code{list} directive
3181 @cindex listing control, turning on
3182 Control (in conjunction with the @code{.nolist} directive) whether or
3183 not assembly listings are generated. These two directives maintain an
3184 internal counter (which is zero initially). @code{.list} increments the
3185 counter, and @code{.nolist} decrements it. Assembly listings are
3186 generated whenever the counter is greater than zero.
3188 By default, listings are disabled. When you enable them (with the
3189 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
3190 the initial value of the listing counter is one.
3193 @section @code{.long @var{expressions}}
3195 @cindex @code{long} directive
3196 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
3199 @c no one seems to know what this is for or whether this description is
3200 @c what it really ought to do
3202 @section @code{.lsym @var{symbol}, @var{expression}}
3204 @cindex @code{lsym} directive
3205 @cindex symbol, not referenced in assembly
3206 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
3207 the hash table, ensuring it cannot be referenced by name during the
3208 rest of the assembly. This sets the attributes of the symbol to be
3209 the same as the expression value:
3211 @var{other} = @var{descriptor} = 0
3212 @var{type} = @r{(section of @var{expression})}
3213 @var{value} = @var{expression}
3216 The new symbol is not flagged as external.
3220 @section @code{.nolist}
3222 @cindex @code{nolist} directive
3223 @cindex listing control, turning off
3224 Control (in conjunction with the @code{.list} directive) whether or
3225 not assembly listings are generated. These two directives maintain an
3226 internal counter (which is zero initially). @code{.list} increments the
3227 counter, and @code{.nolist} decrements it. Assembly listings are
3228 generated whenever the counter is greater than zero.
3231 @section @code{.octa @var{bignums}}
3233 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
3234 @cindex @code{octa} directive
3235 @cindex integer, 16-byte
3236 @cindex sixteen byte integer
3237 This directive expects zero or more bignums, separated by commas. For each
3238 bignum, it emits a 16-byte integer.
3240 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
3241 hence @emph{octa}-word for 16 bytes.
3244 @section @code{.org @var{new-lc} , @var{fill}}
3246 @cindex @code{org} directive
3247 @cindex location counter, advancing
3248 @cindex advancing location counter
3249 @cindex current address, advancing
3250 Advance the location counter of the current section to
3251 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3252 expression with the same section as the current subsection. That is,
3253 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3254 wrong section, the @code{.org} directive is ignored. To be compatible
3255 with former assemblers, if the section of @var{new-lc} is absolute,
3256 @code{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
3257 is the same as the current subsection.
3259 @code{.org} may only increase the location counter, or leave it
3260 unchanged; you cannot use @code{.org} to move the location counter
3263 @c double negative used below "not undefined" because this is a specific
3264 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3265 @c section. pesch@cygnus.com 18feb91
3266 Because @code{@value{AS}} tries to assemble programs in one pass @var{new-lc}
3267 may not be undefined. If you really detest this restriction we eagerly await
3268 a chance to share your improved assembler.
3270 Beware that the origin is relative to the start of the section, not
3271 to the start of the subsection. This is compatible with other
3272 people's assemblers.
3274 When the location counter (of the current subsection) is advanced, the
3275 intervening bytes are filled with @var{fill} which should be an
3276 absolute expression. If the comma and @var{fill} are omitted,
3277 @var{fill} defaults to zero.
3280 @section @code{.psize @var{lines} , @var{columns}}
3282 @cindex @code{psize} directive
3283 @cindex listing control: paper size
3284 @cindex paper size, for listings
3285 Use this directive to declare the number of lines---and, optionally, the
3286 number of columns---to use for each page, when generating listings.
3288 If you do not use @code{.psize}, listings use a default line-count
3289 of 60. You may omit the comma and @var{columns} specification; the
3290 default width is 200 columns.
3292 @code{@value{AS}} generates formfeeds whenever the specified number of
3293 lines is exceeded (or whenever you explicitly request one, using
3296 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3297 those explicitly specified with @code{.eject}.
3300 @section @code{.quad @var{bignums}}
3302 @cindex @code{quad} directive
3303 @code{.quad} expects zero or more bignums, separated by commas. For
3304 each bignum, it emits
3306 an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
3307 warning message; and just takes the lowest order 8 bytes of the bignum.
3308 @cindex eight-byte integer
3309 @cindex integer, 8-byte
3311 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3312 hence @emph{quad}-word for 8 bytes.
3315 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3316 warning message; and just takes the lowest order 16 bytes of the bignum.
3317 @cindex sixteen-byte integer
3318 @cindex integer, 16-byte
3322 @section @code{.sbttl "@var{subheading}"}
3324 @cindex @code{sbttl} directive
3325 @cindex subtitles for listings
3326 @cindex listing control: subtitle
3327 Use @var{subheading} as the title (third line, immediately after the
3328 title line) when generating assembly listings.
3330 This directive affects subsequent pages, as well as the current page if
3331 it appears within ten lines of the top of a page.
3335 @section @code{.scl @var{class}}
3337 @cindex @code{scl} directive
3338 @cindex symbol storage class (COFF)
3339 @cindex COFF symbol storage class
3340 Set the storage-class value for a symbol. This directive may only be
3341 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3342 whether a symbol is static or external, or it may record further
3343 symbolic debugging information.
3346 The @samp{.scl} directive is primarily associated with COFF output; when
3347 configured to generate @code{b.out} output format, @code{@value{AS}}
3348 accepts this directive but ignores it.
3354 @section @code{.section @var{name}, @var{subsection}}
3356 @cindex @code{section} directive
3357 @cindex named section (COFF)
3358 @cindex COFF named section
3359 Assemble the following code into end of subsection numbered
3360 @var{subsection} in the COFF named section @var{name}. If you omit
3361 @var{subsection}, @code{@value{AS}} uses subsection number zero.
3362 @samp{.section .text} is equivalent to the @code{.text} directive;
3363 @samp{.section .data} is equivalent to the @code{.data} directive.
3367 @section @code{.set @var{symbol}, @var{expression}}
3369 @cindex @code{set} directive
3370 @cindex symbol value, setting
3371 Set the value of @var{symbol} to @var{expression}. This
3372 changes @var{symbol}'s value and type to conform to
3373 @var{expression}. If @var{symbol} was flagged as external, it remains
3374 flagged. (@xref{Symbol Attributes}.)
3376 You may @code{.set} a symbol many times in the same assembly.
3377 If the expression's section is unknowable during pass 1, a second
3378 pass over the source program is necessary. The second pass is
3379 currently not implemented. @code{@value{AS}} aborts with an error
3380 message if one is required.
3382 If you @code{.set} a global symbol, the value stored in the object
3383 file is the last value stored into it.
3386 The syntax for @code{set} on the HPPA is
3387 @samp{@var{symbol} .set @var{expression}}.
3391 @section @code{.short @var{expressions}}
3393 @cindex @code{short} directive
3395 @code{.short} is normally the same as @samp{.word}.
3396 @xref{Word,,@code{.word}}.
3398 In some configurations, however, @code{.short} and @code{.word} generate
3399 numbers of different lengths; @pxref{Machine Dependencies}.
3403 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3406 This expects zero or more @var{expressions}, and emits
3407 a 16 bit number for each.
3412 @section @code{.single @var{flonums}}
3414 @cindex @code{single} directive
3415 @cindex floating point numbers (single)
3416 This directive assembles zero or more flonums, separated by commas. It
3417 has the same effect as @code{.float}.
3419 The exact kind of floating point numbers emitted depends on how
3420 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
3424 On the @value{TARGET} family, @code{.single} emits 32-bit floating point
3425 numbers in @sc{ieee} format.
3431 @section @code{.size}
3433 @cindex @code{size} directive
3434 This directive is generated by compilers to include auxiliary debugging
3435 information in the symbol table. It is only permitted inside
3436 @code{.def}/@code{.endef} pairs.
3439 @samp{.size} is only meaningful when generating COFF format output; when
3440 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3445 @ifclear no-space-dir
3447 @section @code{.space @var{size} , @var{fill}}
3449 @cindex @code{space} directive
3450 @cindex filling memory
3451 This directive emits @var{size} bytes, each of value @var{fill}. Both
3452 @var{size} and @var{fill} are absolute expressions. If the comma
3453 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3457 @emph{Warning:} @code{.space} has a completely different meaning for HPPA
3458 targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800
3459 Assembly Language Reference Manual} (HP 92432-90001) for the meaning of
3460 the @code{.space} directive.
3468 @section @code{.space}
3469 @cindex @code{space} directive
3471 On the AMD 29K, this directive is ignored; it is accepted for
3472 compatibility with other AMD 29K assemblers.
3475 @emph{Warning:} In most versions of the GNU assembler, the directive
3476 @code{.space} has the effect of @code{.block} @xref{Machine Dependencies}.
3482 @section @code{.stabd, .stabn, .stabs}
3484 @cindex symbolic debuggers, information for
3485 @cindex @code{stab@var{x}} directives
3486 There are three directives that begin @samp{.stab}.
3487 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3488 The symbols are not entered in the @code{@value{AS}} hash table: they
3489 cannot be referenced elsewhere in the source file.
3490 Up to five fields are required:
3494 This is the symbol's name. It may contain any character except
3495 @samp{\000}, so is more general than ordinary symbol names. Some
3496 debuggers used to code arbitrarily complex structures into symbol names
3500 An absolute expression. The symbol's type is set to the low 8 bits of
3501 this expression. Any bit pattern is permitted, but @code{@value{LD}}
3502 and debuggers choke on silly bit patterns.
3505 An absolute expression. The symbol's ``other'' attribute is set to the
3506 low 8 bits of this expression.
3509 An absolute expression. The symbol's descriptor is set to the low 16
3510 bits of this expression.
3513 An absolute expression which becomes the symbol's value.
3516 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3517 or @code{.stabs} statement, the symbol has probably already been created;
3518 you get a half-formed symbol in your object file. This is
3519 compatible with earlier assemblers!
3522 @cindex @code{stabd} directive
3523 @item .stabd @var{type} , @var{other} , @var{desc}
3525 The ``name'' of the symbol generated is not even an empty string.
3526 It is a null pointer, for compatibility. Older assemblers used a
3527 null pointer so they didn't waste space in object files with empty
3530 The symbol's value is set to the location counter,
3531 relocatably. When your program is linked, the value of this symbol
3532 is the address of the location counter when the @code{.stabd} was
3535 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3536 @cindex @code{stabn} directive
3537 The name of the symbol is set to the empty string @code{""}.
3539 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3540 @cindex @code{stabs} directive
3541 All five fields are specified.
3548 @section @code{.tag @var{structname}}
3550 @cindex COFF structure debugging
3551 @cindex structure debugging, COFF
3552 @cindex @code{tag} directive
3553 This directive is generated by compilers to include auxiliary debugging
3554 information in the symbol table. It is only permitted inside
3555 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3556 definitions in the symbol table with instances of those structures.
3559 @samp{.tag} is only used when generating COFF format output; when
3560 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3566 @section @code{.text @var{subsection}}
3568 @cindex @code{text} directive
3569 Tells @code{@value{AS}} to assemble the following statements onto the end of
3570 the text subsection numbered @var{subsection}, which is an absolute
3571 expression. If @var{subsection} is omitted, subsection number zero
3575 @section @code{.title "@var{heading}"}
3577 @cindex @code{title} directive
3578 @cindex listing control: title line
3579 Use @var{heading} as the title (second line, immediately after the
3580 source file name and pagenumber) when generating assembly listings.
3582 This directive affects subsequent pages, as well as the current page if
3583 it appears within ten lines of the top of a page.
3587 @section @code{.type @var{int}}
3589 @cindex COFF symbol type
3590 @cindex symbol type, COFF
3591 @cindex @code{type} directive
3592 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3593 records the integer @var{int} as the type attribute of a symbol table entry.
3596 @samp{.type} is associated only with COFF format output; when
3597 @code{@value{AS}} is configured for @code{b.out} output, it accepts this
3598 directive but ignores it.
3604 @section @code{.val @var{addr}}
3606 @cindex @code{val} directive
3607 @cindex COFF value attribute
3608 @cindex value attribute, COFF
3609 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3610 records the address @var{addr} as the value attribute of a symbol table
3614 @samp{.val} is used only for COFF output; when @code{@value{AS}} is
3615 configured for @code{b.out}, it accepts this directive but ignores it.
3620 @section @code{.word @var{expressions}}
3622 @cindex @code{word} directive
3623 This directive expects zero or more @var{expressions}, of any section,
3624 separated by commas.
3627 For each expression, @code{@value{AS}} emits a 32-bit number.
3630 For each expression, @code{@value{AS}} emits a 16-bit number.
3635 The size of the number emitted, and its byte order,
3636 depend on what target computer the assembly is for.
3639 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3640 @c happen---32-bit addressability, period; no long/short jumps.
3641 @ifset DIFF-TBL-KLUGE
3642 @cindex difference tables altered
3643 @cindex altered difference tables
3645 @emph{Warning: Special Treatment to support Compilers}
3649 Machines with a 32-bit address space, but that do less than 32-bit
3650 addressing, require the following special treatment. If the machine of
3651 interest to you does 32-bit addressing (or doesn't require it;
3652 @pxref{Machine Dependencies}), you can ignore this issue.
3655 In order to assemble compiler output into something that works,
3656 @code{@value{AS}} occasionlly does strange things to @samp{.word} directives.
3657 Directives of the form @samp{.word sym1-sym2} are often emitted by
3658 compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a
3659 directive of the form @samp{.word sym1-sym2}, and the difference between
3660 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}}
3661 creates a @dfn{secondary jump table}, immediately before the next label.
3662 This secondary jump table is preceded by a short-jump to the
3663 first byte after the secondary table. This short-jump prevents the flow
3664 of control from accidentally falling into the new table. Inside the
3665 table is a long-jump to @code{sym2}. The original @samp{.word}
3666 contains @code{sym1} minus the address of the long-jump to
3669 If there were several occurrences of @samp{.word sym1-sym2} before the
3670 secondary jump table, all of them are adjusted. If there was a
3671 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3672 long-jump to @code{sym4} is included in the secondary jump table,
3673 and the @code{.word} directives are adjusted to contain @code{sym3}
3674 minus the address of the long-jump to @code{sym4}; and so on, for as many
3675 entries in the original jump table as necessary.
3678 @emph{This feature may be disabled by compiling @code{@value{AS}} with the
3679 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3680 assembly language programmers.
3683 @c end DIFF-TBL-KLUGE
3686 @section Deprecated Directives
3688 @cindex deprecated directives
3689 @cindex obsolescent directives
3690 One day these directives won't work.
3691 They are included for compatibility with older assemblers.
3699 @node Machine Dependencies
3700 @chapter Machine Dependent Features
3702 @cindex machine dependencies
3703 The machine instruction sets are (almost by definition) different on
3704 each machine where @code{@value{AS}} runs. Floating point representations
3705 vary as well, and @code{@value{AS}} often supports a few additional
3706 directives or command-line options for compatibility with other
3707 assemblers on a particular platform. Finally, some versions of
3708 @code{@value{AS}} support special pseudo-instructions for branch
3711 This chapter discusses most of these differences, though it does not
3712 include details on any machine's instruction set. For details on that
3713 subject, see the hardware manufacturer's manual.
3717 * Vax-Dependent:: VAX Dependent Features
3720 * AMD29K-Dependent:: AMD 29K Dependent Features
3723 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
3726 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
3729 * HPPA-Dependent:: HPPA Dependent Features
3732 * SH-Dependent:: Hitachi SH Dependent Features
3735 * i960-Dependent:: Intel 80960 Dependent Features
3738 * M68K-Dependent:: M680x0 Dependent Features
3741 * Sparc-Dependent:: SPARC Dependent Features
3744 * Z8000-Dependent:: Z8000 Dependent Features
3747 * i386-Dependent:: 80386 Dependent Features
3754 @c The following major nodes are *sections* in the GENERIC version, *chapters*
3755 @c in single-cpu versions. This is mainly achieved by @lowersections. There is a
3756 @c peculiarity: to preserve cross-references, there must be a node called
3757 @c "Machine Dependencies". Hence the conditional nodenames in each
3758 @c major node below. Node defaulting in makeinfo requires adjacency of
3759 @c node and sectioning commands; hence the repetition of @chapter BLAH
3760 @c in both conditional blocks.
3765 @chapter VAX Dependent Features
3770 @node Machine Dependencies
3771 @chapter VAX Dependent Features
3777 * Vax-Opts:: VAX Command-Line Options
3778 * VAX-float:: VAX Floating Point
3779 * VAX-directives:: Vax Machine Directives
3780 * VAX-opcodes:: VAX Opcodes
3781 * VAX-branch:: VAX Branch Improvement
3782 * VAX-operands:: VAX Operands
3783 * VAX-no:: Not Supported on VAX
3788 @section VAX Command-Line Options
3790 @cindex command-line options ignored, VAX
3791 @cindex VAX command-line options ignored
3792 The Vax version of @code{@value{AS}} accepts any of the following options,
3793 gives a warning message that the option was ignored and proceeds.
3794 These options are for compatibility with scripts designed for other
3795 people's assemblers.
3798 @item @samp{-D} (Debug)
3799 @itemx @samp{-S} (Symbol Table)
3800 @itemx @samp{-T} (Token Trace)
3801 @cindex @code{-D}, ignored on VAX
3802 @cindex @code{-S}, ignored on VAX
3803 @cindex @code{-T}, ignored on VAX
3804 These are obsolete options used to debug old assemblers.
3806 @item @samp{-d} (Displacement size for JUMPs)
3807 @cindex @code{-d}, VAX option
3808 This option expects a number following the @samp{-d}. Like options
3809 that expect filenames, the number may immediately follow the
3810 @samp{-d} (old standard) or constitute the whole of the command line
3811 argument that follows @samp{-d} (GNU standard).
3813 @item @samp{-V} (Virtualize Interpass Temporary File)
3814 @cindex @code{-V}, redundant on VAX
3815 Some other assemblers use a temporary file. This option
3816 commanded them to keep the information in active memory rather
3817 than in a disk file. @code{@value{AS}} always does this, so this
3818 option is redundant.
3820 @item @samp{-J} (JUMPify Longer Branches)
3821 @cindex @code{-J}, ignored on VAX
3822 Many 32-bit computers permit a variety of branch instructions
3823 to do the same job. Some of these instructions are short (and
3824 fast) but have a limited range; others are long (and slow) but
3825 can branch anywhere in virtual memory. Often there are 3
3826 flavors of branch: short, medium and long. Some other
3827 assemblers would emit short and medium branches, unless told by
3828 this option to emit short and long branches.
3830 @item @samp{-t} (Temporary File Directory)
3831 @cindex @code{-t}, ignored on VAX
3832 Some other assemblers may use a temporary file, and this option
3833 takes a filename being the directory to site the temporary
3834 file. Since @code{@value{AS}} does not use a temporary disk file, this
3835 option makes no difference. @samp{-t} needs exactly one
3839 @cindex VMS (VAX) options
3840 @cindex options for VAX/VMS
3841 @cindex VAX/VMS options
3842 @cindex @code{-h} option, VAX/VMS
3843 @cindex @code{-+} option, VAX/VMS
3844 @cindex Vax-11 C compatibility
3845 @cindex symbols with lowercase, VAX/VMS
3846 @c FIXME! look into "I think" below, correct if needed, delete.
3847 The Vax version of the assembler accepts two options when
3848 compiled for VMS. They are @samp{-h}, and @samp{-+}. The
3849 @samp{-h} option prevents @code{@value{AS}} from modifying the
3850 symbol-table entries for symbols that contain lowercase
3851 characters (I think). The @samp{-+} option causes @code{@value{AS}} to
3852 print warning messages if the FILENAME part of the object file,
3853 or any symbol name is larger than 31 characters. The @samp{-+}
3854 option also inserts some code following the @samp{_main}
3855 symbol so that the object file is compatible with Vax-11
3859 @section VAX Floating Point
3861 @cindex VAX floating point
3862 @cindex floating point, VAX
3863 Conversion of flonums to floating point is correct, and
3864 compatible with previous assemblers. Rounding is
3865 towards zero if the remainder is exactly half the least significant bit.
3867 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
3870 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
3871 are rendered correctly. Again, rounding is towards zero in the
3874 @cindex @code{float} directive, VAX
3875 @cindex @code{double} directive, VAX
3876 The @code{.float} directive produces @code{f} format numbers.
3877 The @code{.double} directive produces @code{d} format numbers.
3879 @node VAX-directives
3880 @section Vax Machine Directives
3882 @cindex machine directives, VAX
3883 @cindex VAX machine directives
3884 The Vax version of the assembler supports four directives for
3885 generating Vax floating point constants. They are described in the
3888 @cindex wide floating point directives, VAX
3891 @cindex @code{dfloat} directive, VAX
3892 This expects zero or more flonums, separated by commas, and
3893 assembles Vax @code{d} format 64-bit floating point constants.
3896 @cindex @code{ffloat} directive, VAX
3897 This expects zero or more flonums, separated by commas, and
3898 assembles Vax @code{f} format 32-bit floating point constants.
3901 @cindex @code{gfloat} directive, VAX
3902 This expects zero or more flonums, separated by commas, and
3903 assembles Vax @code{g} format 64-bit floating point constants.
3906 @cindex @code{hfloat} directive, VAX
3907 This expects zero or more flonums, separated by commas, and
3908 assembles Vax @code{h} format 128-bit floating point constants.
3913 @section VAX Opcodes
3915 @cindex VAX opcode mnemonics
3916 @cindex opcode mnemonics, VAX
3917 @cindex mnemonics for opcodes, VAX
3918 All DEC mnemonics are supported. Beware that @code{case@dots{}}
3919 instructions have exactly 3 operands. The dispatch table that
3920 follows the @code{case@dots{}} instruction should be made with
3921 @code{.word} statements. This is compatible with all unix
3922 assemblers we know of.
3925 @section VAX Branch Improvement
3927 @cindex VAX branch improvement
3928 @cindex branch improvement, VAX
3929 @cindex pseudo-ops for branch, VAX
3930 Certain pseudo opcodes are permitted. They are for branch
3931 instructions. They expand to the shortest branch instruction that
3932 reaches the target. Generally these mnemonics are made by
3933 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
3934 This feature is included both for compatibility and to help
3935 compilers. If you do not need this feature, avoid these
3936 opcodes. Here are the mnemonics, and the code they can expand into.
3940 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
3942 @item (byte displacement)
3944 @item (word displacement)
3946 @item (long displacement)
3951 Unconditional branch.
3953 @item (byte displacement)
3955 @item (word displacement)
3957 @item (long displacement)
3961 @var{COND} may be any one of the conditional branches
3962 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
3963 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
3964 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
3965 @var{COND} may also be one of the bit tests
3966 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
3967 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
3968 @var{NOTCOND} is the opposite condition to @var{COND}.
3970 @item (byte displacement)
3971 @kbd{b@var{COND} @dots{}}
3972 @item (word displacement)
3973 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
3974 @item (long displacement)
3975 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
3978 @var{X} may be one of @code{b d f g h l w}.
3980 @item (word displacement)
3981 @kbd{@var{OPCODE} @dots{}}
3982 @item (long displacement)
3984 @var{OPCODE} @dots{}, foo ;
3991 @var{YYY} may be one of @code{lss leq}.
3993 @var{ZZZ} may be one of @code{geq gtr}.
3995 @item (byte displacement)
3996 @kbd{@var{OPCODE} @dots{}}
3997 @item (word displacement)
3999 @var{OPCODE} @dots{}, foo ;
4001 foo: brw @var{destination} ;
4004 @item (long displacement)
4006 @var{OPCODE} @dots{}, foo ;
4008 foo: jmp @var{destination} ;
4017 @item (byte displacement)
4018 @kbd{@var{OPCODE} @dots{}}
4019 @item (word displacement)
4021 @var{OPCODE} @dots{}, foo ;
4023 foo: brw @var{destination} ;
4026 @item (long displacement)
4028 @var{OPCODE} @dots{}, foo ;
4030 foo: jmp @var{destination} ;
4037 @section VAX Operands
4039 @cindex VAX operand notation
4040 @cindex operand notation, VAX
4041 @cindex immediate character, VAX
4042 @cindex VAX immediate character
4043 The immediate character is @samp{$} for Unix compatibility, not
4044 @samp{#} as DEC writes it.
4046 @cindex indirect character, VAX
4047 @cindex VAX indirect character
4048 The indirect character is @samp{*} for Unix compatibility, not
4049 @samp{@@} as DEC writes it.
4051 @cindex displacement sizing character, VAX
4052 @cindex VAX displacement sizing character
4053 The displacement sizing character is @samp{`} (an accent grave) for
4054 Unix compatibility, not @samp{^} as DEC writes it. The letter
4055 preceding @samp{`} may have either case. @samp{G} is not
4056 understood, but all other letters (@code{b i l s w}) are understood.
4058 @cindex register names, VAX
4059 @cindex VAX register names
4060 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
4061 pc}. Upper and lower case letters are equivalent.
4068 Any expression is permitted in an operand. Operands are comma
4071 @c There is some bug to do with recognizing expressions
4072 @c in operands, but I forget what it is. It is
4073 @c a syntax clash because () is used as an address mode
4074 @c and to encapsulate sub-expressions.
4077 @section Not Supported on VAX
4079 @cindex VAX bitfields not supported
4080 @cindex bitfields, not supported on VAX
4081 Vax bit fields can not be assembled with @code{@value{AS}}. Someone
4082 can add the required code if they really need it.
4088 @node AMD29K-Dependent
4089 @chapter AMD 29K Dependent Features
4092 @node Machine Dependencies
4093 @chapter AMD 29K Dependent Features
4096 @cindex AMD 29K support
4099 * AMD29K Options:: Options
4100 * AMD29K Syntax:: Syntax
4101 * AMD29K Floating Point:: Floating Point
4102 * AMD29K Directives:: AMD 29K Machine Directives
4103 * AMD29K Opcodes:: Opcodes
4106 @node AMD29K Options
4108 @cindex AMD 29K options (none)
4109 @cindex options for AMD29K (none)
4110 @code{@value{AS}} has no additional command-line options for the AMD
4116 * AMD29K-Chars:: Special Characters
4117 * AMD29K-Regs:: Register Names
4121 @subsection Special Characters
4123 @cindex line comment character, AMD 29K
4124 @cindex AMD 29K line comment character
4125 @samp{;} is the line comment character.
4127 @cindex line separator, AMD 29K
4128 @cindex AMD 29K line separator
4129 @cindex statement separator, AMD 29K
4130 @cindex AMD 29K statement separator
4131 @samp{@@} can be used instead of a newline to separate statements.
4133 @cindex identifiers, AMD 29K
4134 @cindex AMD 29K identifiers
4135 The character @samp{?} is permitted in identifiers (but may not begin
4139 @subsection Register Names
4141 @cindex AMD 29K register names
4142 @cindex register names, AMD 29K
4143 General-purpose registers are represented by predefined symbols of the
4144 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
4145 (for local registers), where @var{nnn} represents a number between
4146 @code{0} and @code{127}, written with no leading zeros. The leading
4147 letters may be in either upper or lower case; for example, @samp{gr13}
4148 and @samp{LR7} are both valid register names.
4150 You may also refer to general-purpose registers by specifying the
4151 register number as the result of an expression (prefixed with @samp{%%}
4152 to flag the expression as a register number):
4157 ---where @var{expression} must be an absolute expression evaluating to a
4158 number between @code{0} and @code{255}. The range [0, 127] refers to
4159 global registers, and the range [128, 255] to local registers.
4161 @cindex special purpose registers, AMD 29K
4162 @cindex AMD 29K special purpose registers
4163 @cindex protected registers, AMD 29K
4164 @cindex AMD 29K protected registers
4165 In addition, @code{@value{AS}} understands the following protected
4166 special-purpose register names for the AMD 29K family:
4176 These unprotected special-purpose register names are also recognized:
4184 @node AMD29K Floating Point
4185 @section Floating Point
4187 @cindex floating point, AMD 29K (@sc{ieee})
4188 @cindex AMD 29K floating point (@sc{ieee})
4189 The AMD 29K family uses @sc{ieee} floating-point numbers.
4191 @node AMD29K Directives
4192 @section AMD 29K Machine Directives
4194 @cindex machine directives, AMD 29K
4195 @cindex AMD 29K machine directives
4197 @item .block @var{size} , @var{fill}
4198 @cindex @code{block} directive, AMD 29K
4199 This directive emits @var{size} bytes, each of value @var{fill}. Both
4200 @var{size} and @var{fill} are absolute expressions. If the comma
4201 and @var{fill} are omitted, @var{fill} is assumed to be zero.
4203 In other versions of the GNU assembler, this directive is called
4209 @cindex @code{cputype} directive, AMD 29K
4210 This directive is ignored; it is accepted for compatibility with other
4214 @cindex @code{file} directive, AMD 29K
4215 This directive is ignored; it is accepted for compatibility with other
4219 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
4220 used for the directive called @code{.app-file} in the AMD 29K support.
4224 @cindex @code{line} directive, AMD 29K
4225 This directive is ignored; it is accepted for compatibility with other
4229 @c since we're ignoring .lsym...
4230 @item .reg @var{symbol}, @var{expression}
4231 @cindex @code{reg} directive, AMD 29K
4232 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
4236 @cindex @code{sect} directive, AMD 29K
4237 This directive is ignored; it is accepted for compatibility with other
4240 @item .use @var{section name}
4241 @cindex @code{use} directive, AMD 29K
4242 Establishes the section and subsection for the following code;
4243 @var{section name} may be one of @code{.text}, @code{.data},
4244 @code{.data1}, or @code{.lit}. With one of the first three @var{section
4245 name} options, @samp{.use} is equivalent to the machine directive
4246 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
4250 @node AMD29K Opcodes
4253 @cindex AMD 29K opcodes
4254 @cindex opcodes for AMD 29K
4255 @code{@value{AS}} implements all the standard AMD 29K opcodes. No
4256 additional pseudo-instructions are needed on this family.
4258 For information on the 29K machine instruction set, see @cite{Am29000
4259 User's Manual}, Advanced Micro Devices, Inc.
4264 @node Machine Dependencies
4265 @chapter Machine Dependent Features
4267 The machine instruction sets are different on each Hitachi chip family,
4268 and there are also some syntax differences among the families. This
4269 chapter describes the specific @code{@value{AS}} features for each
4273 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
4274 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
4275 * SH-Dependent:: Hitachi SH Dependent Features
4285 @node H8/300-Dependent
4286 @chapter H8/300 Dependent Features
4288 @cindex H8/300 support
4290 * H8/300 Options:: Options
4291 * H8/300 Syntax:: Syntax
4292 * H8/300 Floating Point:: Floating Point
4293 * H8/300 Directives:: H8/300 Machine Directives
4294 * H8/300 Opcodes:: Opcodes
4297 @node H8/300 Options
4300 @cindex H8/300 options (none)
4301 @cindex options, H8/300 (none)
4302 @code{@value{AS}} has no additional command-line options for the Hitachi
4308 * H8/300-Chars:: Special Characters
4309 * H8/300-Regs:: Register Names
4310 * H8/300-Addressing:: Addressing Modes
4314 @subsection Special Characters
4316 @cindex line comment character, H8/300
4317 @cindex H8/300 line comment character
4318 @samp{;} is the line comment character.
4320 @cindex line separator, H8/300
4321 @cindex statement separator, H8/300
4322 @cindex H8/300 line separator
4323 @samp{$} can be used instead of a newline to separate statements.
4324 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4327 @subsection Register Names
4329 @cindex H8/300 registers
4330 @cindex register names, H8/300
4331 You can use predefined symbols of the form @samp{r@var{n}h} and
4332 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4333 general-purpose registers. @var{n} is a digit from @samp{0} to
4334 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4337 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4338 to the H8/300 registers as 16-bit registers (you must use this form for
4341 On the H8/300H, you can also use the eight predefined symbols
4342 @samp{er@var{n}} (@samp{er0} @dots{} @samp{er7}) to refer to the 32-bit
4343 general purpose registers.
4345 The two control registers are called @code{pc} (program counter; a
4346 16-bit register, except on the H8/300H where it is 24 bits) and
4347 @code{ccr} (condition code register; an 8-bit register). @code{r7} is
4348 used as the stack pointer, and can also be called @code{sp}.
4350 @node H8/300-Addressing
4351 @subsection Addressing Modes
4353 @cindex addressing modes, H8/300
4354 @cindex H8/300 addressing modes
4355 @value{AS} understands the following addressing modes for the H8/300:
4363 @item @@(@var{d}, r@var{n})
4364 @itemx @@(@var{d}:16, r@var{n})
4365 @itemx @@(@var{d}:24, r@var{n})
4366 Register indirect: 16-bit or 24-bit displacement @var{d} from register
4367 @var{n}. (24-bit displacements are only meaningful on the H8/300H.)
4370 Register indirect with post-increment
4373 Register indirect with pre-decrement
4375 @item @code{@@}@var{aa}
4376 @itemx @code{@@}@var{aa}:8
4377 @itemx @code{@@}@var{aa}:16
4378 @itemx @code{@@}@var{aa}:24
4379 Absolute address @code{aa}. (The address size @samp{:24} only makes
4380 sense on the H8/300H.)
4386 Immediate data @var{xx}. You may specify the @samp{:8}, @samp{:16}, or
4387 @samp{:32} for clarity, if you wish; but @code{@value{AS}} neither
4388 requires this nor uses it---the data size required is taken from
4391 @item @code{@@}@code{@@}@var{aa}
4392 @itemx @code{@@}@code{@@}@var{aa}:8
4393 Memory indirect. You may specify the @samp{:8} for clarity, if you
4394 wish; but @code{@value{AS}} neither requires this nor uses it.
4397 @node H8/300 Floating Point
4398 @section Floating Point
4400 @cindex floating point, H8/300 (@sc{ieee})
4401 @cindex H8/300 floating point (@sc{ieee})
4402 The H8/300 family has no hardware floating point, but the @code{.float}
4403 directive generates @sc{ieee} floating-point numbers for compatibility
4404 with other development tools.
4407 @node H8/300 Directives
4408 @section H8/300 Machine Directives
4410 @cindex H8/300 machine directives (none)
4411 @cindex machine directives, H8/300 (none)
4412 @cindex @code{word} directive, H8/300
4413 @cindex @code{int} directive, H8/300
4414 @code{@value{AS}} has only one machine-dependent directive for the
4419 @cindex H8/300H, assembling for
4420 Recognize and emit additional instructions for the H8/300H variant, and
4421 also make @code{.int} emit 32-bit numbers rather than the usual (16-bit)
4422 for the H8/300 family.
4425 On the H8/300 family (including the H8/300H) @samp{.word} directives
4426 generate 16-bit numbers.
4428 @node H8/300 Opcodes
4431 @cindex H8/300 opcode summary
4432 @cindex opcode summary, H8/300
4433 @cindex mnemonics, H8/300
4434 @cindex instruction summary, H8/300
4435 For detailed information on the H8/300 machine instruction set, see
4436 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025). For
4437 information specific to the H8/300H, see @cite{H8/300H Series
4438 Programming Manual} (Hitachi).
4440 @code{@value{AS}} implements all the standard H8/300 opcodes. No additional
4441 pseudo-instructions are needed on this family.
4443 The following table summarizes the H8/300 opcodes, and their arguments.
4444 Entries marked @samp{*} are opcodes used only on the H8/300H.
4447 @c Using @group seems to use the normal baselineskip, not the smallexample
4448 @c baselineskip; looks approx doublespaced.
4450 Rs @r{source register}
4451 Rd @r{destination register}
4452 abs @r{absolute address}
4453 imm @r{immediate data}
4454 disp:N @r{N-bit displacement from a register}
4455 pcrel:N @r{N-bit displacement relative to program counter}
4457 add.b #imm,rd * andc #imm,ccr
4458 add.b rs,rd band #imm,rd
4459 add.w rs,rd band #imm,@@rd
4460 * add.w #imm,rd band #imm,@@abs:8
4461 * add.l rs,rd bra pcrel:8
4462 * add.l #imm,rd * bra pcrel:16
4463 adds #imm,rd bt pcrel:8
4464 addx #imm,rd * bt pcrel:16
4465 addx rs,rd brn pcrel:8
4466 and.b #imm,rd * brn pcrel:16
4467 and.b rs,rd bf pcrel:8
4468 * and.w rs,rd * bf pcrel:16
4469 * and.w #imm,rd bhi pcrel:8
4470 * and.l #imm,rd * bhi pcrel:16
4471 * and.l rs,rd bls pcrel:8
4473 * bls pcrel:16 bld #imm,rd
4474 bcc pcrel:8 bld #imm,@@rd
4475 * bcc pcrel:16 bld #imm,@@abs:8
4476 bhs pcrel:8 bnot #imm,rd
4477 * bhs pcrel:16 bnot #imm,@@rd
4478 bcs pcrel:8 bnot #imm,@@abs:8
4479 * bcs pcrel:16 bnot rs,rd
4480 blo pcrel:8 bnot rs,@@rd
4481 * blo pcrel:16 bnot rs,@@abs:8
4482 bne pcrel:8 bor #imm,rd
4483 * bne pcrel:16 bor #imm,@@rd
4484 beq pcrel:8 bor #imm,@@abs:8
4485 * beq pcrel:16 bset #imm,rd
4486 bvc pcrel:8 bset #imm,@@rd
4487 * bvc pcrel:16 bset #imm,@@abs:8
4488 bvs pcrel:8 bset rs,rd
4489 * bvs pcrel:16 bset rs,@@rd
4490 bpl pcrel:8 bset rs,@@abs:8
4491 * bpl pcrel:16 bsr pcrel:8
4492 bmi pcrel:8 bsr pcrel:16
4493 * bmi pcrel:16 bst #imm,rd
4494 bge pcrel:8 bst #imm,@@rd
4495 * bge pcrel:16 bst #imm,@@abs:8
4496 blt pcrel:8 btst #imm,rd
4497 * blt pcrel:16 btst #imm,@@rd
4498 bgt pcrel:8 btst #imm,@@abs:8
4499 * bgt pcrel:16 btst rs,rd
4500 ble pcrel:8 btst rs,@@rd
4501 * ble pcrel:16 btst rs,@@abs:8
4502 bclr #imm,rd bxor #imm,rd
4503 bclr #imm,@@rd bxor #imm,@@rd
4504 bclr #imm,@@abs:8 bxor #imm,@@abs:8
4505 bclr rs,rd cmp.b #imm,rd
4506 bclr rs,@@rd cmp.b rs,rd
4507 bclr rs,@@abs:8 cmp.w rs,rd
4508 biand #imm,rd cmp.w rs,rd
4509 biand #imm,@@rd * cmp.w #imm,rd
4510 biand #imm,@@abs:8 * cmp.l #imm,rd
4511 bild #imm,rd * cmp.l rs,rd
4512 bild #imm,@@rd daa rs
4513 bild #imm,@@abs:8 das rs
4514 bior #imm,rd dec.b rs
4515 bior #imm,@@rd * dec.w #imm,rd
4516 bior #imm,@@abs:8 * dec.l #imm,rd
4517 bist #imm,rd divxu.b rs,rd
4518 bist #imm,@@rd * divxu.w rs,rd
4519 bist #imm,@@abs:8 * divxs.b rs,rd
4520 bixor #imm,rd * divxs.w rs,rd
4521 bixor #imm,@@rd eepmov
4522 bixor #imm,@@abs:8 * eepmovw
4524 * exts.w rd mov.w rs,@@abs:16
4525 * exts.l rd * mov.l #imm,rd
4526 * extu.w rd * mov.l rs,rd
4527 * extu.l rd * mov.l @@rs,rd
4528 inc rs * mov.l @@(disp:16,rs),rd
4529 * inc.w #imm,rd * mov.l @@(disp:24,rs),rd
4530 * inc.l #imm,rd * mov.l @@rs+,rd
4531 jmp @@rs * mov.l @@abs:16,rd
4532 jmp abs * mov.l @@abs:24,rd
4533 jmp @@@@abs:8 * mov.l rs,@@rd
4534 jsr @@rs * mov.l rs,@@(disp:16,rd)
4535 jsr abs * mov.l rs,@@(disp:24,rd)
4536 jsr @@@@abs:8 * mov.l rs,@@-rd
4537 ldc #imm,ccr * mov.l rs,@@abs:16
4538 ldc rs,ccr * mov.l rs,@@abs:24
4539 * ldc @@abs:16,ccr movfpe @@abs:16,rd
4540 * ldc @@abs:24,ccr movtpe rs,@@abs:16
4541 * ldc @@(disp:16,rs),ccr mulxu.b rs,rd
4542 * ldc @@(disp:24,rs),ccr * mulxu.w rs,rd
4543 * ldc @@rs+,ccr * mulxs.b rs,rd
4544 * ldc @@rs,ccr * mulxs.w rs,rd
4545 * mov.b @@(disp:24,rs),rd neg.b rs
4546 * mov.b rs,@@(disp:24,rd) * neg.w rs
4547 mov.b @@abs:16,rd * neg.l rs
4549 mov.b @@abs:8,rd not.b rs
4550 mov.b rs,@@abs:8 * not.w rs
4551 mov.b rs,rd * not.l rs
4552 mov.b #imm,rd or.b #imm,rd
4553 mov.b @@rs,rd or.b rs,rd
4554 mov.b @@(disp:16,rs),rd * or.w #imm,rd
4555 mov.b @@rs+,rd * or.w rs,rd
4556 mov.b @@abs:8,rd * or.l #imm,rd
4557 mov.b rs,@@rd * or.l rs,rd
4558 mov.b rs,@@(disp:16,rd) orc #imm,ccr
4559 mov.b rs,@@-rd pop.w rs
4560 mov.b rs,@@abs:8 * pop.l rs
4561 mov.w rs,@@rd push.w rs
4562 * mov.w @@(disp:24,rs),rd * push.l rs
4563 * mov.w rs,@@(disp:24,rd) rotl.b rs
4564 * mov.w @@abs:24,rd * rotl.w rs
4565 * mov.w rs,@@abs:24 * rotl.l rs
4566 mov.w rs,rd rotr.b rs
4567 mov.w #imm,rd * rotr.w rs
4568 mov.w @@rs,rd * rotr.l rs
4569 mov.w @@(disp:16,rs),rd rotxl.b rs
4570 mov.w @@rs+,rd * rotxl.w rs
4571 mov.w @@abs:16,rd * rotxl.l rs
4572 mov.w rs,@@(disp:16,rd) rotxr.b rs
4573 mov.w rs,@@-rd * rotxr.w rs
4575 * rotxr.l rs * stc ccr,@@(disp:24,rd)
4577 rte * stc ccr,@@abs:16
4578 rts * stc ccr,@@abs:24
4579 shal.b rs sub.b rs,rd
4580 * shal.w rs sub.w rs,rd
4581 * shal.l rs * sub.w #imm,rd
4582 shar.b rs * sub.l rs,rd
4583 * shar.w rs * sub.l #imm,rd
4584 * shar.l rs subs #imm,rd
4585 shll.b rs subx #imm,rd
4586 * shll.w rs subx rs,rd
4587 * shll.l rs * trapa #imm
4588 shlr.b rs xor #imm,rd
4589 * shlr.w rs xor rs,rd
4590 * shlr.l rs * xor.w #imm,rd
4592 stc ccr,rd * xor.l #imm,rd
4593 * stc ccr,@@rs * xor.l rs,rd
4594 * stc ccr,@@(disp:16,rd) xorc #imm,ccr
4597 @cindex size suffixes, H8/300
4598 @cindex H8/300 size suffixes
4599 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4600 @code{sub}) are defined with variants using the suffixes @samp{.b},
4601 @samp{.w}, and @samp{.l} to specify the size of a memory operand.
4602 @code{@value{AS}} supports these suffixes, but does not require them;
4603 since one of the operands is always a register, @code{@value{AS}} can
4604 deduce the correct size.
4606 For example, since @code{r0} refers to a 16-bit register,
4609 @exdent is equivalent to
4613 If you use the size suffixes, @code{@value{AS}} issues a warning when
4614 the suffix and the register size do not match.
4619 @node H8/500-Dependent
4620 @chapter H8/500 Dependent Features
4622 @cindex H8/500 support
4624 * H8/500 Options:: Options
4625 * H8/500 Syntax:: Syntax
4626 * H8/500 Floating Point:: Floating Point
4627 * H8/500 Directives:: H8/500 Machine Directives
4628 * H8/500 Opcodes:: Opcodes
4631 @node H8/500 Options
4634 @cindex H8/500 options (none)
4635 @cindex options, H8/500 (none)
4636 @code{@value{AS}} has no additional command-line options for the Hitachi
4643 * H8/500-Chars:: Special Characters
4644 * H8/500-Regs:: Register Names
4645 * H8/500-Addressing:: Addressing Modes
4649 @subsection Special Characters
4651 @cindex line comment character, H8/500
4652 @cindex H8/500 line comment character
4653 @samp{!} is the line comment character.
4655 @cindex line separator, H8/500
4656 @cindex statement separator, H8/500
4657 @cindex H8/500 line separator
4658 @samp{;} can be used instead of a newline to separate statements.
4660 @cindex symbol names, @samp{$} in
4661 @cindex @code{$} in symbol names
4662 Since @samp{$} has no special meaning, you may use it in symbol names.
4665 @subsection Register Names
4667 @cindex H8/500 registers
4668 @cindex registers, H8/500
4669 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
4670 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, and @samp{r7} to refer to
4671 the H8/500 registers.
4673 The H8/500 also has these control registers:
4695 condition code register
4698 All registers are 16 bits long. To represent 32 bit numbers, use two
4699 adjacent registers; for distant memory addresses, use one of the segment
4700 pointers (@code{cp} for the program counter; @code{dp} for
4701 @code{r0}--@code{r3}; @code{ep} for @code{r4} and @code{r5}; and
4702 @code{tp} for @code{r6} and @code{r7}.
4704 @node H8/500-Addressing
4705 @subsection Addressing Modes
4707 @cindex addressing modes, H8/500
4708 @cindex H8/500 addressing modes
4709 @value{AS} understands the following addressing modes for the H8/500:
4717 @item @@(d:8, R@var{n})
4718 Register indirect with 8 bit signed displacement
4720 @item @@(d:16, R@var{n})
4721 Register indirect with 16 bit signed displacement
4724 Register indirect with pre-decrement
4727 Register indirect with post-increment
4730 8 bit absolute address
4733 16 bit absolute address
4742 @node H8/500 Floating Point
4743 @section Floating Point
4745 @cindex floating point, H8/500 (@sc{ieee})
4746 @cindex H8/500 floating point (@sc{ieee})
4747 The H8/500 family uses @sc{ieee} floating-point numbers.
4749 @node H8/500 Directives
4750 @section H8/500 Machine Directives
4752 @cindex H8/500 machine directives (none)
4753 @cindex machine directives, H8/500 (none)
4754 @cindex @code{word} directive, H8/500
4755 @cindex @code{int} directive, H8/500
4756 @code{@value{AS}} has no machine-dependent directives for the H8/500.
4757 However, on this platform the @samp{.int} and @samp{.word} directives
4758 generate 16-bit numbers.
4760 @node H8/500 Opcodes
4763 @cindex H8/500 opcode summary
4764 @cindex opcode summary, H8/500
4765 @cindex mnemonics, H8/500
4766 @cindex instruction summary, H8/500
4767 For detailed information on the H8/500 machine instruction set, see
4768 @cite{H8/500 Series Programming Manual} (Hitachi M21T001).
4770 @code{@value{AS}} implements all the standard H8/500 opcodes. No additional
4771 pseudo-instructions are needed on this family.
4773 The following table summarizes H8/500 opcodes and their operands:
4775 @c Use @group if it ever works, instead of @page
4779 abs8 @r{8-bit absolute address}
4780 abs16 @r{16-bit absolute address}
4781 abs24 @r{24-bit absolute address}
4782 crb @r{@code{ccr}, @code{br}, @code{ep}, @code{dp}, @code{tp}, @code{dp}}
4783 disp8 @r{8-bit displacement}
4784 ea @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4785 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16},}
4786 @r{@code{#xx:8}, @code{#xx:16}}
4787 ea_mem @r{@code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4788 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4789 ea_noimm @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4790 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4792 imm4 @r{4-bit immediate data}
4793 imm8 @r{8-bit immediate data}
4794 imm16 @r{16-bit immediate data}
4795 pcrel8 @r{8-bit offset from program counter}
4796 pcrel16 @r{16-bit offset from program counter}
4797 qim @r{@code{-2}, @code{-1}, @code{1}, @code{2}}
4799 rs @r{a register distinct from rd}
4800 rlist @r{comma-separated list of registers in parentheses;}
4801 @r{register ranges @code{rd-rs} are allowed}
4802 sp @r{stack pointer (@code{r7})}
4803 sr @r{status register}
4804 sz @r{size; @samp{.b} or @samp{.w}. If omitted, default @samp{.w}}
4806 ldc[.b] ea,crb bcc[.w] pcrel16
4807 ldc[.w] ea,sr bcc[.b] pcrel8
4808 add[:q] sz qim,ea_noimm bhs[.w] pcrel16
4809 add[:g] sz ea,rd bhs[.b] pcrel8
4810 adds sz ea,rd bcs[.w] pcrel16
4811 addx sz ea,rd bcs[.b] pcrel8
4812 and sz ea,rd blo[.w] pcrel16
4813 andc[.b] imm8,crb blo[.b] pcrel8
4814 andc[.w] imm16,sr bne[.w] pcrel16
4816 bra[.w] pcrel16 beq[.w] pcrel16
4817 bra[.b] pcrel8 beq[.b] pcrel8
4818 bt[.w] pcrel16 bvc[.w] pcrel16
4819 bt[.b] pcrel8 bvc[.b] pcrel8
4820 brn[.w] pcrel16 bvs[.w] pcrel16
4821 brn[.b] pcrel8 bvs[.b] pcrel8
4822 bf[.w] pcrel16 bpl[.w] pcrel16
4823 bf[.b] pcrel8 bpl[.b] pcrel8
4824 bhi[.w] pcrel16 bmi[.w] pcrel16
4825 bhi[.b] pcrel8 bmi[.b] pcrel8
4826 bls[.w] pcrel16 bge[.w] pcrel16
4827 bls[.b] pcrel8 bge[.b] pcrel8
4829 blt[.w] pcrel16 mov[:g][.b] imm8,ea_mem
4830 blt[.b] pcrel8 mov[:g][.w] imm16,ea_mem
4831 bgt[.w] pcrel16 movfpe[.b] ea,rd
4832 bgt[.b] pcrel8 movtpe[.b] rs,ea_noimm
4833 ble[.w] pcrel16 mulxu sz ea,rd
4834 ble[.b] pcrel8 neg sz ea
4835 bclr sz imm4,ea_noimm nop
4836 bclr sz rs,ea_noimm not sz ea
4837 bnot sz imm4,ea_noimm or sz ea,rd
4838 bnot sz rs,ea_noimm orc[.b] imm8,crb
4839 bset sz imm4,ea_noimm orc[.w] imm16,sr
4840 bset sz rs,ea_noimm pjmp abs24
4841 bsr[.b] pcrel8 pjmp @@rd
4842 bsr[.w] pcrel16 pjsr abs24
4843 btst sz imm4,ea_noimm pjsr @@rd
4844 btst sz rs,ea_noimm prtd imm8
4845 clr sz ea prtd imm16
4846 cmp[:e][.b] imm8,rd prts
4847 cmp[:i][.w] imm16,rd rotl sz ea
4848 cmp[:g].b imm8,ea_noimm rotr sz ea
4849 cmp[:g][.w] imm16,ea_noimm rotxl sz ea
4850 Cmp[:g] sz ea,rd rotxr sz ea
4852 divxu sz ea,rd rtd imm16
4854 exts[.b] rd scb/f rs,pcrel8
4855 extu[.b] rd scb/ne rs,pcrel8
4856 jmp @@rd scb/eq rs,pcrel8
4857 jmp @@(imm8,rd) shal sz ea
4858 jmp @@(imm16,rd) shar sz ea
4859 jmp abs16 shll sz ea
4861 jsr @@(imm8,rd) sleep
4862 jsr @@(imm16,rd) stc[.b] crb,ea_noimm
4863 jsr abs16 stc[.w] sr,ea_noimm
4864 ldm @@sp+,(rlist) stm (rlist),@@-sp
4865 link fp,imm8 sub sz ea,rd
4866 link fp,imm16 subs sz ea,rd
4867 mov[:e][.b] imm8,rd subx sz ea,rd
4868 mov[:i][.w] imm16,rd swap[.b] rd
4869 mov[:l][.w] abs8,rd tas[.b] ea
4870 mov[:l].b abs8,rd trapa imm4
4871 mov[:s][.w] rs,abs8 trap/vs
4872 mov[:s].b rs,abs8 tst sz ea
4873 mov[:f][.w] @@(disp8,fp),rd unlk fp
4874 mov[:f][.w] rs,@@(disp8,fp) xch[.w] rs,rd
4875 mov[:f].b @@(disp8,fp),rd xor sz ea,rd
4876 mov[:f].b rs,@@(disp8,fp) xorc.b imm8,crb
4877 mov[:g] sz rs,ea_mem xorc.w imm16,sr
4885 @node HPPA-Dependent
4886 @chapter HPPA Dependent Features
4890 * HPPA Notes:: Notes
4891 * HPPA Options:: Options
4892 * HPPA Syntax:: Syntax
4893 * HPPA Floating Point:: Floating Point
4894 * HPPA Directives:: HPPA Machine Directives
4895 * HPPA Opcodes:: Opcodes
4900 As a back end for GNU CC @code{@value{AS}} has been throughly tested and should
4901 work extremely well. We have tested it only minimally on hand written assembly
4902 code and no one has tested it much on the assembly output from the HP
4905 The format of the debugging sections has changed since the original
4906 @code{@value{AS}} port (version 1.3X) was released; therefore,
4907 you must rebuild all HPPA objects and libraries with the new
4908 assembler so that you can debug the final executable.
4910 The HPPA @code{@value{AS}} port generates a small subset of the relocations
4911 available in the SOM and ELF object file formats. Additional relocation
4912 support will be added as it becomes necessary.
4916 @code{@value{AS}} has no machine-dependent command-line options for the HPPA.
4921 The assembler syntax closely follows the HPPA instruction set
4922 reference manual; assembler directives and general syntax closely follow the
4923 HPPA assembly language reference manual, with a few noteworthy differences.
4925 First, a colon may immediately follow a label definition. This is
4926 simply for compatibility with how most assembly language programmers
4929 Some obscure expression parsing problems may affect hand written code which
4930 uses the @code{spop} instructions, or code which makes significant
4931 use of the @code{!} line separator.
4933 @code{@value{AS}} is much less forgiving about missing arguments and other
4934 similar oversights than the HP assembler. @code{@value{AS}} notifies you
4935 of missing arguments as syntax errors; this is regarded as a feature, not a
4938 Finally, @code{@value{AS}} allows you to use an external symbol without
4939 explicitly importing the symbol. @emph{Warning:} in the future this will be
4940 an error for HPPA targets.
4942 Special characters for HPPA targets include:
4944 @samp{;} is the line comment character.
4946 @samp{!} can be used instead of a newline to separate statements.
4948 Since @samp{$} has no special meaning, you may use it in symbol names.
4950 @node HPPA Floating Point
4951 @section Floating Point
4952 @cindex floating point, HPPA (@sc{ieee})
4953 @cindex HPPA floating point (@sc{ieee})
4954 The HPPA family uses @sc{ieee} floating-point numbers.
4956 @node HPPA Directives
4957 @section HPPA Machine Directives
4958 For detailed information on the HPPA machine instruction set, see
4959 @cite{HP9000 Series 800 Assembly Language Reference Manual}
4962 @code{@value{AS}} does not support the following assembler directives
4963 found in the HP manual:
4974 @cindex @code{.PARAM} on HPPA
4975 @code{@value{AS}} supports one additional assembler directive for the
4976 HPPA: @code{.PARAM}. It conveys register argument locations for
4977 static functions. Its syntax closely follows the @code{.EXPORT} directive.
4981 For detailed information on the HPPA machine instruction set, see
4982 @cite{PA-RISC Architecture and Instruction Set Reference Manual}
4989 @chapter Hitachi SH Dependent Features
4993 * SH Options:: Options
4994 * SH Syntax:: Syntax
4995 * SH Floating Point:: Floating Point
4996 * SH Directives:: SH Machine Directives
4997 * SH Opcodes:: Opcodes
5003 @cindex SH options (none)
5004 @cindex options, SH (none)
5005 @code{@value{AS}} has no additional command-line options for the Hitachi
5012 * SH-Chars:: Special Characters
5013 * SH-Regs:: Register Names
5014 * SH-Addressing:: Addressing Modes
5018 @subsection Special Characters
5020 @cindex line comment character, SH
5021 @cindex SH line comment character
5022 @samp{!} is the line comment character.
5024 @cindex line separator, SH
5025 @cindex statement separator, SH
5026 @cindex SH line separator
5027 You can use @samp{;} instead of a newline to separate statements.
5029 @cindex symbol names, @samp{$} in
5030 @cindex @code{$} in symbol names
5031 Since @samp{$} has no special meaning, you may use it in symbol names.
5034 @subsection Register Names
5036 @cindex SH registers
5037 @cindex registers, SH
5038 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
5039 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, @samp{r7}, @samp{r8},
5040 @samp{r9}, @samp{r10}, @samp{r11}, @samp{r12}, @samp{r13}, @samp{r14},
5041 and @samp{r15} to refer to the SH registers.
5043 The SH also has these control registers:
5047 procedure register (holds return address)
5054 high and low multiply accumulator registers
5060 global base register
5063 vector base register (for interrupt vectors)
5067 @subsection Addressing Modes
5069 @cindex addressing modes, SH
5070 @cindex SH addressing modes
5071 @code{@value{AS}} understands the following addressing modes for the SH.
5072 @code{R@var{n}} in the following refers to any of the numbered
5073 registers, but @emph{not} the control registers.
5083 Register indirect with pre-decrement
5086 Register indirect with post-increment
5088 @item @@(@var{disp}, R@var{n})
5089 Register indirect with displacement
5091 @item @@(R0, R@var{n})
5094 @item @@(@var{disp}, GBR)
5101 @itemx @@(@var{disp}, PC)
5102 PC relative address (for branch or for addressing memory). The
5103 @code{@value{AS}} implementation allows you to use the simpler form
5104 @var{addr} anywhere a PC relative address is called for; the alternate
5105 form is supported for compatibility with other assemblers.
5111 @node SH Floating Point
5112 @section Floating Point
5114 @cindex floating point, SH (@sc{ieee})
5115 @cindex SH floating point (@sc{ieee})
5116 The SH family uses @sc{ieee} floating-point numbers.
5119 @section SH Machine Directives
5121 @cindex SH machine directives (none)
5122 @cindex machine directives, SH (none)
5123 @cindex @code{word} directive, SH
5124 @cindex @code{int} directive, SH
5125 @code{@value{AS}} has no machine-dependent directives for the SH.
5130 @cindex SH opcode summary
5131 @cindex opcode summary, SH
5132 @cindex mnemonics, SH
5133 @cindex instruction summary, SH
5134 For detailed information on the SH machine instruction set, see
5135 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
5137 @code{@value{AS}} implements all the standard SH opcodes. No additional
5138 pseudo-instructions are needed on this family. Note, however, that
5139 because @code{@value{AS}} supports a simpler form of PC-relative
5140 addressing, you may simply write (for example)
5147 where other assemblers might require an explicit displacement to
5148 @code{bar} from the program counter:
5151 mov.l @@(@var{disp}, PC)
5154 Here is a summary of SH opcodes:
5159 Rn @r{a numbered register}
5160 Rm @r{another numbered register}
5161 #imm @r{immediate data}
5162 disp @r{displacement}
5163 disp8 @r{8-bit displacement}
5164 disp12 @r{12-bit displacement}
5166 add #imm,Rn lds.l @@Rn+,PR
5167 add Rm,Rn mac.w @@Rm+,@@Rn+
5168 addc Rm,Rn mov #imm,Rn
5169 addv Rm,Rn mov Rm,Rn
5170 and #imm,R0 mov.b Rm,@@(R0,Rn)
5171 and Rm,Rn mov.b Rm,@@-Rn
5172 and.b #imm,@@(R0,GBR) mov.b Rm,@@Rn
5173 bf disp8 mov.b @@(disp,Rm),R0
5174 bra disp12 mov.b @@(disp,GBR),R0
5175 bsr disp12 mov.b @@(R0,Rm),Rn
5176 bt disp8 mov.b @@Rm+,Rn
5177 clrmac mov.b @@Rm,Rn
5178 clrt mov.b R0,@@(disp,Rm)
5179 cmp/eq #imm,R0 mov.b R0,@@(disp,GBR)
5180 cmp/eq Rm,Rn mov.l Rm,@@(disp,Rn)
5181 cmp/ge Rm,Rn mov.l Rm,@@(R0,Rn)
5182 cmp/gt Rm,Rn mov.l Rm,@@-Rn
5183 cmp/hi Rm,Rn mov.l Rm,@@Rn
5184 cmp/hs Rm,Rn mov.l @@(disp,Rn),Rm
5185 cmp/pl Rn mov.l @@(disp,GBR),R0
5186 cmp/pz Rn mov.l @@(disp,PC),Rn
5187 cmp/str Rm,Rn mov.l @@(R0,Rm),Rn
5188 div0s Rm,Rn mov.l @@Rm+,Rn
5190 div1 Rm,Rn mov.l R0,@@(disp,GBR)
5191 exts.b Rm,Rn mov.w Rm,@@(R0,Rn)
5192 exts.w Rm,Rn mov.w Rm,@@-Rn
5193 extu.b Rm,Rn mov.w Rm,@@Rn
5194 extu.w Rm,Rn mov.w @@(disp,Rm),R0
5195 jmp @@Rn mov.w @@(disp,GBR),R0
5196 jsr @@Rn mov.w @@(disp,PC),Rn
5197 ldc Rn,GBR mov.w @@(R0,Rm),Rn
5198 ldc Rn,SR mov.w @@Rm+,Rn
5199 ldc Rn,VBR mov.w @@Rm,Rn
5200 ldc.l @@Rn+,GBR mov.w R0,@@(disp,Rm)
5201 ldc.l @@Rn+,SR mov.w R0,@@(disp,GBR)
5202 ldc.l @@Rn+,VBR mova @@(disp,PC),R0
5204 lds Rn,MACL muls Rm,Rn
5205 lds Rn,PR mulu Rm,Rn
5206 lds.l @@Rn+,MACH neg Rm,Rn
5207 lds.l @@Rn+,MACL negc Rm,Rn
5210 not Rm,Rn stc.l GBR,@@-Rn
5211 or #imm,R0 stc.l SR,@@-Rn
5212 or Rm,Rn stc.l VBR,@@-Rn
5213 or.b #imm,@@(R0,GBR) sts MACH,Rn
5214 rotcl Rn sts MACL,Rn
5216 rotl Rn sts.l MACH,@@-Rn
5217 rotr Rn sts.l MACL,@@-Rn
5222 shar Rn swap.b Rm,Rn
5223 shll Rn swap.w Rm,Rn
5224 shll16 Rn tas.b @@Rn
5226 shll8 Rn tst #imm,R0
5228 shlr16 Rn tst.b #imm,@@(R0,GBR)
5229 shlr2 Rn xor #imm,R0
5231 sleep xor.b #imm,@@(R0,GBR)
5232 stc GBR,Rn xtrct Rm,Rn
5246 @node i960-Dependent
5247 @chapter Intel 80960 Dependent Features
5250 @node Machine Dependencies
5251 @chapter Intel 80960 Dependent Features
5254 @cindex i960 support
5256 * Options-i960:: i960 Command-line Options
5257 * Floating Point-i960:: Floating Point
5258 * Directives-i960:: i960 Machine Directives
5259 * Opcodes for i960:: i960 Opcodes
5262 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
5263 @c long as they're not turned on for other machines than 960.
5267 @section i960 Command-line Options
5269 @cindex i960 options
5270 @cindex options, i960
5273 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
5274 @cindex i960 architecture options
5275 @cindex architecture options, i960
5276 @cindex @code{-A} options, i960
5277 Select the 80960 architecture. Instructions or features not supported
5278 by the selected architecture cause fatal errors.
5280 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
5281 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
5283 If none of these options is specified, @code{@value{AS}} generates code for any
5284 instruction or feature that is supported by @emph{some} version of the
5285 960 (even if this means mixing architectures!). In principle,
5286 @code{@value{AS}} attempts to deduce the minimal sufficient processor
5287 type if none is specified; depending on the object code format, the
5288 processor type may be recorded in the object file. If it is critical
5289 that the @code{@value{AS}} output match a specific architecture, specify that
5290 architecture explicitly.
5293 @cindex @code{-b} option, i960
5294 @cindex branch recording, i960
5295 @cindex i960 branch recording
5296 Add code to collect information about conditional branches taken, for
5297 later optimization using branch prediction bits. (The conditional branch
5298 instructions have branch prediction bits in the CA, CB, and CC
5299 architectures.) If @var{BR} represents a conditional branch instruction,
5300 the following represents the code generated by the assembler when
5301 @samp{-b} is specified:
5304 call @var{increment routine}
5305 .word 0 # pre-counter
5307 call @var{increment routine}
5308 .word 0 # post-counter
5311 The counter following a branch records the number of times that branch
5312 was @emph{not} taken; the differenc between the two counters is the
5313 number of times the branch @emph{was} taken.
5315 @cindex @code{gbr960}, i960 postprocessor
5316 @cindex branch statistics table, i960
5317 A table of every such @code{Label} is also generated, so that the
5318 external postprocessor @code{gbr960} (supplied by Intel) can locate all
5319 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
5320 this is a local symbol to permit collecting statistics for many separate
5321 object files. The table is word aligned, and begins with a two-word
5322 header. The first word, initialized to 0, is used in maintaining linked
5323 lists of branch tables. The second word is a count of the number of
5324 entries in the table, which follow immediately: each is a word, pointing
5325 to one of the labels illustrated above.
5329 @c END TEXI2ROFF-KILL
5331 +------------+------------+------------+ ... +------------+
5333 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
5335 +------------+------------+------------+ ... +------------+
5337 __BRANCH_TABLE__ layout
5343 \line{\leftskip=0pt\hskip\tableindent
5344 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
5345 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
5346 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
5348 @c END TEXI2ROFF-KILL
5350 The first word of the header is used to locate multiple branch tables,
5351 since each object file may contain one. Normally the links are
5352 maintained with a call to an initialization routine, placed at the
5353 beginning of each function in the file. The GNU C compiler
5354 generates these calls automatically when you give it a @samp{-b} option.
5355 For further details, see the documentation of @samp{gbr960}.
5358 @cindex @code{-norelax} option, i960
5359 Normally, Compare-and-Branch instructions with targets that require
5360 displacements greater than 13 bits (or that have external targets) are
5361 replaced with the corresponding compare (or @samp{chkbit}) and branch
5362 instructions. You can use the @samp{-norelax} option to specify that
5363 @code{@value{AS}} should generate errors instead, if the target displacement
5364 is larger than 13 bits.
5366 This option does not affect the Compare-and-Jump instructions; the code
5367 emitted for them is @emph{always} adjusted when necessary (depending on
5368 displacement size), regardless of whether you use @samp{-norelax}.
5371 @node Floating Point-i960
5372 @section Floating Point
5374 @cindex floating point, i960 (@sc{ieee})
5375 @cindex i960 floating point (@sc{ieee})
5376 @code{@value{AS}} generates @sc{ieee} floating-point numbers for the directives
5377 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
5379 @node Directives-i960
5380 @section i960 Machine Directives
5382 @cindex machine directives, i960
5383 @cindex i960 machine directives
5386 @cindex @code{bss} directive, i960
5387 @item .bss @var{symbol}, @var{length}, @var{align}
5388 Reserve @var{length} bytes in the bss section for a local @var{symbol},
5389 aligned to the power of two specified by @var{align}. @var{length} and
5390 @var{align} must be positive absolute expressions. This directive
5391 differs from @samp{.lcomm} only in that it permits you to specify
5392 an alignment. @xref{Lcomm,,@code{.lcomm}}.
5396 @item .extended @var{flonums}
5397 @cindex @code{extended} directive, i960
5398 @code{.extended} expects zero or more flonums, separated by commas; for
5399 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
5400 floating-point number.
5402 @item .leafproc @var{call-lab}, @var{bal-lab}
5403 @cindex @code{leafproc} directive, i960
5404 You can use the @samp{.leafproc} directive in conjunction with the
5405 optimized @code{callj} instruction to enable faster calls of leaf
5406 procedures. If a procedure is known to call no other procedures, you
5407 may define an entry point that skips procedure prolog code (and that does
5408 not depend on system-supplied saved context), and declare it as the
5409 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
5410 entry point that goes through the normal prolog, you can specify that
5411 entry point as @var{call-lab}.
5413 A @samp{.leafproc} declaration is meant for use in conjunction with the
5414 optimized call instruction @samp{callj}; the directive records the data
5415 needed later to choose between converting the @samp{callj} into a
5416 @code{bal} or a @code{call}.
5418 @var{call-lab} is optional; if only one argument is present, or if the
5419 two arguments are identical, the single argument is assumed to be the
5420 @code{bal} entry point.
5422 @item .sysproc @var{name}, @var{index}
5423 @cindex @code{sysproc} directive, i960
5424 The @samp{.sysproc} directive defines a name for a system procedure.
5425 After you define it using @samp{.sysproc}, you can use @var{name} to
5426 refer to the system procedure identified by @var{index} when calling
5427 procedures with the optimized call instruction @samp{callj}.
5429 Both arguments are required; @var{index} must be between 0 and 31
5433 @node Opcodes for i960
5434 @section i960 Opcodes
5436 @cindex opcodes, i960
5437 @cindex i960 opcodes
5438 All Intel 960 machine instructions are supported;
5439 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
5440 selecting the instruction subset for a particular 960
5441 architecture.@refill
5443 Some opcodes are processed beyond simply emitting a single corresponding
5444 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
5445 instructions with target displacements larger than 13 bits.
5448 * callj-i960:: @code{callj}
5449 * Compare-and-branch-i960:: Compare-and-Branch
5453 @subsection @code{callj}
5455 @cindex @code{callj}, i960 pseudo-opcode
5456 @cindex i960 @code{callj} pseudo-opcode
5457 You can write @code{callj} to have the assembler or the linker determine
5458 the most appropriate form of subroutine call: @samp{call},
5459 @samp{bal}, or @samp{calls}. If the assembly source contains
5460 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
5461 defining the operand---then @code{@value{AS}} translates the
5462 @code{callj}; if not, it simply emits the @code{callj}, leaving it
5463 for the linker to resolve.
5465 @node Compare-and-branch-i960
5466 @subsection Compare-and-Branch
5468 @cindex i960 compare/branch instructions
5469 @cindex compare/branch instructions, i960
5470 The 960 architectures provide combined Compare-and-Branch instructions
5471 that permit you to store the branch target in the lower 13 bits of the
5472 instruction word itself. However, if you specify a branch target far
5473 enough away that its address won't fit in 13 bits, the assembler can
5474 either issue an error, or convert your Compare-and-Branch instruction
5475 into separate instructions to do the compare and the branch.
5477 @cindex compare and jump expansions, i960
5478 @cindex i960 compare and jump expansions
5479 Whether @code{@value{AS}} gives an error or expands the instruction depends
5480 on two choices you can make: whether you use the @samp{-norelax} option,
5481 and whether you use a ``Compare and Branch'' instruction or a ``Compare
5482 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
5483 expanded if necessary; the ``Branch'' instructions are expanded when
5484 necessary @emph{unless} you specify @code{-norelax}---in which case
5485 @code{@value{AS}} gives an error instead.
5487 These are the Compare-and-Branch instructions, their ``Jump'' variants,
5488 and the instruction pairs they may expand into:
5492 @c END TEXI2ROFF-KILL
5495 Branch Jump Expanded to
5496 ------ ------ ------------
5499 cmpibe cmpije cmpi; be
5500 cmpibg cmpijg cmpi; bg
5501 cmpibge cmpijge cmpi; bge
5502 cmpibl cmpijl cmpi; bl
5503 cmpible cmpijle cmpi; ble
5504 cmpibno cmpijno cmpi; bno
5505 cmpibne cmpijne cmpi; bne
5506 cmpibo cmpijo cmpi; bo
5507 cmpobe cmpoje cmpo; be
5508 cmpobg cmpojg cmpo; bg
5509 cmpobge cmpojge cmpo; bge
5510 cmpobl cmpojl cmpo; bl
5511 cmpoble cmpojle cmpo; ble
5512 cmpobne cmpojne cmpo; bne
5518 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
5519 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
5520 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
5521 bbc& & chkbit; bno\cr
5522 bbs& & chkbit; bo\cr
5523 cmpibe& cmpije& cmpi; be\cr
5524 cmpibg& cmpijg& cmpi; bg\cr
5525 cmpibge& cmpijge& cmpi; bge\cr
5526 cmpibl& cmpijl& cmpi; bl\cr
5527 cmpible& cmpijle& cmpi; ble\cr
5528 cmpibno& cmpijno& cmpi; bno\cr
5529 cmpibne& cmpijne& cmpi; bne\cr
5530 cmpibo& cmpijo& cmpi; bo\cr
5531 cmpobe& cmpoje& cmpo; be\cr
5532 cmpobg& cmpojg& cmpo; bg\cr
5533 cmpobge& cmpojge& cmpo; bge\cr
5534 cmpobl& cmpojl& cmpo; bl\cr
5535 cmpoble& cmpojle& cmpo; ble\cr
5536 cmpobne& cmpojne& cmpo; bne\cr}
5538 @c END TEXI2ROFF-KILL
5544 @node M68K-Dependent
5545 @chapter M680x0 Dependent Features
5548 @node Machine Dependencies
5549 @chapter M680x0 Dependent Features
5552 @cindex M680x0 support
5554 * M68K-Opts:: M680x0 Options
5555 * M68K-Syntax:: Syntax
5556 * M68K-Moto-Syntax:: Motorola Syntax
5557 * M68K-Float:: Floating Point
5558 * M68K-Directives:: 680x0 Machine Directives
5559 * M68K-opcodes:: Opcodes
5563 @section M680x0 Options
5565 @cindex options, M680x0
5566 @cindex M680x0 options
5567 The Motorola 680x0 version of @code{@value{AS}} has two machine dependent options.
5568 One shortens undefined references from 32 to 16 bits, while the
5569 other is used to tell @code{@value{AS}} what kind of machine it is
5572 @cindex @code{-l} option, M680x0
5573 You can use the @samp{-l} option to shorten the size of references to undefined
5574 symbols. If you do not use the @samp{-l} option, references to undefined
5575 symbols are wide enough for a full @code{long} (32 bits). (Since
5576 @code{@value{AS}} cannot know where these symbols end up, @code{@value{AS}} can
5577 only allocate space for the linker to fill in later. Since @code{@value{AS}}
5578 doesn't know how far away these symbols are, it allocates as much space as it
5579 can.) If you use this option, the references are only one word wide (16 bits).
5580 This may be useful if you want the object file to be as small as possible, and
5581 you know that the relevant symbols are always less than 17 bits away.
5583 @cindex @code{-m68000} and related options
5584 @cindex architecture options, M680x0
5585 @cindex M680x0 architecture options
5586 The 680x0 version of @code{@value{AS}} is most frequently used to assemble
5587 programs for the Motorola MC68020 microprocessor. Occasionally it is
5588 used to assemble programs for the mostly similar, but slightly different
5589 MC68000 or MC68010 microprocessors. You can give @code{@value{AS}} the options
5590 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
5591 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
5598 This syntax for the Motorola 680x0 was developed at @sc{mit}.
5600 @cindex M680x0 syntax
5601 @cindex syntax, M680x0
5602 @cindex M680x0 size modifiers
5603 @cindex size modifiers, M680x0
5604 The 680x0 version of @code{@value{AS}} uses syntax compatible with the Sun
5605 assembler. Intervening periods are ignored; for example, @samp{movl} is
5606 equivalent to @samp{move.l}.
5609 If @code{@value{AS}} is compiled with SUN_ASM_SYNTAX defined, it
5610 also allows Sun-style local labels of the form @samp{1$} through
5614 In the following table @dfn{apc} stands for any of the address
5615 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
5616 Program Counter (@samp{pc}), or the zero-address relative to the
5617 program counter (@samp{zpc}).
5619 @cindex M680x0 addressing modes
5620 @cindex addressing modes, M680x0
5621 The following addressing modes are understood:
5624 @samp{#@var{digits}}
5627 @samp{d0} through @samp{d7}
5629 @item Address Register
5630 @samp{a0} through @samp{a7}@*
5631 @samp{a7} is also known as @samp{sp}, i.e. the Stack Pointer. @code{a6}
5632 is also known as @samp{fp}, the Frame Pointer.
5634 @item Address Register Indirect
5635 @samp{a0@@} through @samp{a7@@}
5637 @item Address Register Postincrement
5638 @samp{a0@@+} through @samp{a7@@+}
5640 @item Address Register Predecrement
5641 @samp{a0@@-} through @samp{a7@@-}
5643 @item Indirect Plus Offset
5644 @samp{@var{apc}@@(@var{digits})}
5647 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
5649 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
5652 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
5654 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
5657 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5659 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5661 @item Memory Indirect
5662 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
5665 @samp{@var{symbol}}, or @samp{@var{digits}}
5667 @c pesch@cygnus.com: gnu, rich concur the following needs careful
5668 @c research before documenting.
5669 , or either of the above followed
5670 by @samp{:b}, @samp{:w}, or @samp{:l}.
5674 For some configurations, especially those where the compiler normally
5675 does not prepend an underscore to the names of user variables, the
5676 assembler requires a @samp{%} before any use of a register name. This
5677 is intended to let the assembler distinguish between user variables and
5678 registers named @samp{a0} through @samp{a7}, and so on. The @samp{%} is
5679 always accepted, but is only required for some configurations, notably
5682 @node M68K-Moto-Syntax
5683 @section Motorola Syntax
5685 @cindex Motorola syntax for the 680x0
5686 @cindex alternate syntax for the 680x0
5688 The standard Motorola syntax for this chip differs from the syntax
5689 already discussed (@pxref{M68K-Syntax,,Syntax}). @code{@value{AS}} can
5690 accept both kinds of syntax, even within a single instruction. The
5691 two kinds of syntax are fully compatible.
5693 @c FIXME! I can't figure out what this means. Surely the "always" is in some
5694 @c restricted context, for instance. It's not necessary for the preceding text
5695 @c to explain this, so just ignore it for now; re-enable someday when someone
5696 @c has time to explain it better.
5697 , because the Motorola syntax never uses
5698 the @samp{@@} character and the @sc{mit} syntax always does, except in
5699 cases where the syntaxes are identical.
5702 @cindex M680x0 syntax
5703 @cindex syntax, M680x0
5704 In particular, you may write or generate M68K assembler with the
5705 following conventions:
5707 (In the following table @dfn{apc} stands for any of the address
5708 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
5709 Program Counter (@samp{pc}), or the zero-address relative to the
5710 program counter (@samp{zpc}).)
5712 @cindex M680x0 addressing modes
5713 @cindex addressing modes, M680x0
5714 The following additional addressing modes are understood:
5716 @item Address Register Indirect
5717 @samp{a0} through @samp{a7}@*
5718 @samp{a7} is also known as @samp{sp}, i.e. the Stack Pointer. @code{a6}
5719 is also known as @samp{fp}, the Frame Pointer.
5721 @item Address Register Postincrement
5722 @samp{(a0)+} through @samp{(a7)+}
5724 @item Address Register Predecrement
5725 @samp{-(a0)} through @samp{-(a7)}
5727 @item Indirect Plus Offset
5728 @samp{@var{digits}(@var{apc})}
5731 @samp{@var{digits}(@var{apc},(@var{register}.@var{size}*@var{scale})}@*
5732 or @samp{(@var{apc},@var{register}.@var{size}*@var{scale})}@*
5733 In either case, @var{size} and @var{scale} are optional
5734 (@var{scale} defaults to @samp{1}, @var{size} defaults to @samp{l}).
5735 @var{scale} can be @samp{1}, @samp{2}, @samp{4}, or @samp{8}.
5736 @var{size} can be @samp{w} or @samp{l}. @var{scale} is only supported
5737 on the 68020 and greater.
5741 @section Floating Point
5743 @cindex floating point, M680x0
5744 @cindex M680x0 floating point
5745 @c FIXME is this "not too well tested" crud STILL true?
5746 The floating point code is not too well tested, and may have
5749 Packed decimal (P) format floating literals are not supported.
5750 Feel free to add the code!
5752 The floating point formats generated by directives are these.
5756 @cindex @code{float} directive, M680x0
5757 @code{Single} precision floating point constants.
5760 @cindex @code{double} directive, M680x0
5761 @code{Double} precision floating point constants.
5764 There is no directive to produce regions of memory holding
5765 extended precision numbers, however they can be used as
5766 immediate operands to floating-point instructions. Adding a
5767 directive to create extended precision numbers would not be
5768 hard, but it has not yet seemed necessary.
5770 @node M68K-Directives
5771 @section 680x0 Machine Directives
5773 @cindex M680x0 directives
5774 @cindex directives, M680x0
5775 In order to be compatible with the Sun assembler the 680x0 assembler
5776 understands the following directives.
5780 @cindex @code{data1} directive, M680x0
5781 This directive is identical to a @code{.data 1} directive.
5784 @cindex @code{data2} directive, M680x0
5785 This directive is identical to a @code{.data 2} directive.
5788 @cindex @code{even} directive, M680x0
5789 This directive is identical to a @code{.align 1} directive.
5790 @c Is this true? does it work???
5793 @cindex @code{skip} directive, M680x0
5794 This directive is identical to a @code{.space} directive.
5800 @cindex M680x0 opcodes
5801 @cindex opcodes, M680x0
5802 @cindex instruction set, M680x0
5803 @c pesch@cygnus.com: I don't see any point in the following
5804 @c paragraph. Bugs are bugs; how does saying this
5807 Danger: Several bugs have been found in the opcode table (and
5808 fixed). More bugs may exist. Be careful when using obscure
5813 * M68K-Branch:: Branch Improvement
5814 * M68K-Chars:: Special Characters
5818 @subsection Branch Improvement
5820 @cindex pseudo-opcodes, M680x0
5821 @cindex M680x0 pseudo-opcodes
5822 @cindex branch improvement, M680x0
5823 @cindex M680x0 branch improvement
5824 Certain pseudo opcodes are permitted for branch instructions.
5825 They expand to the shortest branch instruction that reach the
5826 target. Generally these mnemonics are made by substituting @samp{j} for
5827 @samp{b} at the start of a Motorola mnemonic.
5829 The following table summarizes the pseudo-operations. A @code{*} flags
5830 cases that are more fully described after the table:
5834 +-------------------------------------------------
5836 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
5837 +-------------------------------------------------
5838 jbsr |bsrs bsr bsrl jsr jsr
5839 jra |bras bra bral jmp jmp
5840 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
5841 * dbXX |dbXX dbXX dbXX; bra; jmpl
5842 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
5845 NX: negative of condition XX
5848 @center @code{*}---see full description below
5853 These are the simplest jump pseudo-operations; they always map to one
5854 particular machine instruction, depending on the displacement to the
5858 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
5859 where @var{XX} is a conditional branch or condition-code test. The full
5860 list of pseudo-ops in this family is:
5862 jhi jls jcc jcs jne jeq jvc
5863 jvs jpl jmi jge jlt jgt jle
5866 For the cases of non-PC relative displacements and long displacements on
5867 the 68000 or 68010, @code{@value{AS}} issues a longer code fragment in terms of
5868 @var{NX}, the opposite condition to @var{XX}. For example, for the
5869 non-PC relative case:
5881 The full family of pseudo-operations covered here is
5883 dbhi dbls dbcc dbcs dbne dbeq dbvc
5884 dbvs dbpl dbmi dbge dblt dbgt dble
5888 Other than for word and byte displacements, when the source reads
5889 @samp{db@var{XX} foo}, @code{@value{AS}} emits
5898 This family includes
5900 fjne fjeq fjge fjlt fjgt fjle fjf
5901 fjt fjgl fjgle fjnge fjngl fjngle fjngt
5902 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
5903 fjor fjseq fjsf fjsne fjst fjueq fjuge
5904 fjugt fjule fjult fjun
5907 For branch targets that are not PC relative, @code{@value{AS}} emits
5913 when it encounters @samp{fj@var{XX} foo}.
5918 @subsection Special Characters
5920 @cindex special characters, M680x0
5921 @cindex M680x0 immediate character
5922 @cindex immediate character, M680x0
5923 @cindex M680x0 line comment character
5924 @cindex line comment character, M680x0
5925 @cindex comments, M680x0
5926 The immediate character is @samp{#} for Sun compatibility. The
5927 line-comment character is @samp{|}. If a @samp{#} appears at the
5928 beginning of a line, it is treated as a comment unless it looks like
5929 @samp{# line file}, in which case it is treated normally.
5933 @c FIXME! Stop ignoring when filled in.
5938 The 32x32 version of @code{@value{AS}} accepts a @samp{-m32032} option to
5939 specify thiat it is compiling for a 32032 processor, or a
5940 @samp{-m32532} to specify that it is compiling for a 32532 option.
5941 The default (if neither is specified) is chosen when the assembler
5945 I don't know anything about the 32x32 syntax assembled by
5946 @code{@value{AS}}. Someone who undersands the processor (I've never seen
5947 one) and the possible syntaxes should write this section.
5949 @section Floating Point
5950 The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{AS}}
5951 only creates single or double precision values. I don't know if the
5952 32x32 understands extended precision numbers.
5954 @section 32x32 Machine Directives
5955 The 32x32 has no machine dependent directives.
5961 @node Sparc-Dependent
5962 @chapter SPARC Dependent Features
5965 @node Machine Dependencies
5966 @chapter SPARC Dependent Features
5969 @cindex SPARC support
5971 * Sparc-Opts:: Options
5972 * Sparc-Float:: Floating Point
5973 * Sparc-Directives:: Sparc Machine Directives
5979 @cindex options for SPARC
5980 @cindex SPARC options
5981 @cindex architectures, SPARC
5982 @cindex SPARC architectures
5983 The SPARC chip family includes several successive levels (or other
5984 variants) of chip, using the same core instruction set, but including
5985 a few additional instructions at each level.
5987 By default, @code{@value{AS}} assumes the core instruction set (SPARC
5988 v6), but ``bumps'' the architecture level as needed: it switches to
5989 successively higher architectures as it encounters instructions that
5990 only exist in the higher levels.
5993 @item -Av6 | -Av7 | -Av8 | -Asparclite
5998 Use one of the @samp{-A} options to select one of the SPARC
5999 architectures explicitly. If you select an architecture explicitly,
6000 @code{@value{AS}} reports a fatal error if it encounters an instruction
6001 or feature requiring a higher level.
6004 Permit the assembler to ``bump'' the architecture level as required, but
6005 warn whenever it is necessary to switch to another level.
6009 @c FIXME: (sparc) Fill in "syntax" section!
6010 @c subsection syntax
6011 I don't know anything about Sparc syntax. Someone who does
6012 will have to write this section.
6016 @section Floating Point
6018 @cindex floating point, SPARC (@sc{ieee})
6019 @cindex SPARC floating point (@sc{ieee})
6020 The Sparc uses @sc{ieee} floating-point numbers.
6022 @node Sparc-Directives
6023 @section Sparc Machine Directives
6025 @cindex SPARC machine directives
6026 @cindex machine directives, SPARC
6027 The Sparc version of @code{@value{AS}} supports the following additional
6032 @cindex @code{common} directive, SPARC
6033 This must be followed by a symbol name, a positive number, and
6034 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
6035 syntax is different.
6038 @cindex @code{half} directive, SPARC
6039 This is functionally identical to @code{.short}.
6042 @cindex @code{proc} directive, SPARC
6043 This directive is ignored. Any text following it on the same
6044 line is also ignored.
6047 @cindex @code{reserve} directive, SPARC
6048 This must be followed by a symbol name, a positive number, and
6049 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
6050 syntax is different.
6053 @cindex @code{seg} directive, SPARC
6054 This must be followed by @code{"text"}, @code{"data"}, or
6055 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
6059 @cindex @code{skip} directive, SPARC
6060 This is functionally identical to the @code{.space} directive.
6063 @cindex @code{word} directive, SPARC
6064 On the Sparc, the .word directive produces 32 bit values,
6065 instead of the 16 bit values it produces on many other machines.
6072 @node i386-Dependent
6073 @chapter 80386 Dependent Features
6076 @node Machine Dependencies
6077 @chapter 80386 Dependent Features
6080 @cindex i386 support
6081 @cindex i80306 support
6083 * i386-Options:: Options
6084 * i386-Syntax:: AT&T Syntax versus Intel Syntax
6085 * i386-Opcodes:: Opcode Naming
6086 * i386-Regs:: Register Naming
6087 * i386-prefixes:: Opcode Prefixes
6088 * i386-Memory:: Memory References
6089 * i386-jumps:: Handling of Jump Instructions
6090 * i386-Float:: Floating Point
6091 * i386-Notes:: Notes
6097 @cindex options for i386 (none)
6098 @cindex i386 options (none)
6099 The 80386 has no machine dependent options.
6102 @section AT&T Syntax versus Intel Syntax
6104 @cindex i386 syntax compatibility
6105 @cindex syntax compatibility, i386
6106 In order to maintain compatibility with the output of @code{@value{GCC}},
6107 @code{@value{AS}} supports AT&T System V/386 assembler syntax. This is quite
6108 different from Intel syntax. We mention these differences because
6109 almost all 80386 documents used only Intel syntax. Notable differences
6110 between the two syntaxes are:
6114 @cindex immediate operands, i386
6115 @cindex i386 immediate operands
6116 @cindex register operands, i386
6117 @cindex i386 register operands
6118 @cindex jump/call operands, i386
6119 @cindex i386 jump/call operands
6120 @cindex operand delimiters, i386
6121 AT&T immediate operands are preceded by @samp{$}; Intel immediate
6122 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
6123 AT&T register operands are preceded by @samp{%}; Intel register operands
6124 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
6125 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
6128 @cindex i386 source, destination operands
6129 @cindex source, destination operands; i386
6130 AT&T and Intel syntax use the opposite order for source and destination
6131 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
6132 @samp{source, dest} convention is maintained for compatibility with
6133 previous Unix assemblers.
6136 @cindex opcode suffixes, i386
6137 @cindex sizes operands, i386
6138 @cindex i386 size suffixes
6139 In AT&T syntax the size of memory operands is determined from the last
6140 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
6141 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
6142 memory references. Intel syntax accomplishes this by prefixes memory
6143 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
6144 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
6145 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
6148 @cindex return instructions, i386
6149 @cindex i386 jump, call, return
6150 Immediate form long jumps and calls are
6151 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
6153 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
6155 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
6156 @samp{ret far @var{stack-adjust}}.
6159 @cindex sections, i386
6160 @cindex i386 sections
6161 The AT&T assembler does not provide support for multiple section
6162 programs. Unix style systems expect all programs to be single sections.
6166 @section Opcode Naming
6168 @cindex i386 opcode naming
6169 @cindex opcode naming, i386
6170 Opcode names are suffixed with one character modifiers which specify the
6171 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
6172 byte, word, and long operands. If no suffix is specified by an
6173 instruction and it contains no memory operands then @code{@value{AS}} tries to
6174 fill in the missing suffix based on the destination register operand
6175 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
6176 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
6177 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
6178 assembler which assumes that a missing opcode suffix implies long
6179 operand size. (This incompatibility does not affect compiler output
6180 since compilers always explicitly specify the opcode suffix.)
6182 Almost all opcodes have the same names in AT&T and Intel format. There
6183 are a few exceptions. The sign extend and zero extend instructions need
6184 two sizes to specify them. They need a size to sign/zero extend
6185 @emph{from} and a size to zero extend @emph{to}. This is accomplished
6186 by using two opcode suffixes in AT&T syntax. Base names for sign extend
6187 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
6188 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
6189 suffixes are tacked on to this base name, the @emph{from} suffix before
6190 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
6191 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
6192 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
6193 and @samp{wl} (from word to long).
6195 @cindex conversion instructions, i386
6196 @cindex i386 conversion instructions
6197 The Intel-syntax conversion instructions
6201 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
6204 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
6207 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
6210 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
6214 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
6215 AT&T naming. @code{@value{AS}} accepts either naming for these instructions.
6217 @cindex jump instructions, i386
6218 @cindex call instructions, i386
6219 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
6220 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
6224 @section Register Naming
6226 @cindex i386 registers
6227 @cindex registers, i386
6228 Register operands are always prefixes with @samp{%}. The 80386 registers
6233 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
6234 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
6235 frame pointer), and @samp{%esp} (the stack pointer).
6238 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
6239 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
6242 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
6243 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
6244 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
6245 @samp{%cx}, and @samp{%dx})
6248 the 6 section registers @samp{%cs} (code section), @samp{%ds}
6249 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
6253 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
6257 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
6258 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
6261 the 2 test registers @samp{%tr6} and @samp{%tr7}.
6264 the 8 floating point register stack @samp{%st} or equivalently
6265 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
6266 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
6270 @section Opcode Prefixes
6272 @cindex i386 opcode prefixes
6273 @cindex opcode prefixes, i386
6274 @cindex prefixes, i386
6275 Opcode prefixes are used to modify the following opcode. They are used
6276 to repeat string instructions, to provide section overrides, to perform
6277 bus lock operations, and to give operand and address size (16-bit
6278 operands are specified in an instruction by prefixing what would
6279 normally be 32-bit operands with a ``operand size'' opcode prefix).
6280 Opcode prefixes are usually given as single-line instructions with no
6281 operands, and must directly precede the instruction they act upon. For
6282 example, the @samp{scas} (scan string) instruction is repeated with:
6288 Here is a list of opcode prefixes:
6292 @cindex section override prefixes, i386
6293 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
6294 @samp{fs}, @samp{gs}. These are automatically added by specifying
6295 using the @var{section}:@var{memory-operand} form for memory references.
6298 @cindex size prefixes, i386
6299 Operand/Address size prefixes @samp{data16} and @samp{addr16}
6300 change 32-bit operands/addresses into 16-bit operands/addresses. Note
6301 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
6302 are not supported (yet).
6305 @cindex bus lock prefixes, i386
6306 @cindex inhibiting interrupts, i386
6307 The bus lock prefix @samp{lock} inhibits interrupts during
6308 execution of the instruction it precedes. (This is only valid with
6309 certain instructions; see a 80386 manual for details).
6312 @cindex coprocessor wait, i386
6313 The wait for coprocessor prefix @samp{wait} waits for the
6314 coprocessor to complete the current instruction. This should never be
6315 needed for the 80386/80387 combination.
6318 @cindex repeat prefixes, i386
6319 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
6320 to string instructions to make them repeat @samp{%ecx} times.
6324 @section Memory References
6326 @cindex i386 memory references
6327 @cindex memory references, i386
6328 An Intel syntax indirect memory reference of the form
6331 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
6335 is translated into the AT&T syntax
6338 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
6342 where @var{base} and @var{index} are the optional 32-bit base and
6343 index registers, @var{disp} is the optional displacement, and
6344 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
6345 to calculate the address of the operand. If no @var{scale} is
6346 specified, @var{scale} is taken to be 1. @var{section} specifies the
6347 optional section register for the memory operand, and may override the
6348 default section register (see a 80386 manual for section register
6349 defaults). Note that section overrides in AT&T syntax @emph{must} have
6350 be preceded by a @samp{%}. If you specify a section override which
6351 coincides with the default section register, @code{@value{AS}} does @emph{not}
6352 output any section register override prefixes to assemble the given
6353 instruction. Thus, section overrides can be specified to emphasize which
6354 section register is used for a given memory operand.
6356 Here are some examples of Intel and AT&T style memory references:
6359 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
6360 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
6361 missing, and the default section is used (@samp{%ss} for addressing with
6362 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
6364 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
6365 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
6366 @samp{foo}. All other fields are missing. The section register here
6367 defaults to @samp{%ds}.
6369 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
6370 This uses the value pointed to by @samp{foo} as a memory operand.
6371 Note that @var{base} and @var{index} are both missing, but there is only
6372 @emph{one} @samp{,}. This is a syntactic exception.
6374 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
6375 This selects the contents of the variable @samp{foo} with section
6376 register @var{section} being @samp{%gs}.
6379 Absolute (as opposed to PC relative) call and jump operands must be
6380 prefixed with @samp{*}. If no @samp{*} is specified, @code{@value{AS}}
6381 always chooses PC relative addressing for jump/call labels.
6383 Any instruction that has a memory operand @emph{must} specify its size (byte,
6384 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
6388 @section Handling of Jump Instructions
6390 @cindex jump optimization, i386
6391 @cindex i386 jump optimization
6392 Jump instructions are always optimized to use the smallest possible
6393 displacements. This is accomplished by using byte (8-bit) displacement
6394 jumps whenever the target is sufficiently close. If a byte displacement
6395 is insufficient a long (32-bit) displacement is used. We do not support
6396 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
6397 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
6398 @samp{%eip} to 16 bits after the word displacement is added.
6400 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
6401 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in byte
6402 displacements, so that if you use these instructions (@code{@value{GCC}} does
6403 not use them) you may get an error message (and incorrect code). The AT&T
6404 80386 assembler tries to get around this problem by expanding @samp{jcxz foo}
6415 @section Floating Point
6417 @cindex i386 floating point
6418 @cindex floating point, i386
6419 All 80387 floating point types except packed BCD are supported.
6420 (BCD support may be added without much difficulty). These data
6421 types are 16-, 32-, and 64- bit integers, and single (32-bit),
6422 double (64-bit), and extended (80-bit) precision floating point.
6423 Each supported type has an opcode suffix and a constructor
6424 associated with it. Opcode suffixes specify operand's data
6425 types. Constructors build these data types into memory.
6429 @cindex @code{float} directive, i386
6430 @cindex @code{single} directive, i386
6431 @cindex @code{double} directive, i386
6432 @cindex @code{tfloat} directive, i386
6433 Floating point constructors are @samp{.float} or @samp{.single},
6434 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
6435 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
6436 @samp{t} stands for temporary real, and that the 80387 only supports
6437 this format via the @samp{fldt} (load temporary real to stack top) and
6438 @samp{fstpt} (store temporary real and pop stack) instructions.
6441 @cindex @code{word} directive, i386
6442 @cindex @code{long} directive, i386
6443 @cindex @code{int} directive, i386
6444 @cindex @code{quad} directive, i386
6445 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
6446 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
6447 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
6448 (quad). As with the temporary real format the 64-bit @samp{q} format is
6449 only present in the @samp{fildq} (load quad integer to stack top) and
6450 @samp{fistpq} (store quad integer and pop stack) instructions.
6453 Register to register operations do not require opcode suffixes,
6454 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
6456 @cindex i386 @code{fwait} instruction
6457 @cindex @code{fwait instruction}, i386
6458 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
6459 instructions are almost never needed (this is not the case for the
6460 80286/80287 and 8086/8087 combinations). Therefore, @code{@value{AS}} suppresses
6461 the @samp{fwait} instruction whenever it is implicitly selected by one
6462 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
6463 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
6464 instructions are made equivalent to @samp{f@dots{}} instructions. If
6465 @samp{fwait} is desired it must be explicitly coded.
6470 @cindex i386 @code{mul}, @code{imul} instructions
6471 @cindex @code{mul} instruction, i386
6472 @cindex @code{imul} instruction, i386
6473 There is some trickery concerning the @samp{mul} and @samp{imul}
6474 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
6475 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
6476 for @samp{imul}) can be output only in the one operand form. Thus,
6477 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
6478 the expanding multiply would clobber the @samp{%edx} register, and this
6479 would confuse @code{@value{GCC}} output. Use @samp{imul %ebx} to get the
6480 64-bit product in @samp{%edx:%eax}.
6482 We have added a two operand form of @samp{imul} when the first operand
6483 is an immediate mode expression and the second operand is a register.
6484 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
6485 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
6492 @node Z8000-Dependent
6493 @chapter Z8000 Dependent Features
6496 @node Machine Dependencies
6497 @chapter Z8000 Dependent Features
6500 @cindex Z8000 support
6501 The Z8000 @value{AS} supports both members of the Z8000 family: the
6502 unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with
6505 When the assembler is in unsegmented mode (specified with the
6506 @code{unsegm} directive), an address takes up one word (16 bit)
6507 sized register. When the assembler is in segmented mode (specified with
6508 the @code{segm} directive), a 24-bit address takes up a long (32 bit)
6509 register. @xref{Z8000 Directives,,Assembler Directives for the Z8000},
6510 for a list of other Z8000 specific assembler directives.
6513 * Z8000 Options:: No special command-line options for Z8000
6514 * Z8000 Syntax:: Assembler syntax for the Z8000
6515 * Z8000 Directives:: Special directives for the Z8000
6516 * Z8000 Opcodes:: Opcodes
6522 @cindex Z8000 options
6523 @cindex options, Z8000
6524 @code{@value{AS}} has no additional command-line options for the Zilog
6530 * Z8000-Chars:: Special Characters
6531 * Z8000-Regs:: Register Names
6532 * Z8000-Addressing:: Addressing Modes
6536 @subsection Special Characters
6538 @cindex line comment character, Z8000
6539 @cindex Z8000 line comment character
6540 @samp{!} is the line comment character.
6542 @cindex line separator, Z8000
6543 @cindex statement separator, Z8000
6544 @cindex Z8000 line separator
6545 You can use @samp{;} instead of a newline to separate statements.
6548 @subsection Register Names
6550 @cindex Z8000 registers
6551 @cindex registers, Z8000
6552 The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer
6553 to different sized groups of registers by register number, with the
6554 prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and
6555 @samp{rq} for 64 bit registers. You can also refer to the contents of
6556 the first eight (of the sixteen 16 bit registers) by bytes. They are
6557 named @samp{r@var{n}h} and @samp{r@var{n}l}.
6560 @exdent @emph{byte registers}
6561 r0l r0h r1h r1l r2h r2l r3h r3l
6562 r4h r4l r5h r5l r6h r6l r7h r7l
6564 @exdent @emph{word registers}
6565 r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15
6567 @exdent @emph{long word registers}
6568 rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14
6570 @exdent @emph{quad word registers}
6574 @node Z8000-Addressing
6575 @subsection Addressing Modes
6577 @cindex addressing modes, Z8000
6578 @cindex Z800 addressing modes
6579 @value{AS} understands the following addressing modes for the Z8000:
6589 Direct: the 16 bit or 24 bit address (depending on whether the assembler
6590 is in segmented or unsegmented mode) of the operand is in the instruction.
6592 @item address(r@var{n})
6593 Indexed: the 16 or 24 bit address is added to the 16 bit register to produce
6594 the final address in memory of the operand.
6596 @item r@var{n}(#@var{imm})
6597 Base Address: the 16 or 24 bit register is added to the 16 bit sign
6598 extended immediate displacement to produce the final address in memory
6601 @item r@var{n}(r@var{m})
6602 Base Index: the 16 or 24 bit register r@var{n} is added to the sign
6603 extended 16 bit index register r@var{m} to produce the final address in
6604 memory of the operand.
6607 Immediate data @var{xx}.
6610 @node Z8000 Directives
6611 @section Assembler Directives for the Z8000
6613 @cindex Z8000 directives
6614 @cindex directives, Z8000
6615 The Z8000 port of @value{AS} includes these additional assembler directives,
6616 for compatibility with other Z8000 assemblers. As shown, these do not
6617 begin with @samp{.} (unlike the ordinary @value{AS} directives).
6622 Generates code for the segmented Z8001.
6626 Generates code for the unsegmented Z8002.
6630 Synonym for @code{.file}
6634 Synonum for @code{.global}
6638 Synonym for @code{.word}
6642 Synonym for @code{.long}
6646 Synonym for @code{.byte}
6650 Assemble a string. @code{sval} expects one string literal, delimited by
6651 single quotes. It assembles each byte of the string into consecutive
6652 addresses. You can use the escape sequence @samp{%@var{xx}} (where
6653 @var{xx} represents a two-digit hexadecimal number) to represent the
6654 character whose @sc{ascii} value is @var{xx}. Use this feature to
6655 describe single quote and other characters that may not appear in string
6656 literals as themselves. For example, the C statement @w{@samp{char *a =
6657 "he said \"it's 50% off\"";}} is represented in Z8000 assembly language
6658 (shown with the assembler output in hex at the left) as
6662 @let@nonarrowing=@comment
6665 68652073 sval 'he said %22it%27s 50%25 off%22%00'
6678 synonym for @code{.section}
6682 synonym for @code{.space}
6686 synonym for @code{.align 1}
6692 @cindex Z8000 opcode summary
6693 @cindex opcode summary, Z8000
6694 @cindex mnemonics, Z8000
6695 @cindex instruction summary, Z8000
6696 For detailed information on the Z8000 machine instruction set, see
6697 @cite{Z8000 Technical Manual}.
6699 The following table summarizes the opcodes and their arguments:
6702 @let@nonarrowing=@comment
6706 rs @r{16 bit source register}
6707 rd @r{16 bit destination register}
6708 rbs @r{8 bit source register}
6709 rbd @r{8 bit destination register}
6710 rrs @r{32 bit source register}
6711 rrd @r{32 bit destination register}
6712 rqs @r{64 bit source register}
6713 rqd @r{64 bit destination register}
6714 addr @r{16/24 bit address}
6715 imm @r{immediate data}
6717 adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc
6718 adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc
6719 add rd,@@rs clrb rbd dab rbd
6720 add rd,addr com @@rd dbjnz rbd,disp7
6721 add rd,addr(rs) com addr dec @@rd,imm4m1
6722 add rd,imm16 com addr(rd) dec addr(rd),imm4m1
6723 add rd,rs com rd dec addr,imm4m1
6724 addb rbd,@@rs comb @@rd dec rd,imm4m1
6725 addb rbd,addr comb addr decb @@rd,imm4m1
6726 addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1
6727 addb rbd,imm8 comb rbd decb addr,imm4m1
6728 addb rbd,rbs comflg flags decb rbd,imm4m1
6729 addl rrd,@@rs cp @@rd,imm16 di i2
6730 addl rrd,addr cp addr(rd),imm16 div rrd,@@rs
6731 addl rrd,addr(rs) cp addr,imm16 div rrd,addr
6732 addl rrd,imm32 cp rd,@@rs div rrd,addr(rs)
6733 addl rrd,rrs cp rd,addr div rrd,imm16
6734 and rd,@@rs cp rd,addr(rs) div rrd,rs
6735 and rd,addr cp rd,imm16 divl rqd,@@rs
6736 and rd,addr(rs) cp rd,rs divl rqd,addr
6737 and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs)
6738 and rd,rs cpb addr(rd),imm8 divl rqd,imm32
6739 andb rbd,@@rs cpb addr,imm8 divl rqd,rrs
6740 andb rbd,addr cpb rbd,@@rs djnz rd,disp7
6741 andb rbd,addr(rs) cpb rbd,addr ei i2
6742 andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs
6743 andb rbd,rbs cpb rbd,imm8 ex rd,addr
6744 bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs)
6745 bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs
6746 bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs
6747 bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr
6748 bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs)
6749 bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs
6750 bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8
6751 bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8
6752 bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8
6753 bitb rbd,rs cpl rrd,@@rs ext8f imm8
6754 bpt cpl rrd,addr exts rrd
6755 call @@rd cpl rrd,addr(rs) extsb rd
6756 call addr cpl rrd,imm32 extsl rqd
6757 call addr(rd) cpl rrd,rrs halt
6758 calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs
6759 clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16
6760 clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs
6761 clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16
6762 clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1
6763 clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1
6764 inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs)
6765 inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16
6766 incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs
6767 incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs
6768 incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr
6769 incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs)
6770 ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32
6771 indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs
6772 inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd
6773 inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr
6774 iret ldib @@rd,@@rs,rr neg addr(rd)
6775 jp cc,@@rd ldir @@rd,@@rs,rr neg rd
6776 jp cc,addr ldirb @@rd,@@rs,rr negb @@rd
6777 jp cc,addr(rd) ldk rd,imm4 negb addr
6778 jr cc,disp8 ldl @@rd,rrs negb addr(rd)
6779 ld @@rd,imm16 ldl addr(rd),rrs negb rbd
6780 ld @@rd,rs ldl addr,rrs nop
6781 ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs
6782 ld addr(rd),rs ldl rd(rx),rrs or rd,addr
6783 ld addr,imm16 ldl rrd,@@rs or rd,addr(rs)
6784 ld addr,rs ldl rrd,addr or rd,imm16
6785 ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs
6786 ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs
6787 ld rd,@@rs ldl rrd,rrs orb rbd,addr
6788 ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs)
6789 ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8
6790 ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs
6791 ld rd,rs ldm addr(rd),rs,n out @@rd,rs
6792 ld rd,rs(imm16) ldm addr,rs,n out imm16,rs
6793 ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs
6794 lda rd,addr ldm rd,addr(rs),n outb imm16,rbs
6795 lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra
6796 lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba
6797 lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra
6798 ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra
6799 ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs
6800 ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs
6801 ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs
6802 ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs
6803 ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs
6804 ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs
6805 ldb rbd,@@rs mbit popl addr,@@rs
6806 ldb rbd,addr mreq rd popl rrd,@@rs
6807 ldb rbd,addr(rs) mres push @@rd,@@rs
6808 ldb rbd,imm8 mset push @@rd,addr
6809 ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs)
6810 ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16
6811 push @@rd,rs set addr,imm4 subl rrd,imm32
6812 pushl @@rd,@@rs set rd,imm4 subl rrd,rrs
6813 pushl @@rd,addr set rd,rs tcc cc,rd
6814 pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd
6815 pushl @@rd,rrs setb addr(rd),imm4 test @@rd
6816 res @@rd,imm4 setb addr,imm4 test addr
6817 res addr(rd),imm4 setb rbd,imm4 test addr(rd)
6818 res addr,imm4 setb rbd,rs test rd
6819 res rd,imm4 setflg imm4 testb @@rd
6820 res rd,rs sinb rbd,imm16 testb addr
6821 resb @@rd,imm4 sinb rd,imm16 testb addr(rd)
6822 resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd
6823 resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd
6824 resb rbd,imm4 sinib @@rd,@@rs,ra testl addr
6825 resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd)
6826 resflg imm4 sla rd,imm8 testl rrd
6827 ret cc slab rbd,imm8 trdb @@rd,@@rs,rba
6828 rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba
6829 rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr
6830 rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr
6831 rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr
6832 rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr
6833 rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr
6834 rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr
6835 rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd
6836 rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr
6837 rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd)
6838 rsvd36 sra rd,imm8 tset rd
6839 rsvd38 srab rbd,imm8 tsetb @@rd
6840 rsvd78 sral rrd,imm8 tsetb addr
6841 rsvd7e srl rd,imm8 tsetb addr(rd)
6842 rsvd9d srlb rbd,imm8 tsetb rbd
6843 rsvd9f srll rrd,imm8 xor rd,@@rs
6844 rsvdb9 sub rd,@@rs xor rd,addr
6845 rsvdbf sub rd,addr xor rd,addr(rs)
6846 sbc rd,rs sub rd,addr(rs) xor rd,imm16
6847 sbcb rbd,rbs sub rd,imm16 xor rd,rs
6848 sc imm8 sub rd,rs xorb rbd,@@rs
6849 sda rd,rs subb rbd,@@rs xorb rbd,addr
6850 sdab rbd,rs subb rbd,addr xorb rbd,addr(rs)
6851 sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8
6852 sdl rd,rs subb rbd,imm8 xorb rbd,rbs
6853 sdlb rbd,rs subb rbd,rbs xorb rbd,rbs
6854 sdll rrd,rs subl rrd,@@rs
6855 set @@rd,imm4 subl rrd,addr
6856 set addr(rd),imm4 subl rrd,addr(rs)
6867 @node MIPS-Dependent
6868 @chapter MIPS Dependent Features
6871 @node Machine Dependencies
6872 @chapter MIPS Dependent Features
6874 The MIPS @value{AS} supports the MIPS R2000 and R3000 processors.
6876 It ignores the @samp{-nocpp} option.
6878 Not all traditional MIPS macro instructions are currently supported.
6879 Specifically, @code{li.d} and @code{li.s} are not currently supported.
6881 Assembling for a MIPS ECOFF target supports some additional sections
6882 besides the usual @code{.text}, @code{.data} and @code{.bss}. The
6883 additional sections are @code{.rdata}, used for read-only data,
6884 @code{.sdata}, used for small data, and @code{.sbss}, used for small
6887 When assembling for ECOFF, the assembler automatically uses the @code{$gp}
6888 (@code{$28}) register when forming the address of a small object. Any object
6889 in the @code{.sdata} or @code{.sbss} sections is considered ``small''. For
6890 external objects or objects in the @code{.bss} section, you may use the
6891 @samp{-G} option to control the size of objects for which the @code{$gp}
6892 register is used; the default value is 8, meaning that a reference to any
6893 object eight bytes or smaller uses @code{$gp}. Passing @samp{-G 0} to
6894 @value{AS} prevents it from using the @code{$gp} register at all. The size of
6895 an object in the @code{.bss} section is set by the @code{.comm} or
6896 @code{.lcomm} directive that defines it. The size of an external object may be
6897 set using the @code{.extern} directive. For example, @samp{.extern sym,4}
6898 declares that the object at @code{sym} is 4 bytes in length, while leaving
6899 @code{sym} otherwise undefined.
6901 Using small ECOFF objects requires linker support, and assumes that the
6902 @code{$gp} register was initialized correctly (normally done automatically
6903 by the startup code). MIPS ECOFF assembly code must avoid modifying the
6904 @code{$gp} register.
6906 MIPS ECOFF @code{@value{AS}} supports several directives used for generating
6907 debugging information which are not support by traditional MIPS
6908 assemblers. These are @code{.def}, @code{.endef}, @code{.dim},
6909 @code{.file}, @code{.scl}, @code{.size}, @code{.tag}, @code{.type},
6910 @code{.val}, @code{.stabd}, @code{.stabn}, and @code{.stabs}. The
6911 debugging information generated by the three @code{.stab} directives can
6912 only be read by GDB, not by traditional MIPS debuggers (this enhancement
6913 is required to fully support C++ debugging). These directives are
6914 primarily used by compilers, not assembly language programmers, and are
6915 described elsewhere in this manual.
6919 @c reverse effect of @down at top of generic Machine-Dep chapter
6923 @node Acknowledgements
6924 @chapter Acknowledgements
6926 If you have contributed to @code{@value{AS}} and your name isn't listed here,
6927 it is not meant as a slight. We just don't know about it. Send mail to the
6928 maintainer, and we'll correct the situation. Currently (June 1993), the
6929 maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
6931 Dean Elsner wrote the original GNU assembler for the VAX.@footnote{Any more
6934 Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
6935 information and the 68k series machines, most of the preprocessing pass, and
6936 extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}.
6938 K. Richard Pixley maintained GAS for a while, adding various enhancements and
6939 many bug fixes, including merging support for several processors, breaking GAS
6940 up to handle multiple object file format back ends (including heavy rewrite,
6941 testing, an integration of the coff and b.out back ends), adding configuration
6942 including heavy testing and verification of cross assemblers and file splits
6943 and renaming, converted GAS to strictly ANSI C including full prototypes, added
6944 support for m680[34]0 and cpu32, did considerable work on i960 including a COFF
6945 port (including considerable amounts of reverse engineering), a SPARC opcode
6946 file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know''
6947 assertions and made them work, much other reorganization, cleanup, and lint.
6949 Ken Raeburn wrote the high-level BFD interface code to replace most of the code
6950 in format-specific I/O modules.
6952 The original VMS support was contributed by David L. Kashtan. Eric Youngdale
6953 has done much work with it since.
6955 The Intel 80386 machine description was written by Eliot Dresselhaus.
6957 Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
6959 The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
6960 University and Torbjorn Granlund of the Swedish Institute of Computer Science.
6962 Keith Knowles at the Open Software Foundation wrote the original MIPS back end
6963 (@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support
6964 (which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to
6965 support a.out format.
6967 Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k,
6968 tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
6969 Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
6970 use BFD for some low-level operations, for use with the H8/300 and AMD 29k
6973 John Gilmore built the AMD 29000 support, added @code{.include} support, and
6974 simplified the configuration of which versions accept which directives. He
6975 updated the 68k machine description so that Motorola's opcodes always produced
6976 fixed-size instructions (e.g. @code{jsr}), while synthetic instructions
6977 remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested
6978 cross-compilation support, and one bug in relaxation that took a week and
6979 required the apocryphal one-bit fix.
6980 @c FIXME ``apocryphal'' surely wrong. What's meant?
6982 Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
6983 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
6984 and made a few other minor patches.
6986 Steve Chamberlain made @code{@value{AS}} able to generate listings.
6988 Hewlett-Packard contributed support for the HP9000/300.
6990 Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
6991 along with a fairly extensive HPPA testsuite (for both SOM and ELF object
6992 formats). This work was supported by both the Center for Software Science at
6993 the University of Utah and Cygnus Support.
6995 Support for ELF format files has been worked on by Mark Eichin of Cygnus
6996 Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
6997 Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
6998 Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
6999 and some initial 64-bit support).
7001 Several engineers at Cygnus Support have also provided many small bug fixes and
7002 configuration enhancements.
7004 Many others have contributed large or small bugfixes and enhancements. If
7005 you have contributed significant work and are not mentioned on this list, and
7006 want to be, let us know. Some of the history has been lost; we are not
7007 intentionally leaving anyone out.
7012 @include gpl.texinfo