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:: 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{} ]
216 @samp{-ad}, omit debugging pseudo-ops from listing,
217 @samp{-ah}, include high-level source,
218 @samp{-al}, assembly listing,
219 @samp{-an}, no forms processing,
221 These options may be combined; @emph{e.g.}, @samp{-aln} for assembly
222 listing without forms processing. By itself, @samp{-a} defaults to
223 @samp{-ahls} --- that is, all listings turned on.
226 This option is accepted only for script compatibility with calls to
227 other assemblers; it has no effect on @code{@value{AS}}.
230 ``fast''---skip whitespace and comment preprocessing (assume source is
234 Add @var{path} to the search list for @code{.include} directives
237 @ifclear DIFF-TBL-KLUGE
238 This option is accepted but has no effect on the @value{TARGET} family.
240 @ifset DIFF-TBL-KLUGE
241 Issue warnings when difference tables altered for long displacements.
245 Keep (in symbol table) local symbols, starting with @samp{L}
247 @item -o @var{objfile}
248 Name the object-file output from @code{@value{AS}}
251 Fold data section into text section
254 Announce @code{as} version
257 Suppress warning messages
259 @item -- | @var{files} @dots{}
260 Standard input, or source files to assemble.
265 The following options are available when @value{AS} is configured for the
266 Intel 80960 processor.
269 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
270 Specify which variant of the 960 architecture is the target.
273 Add code to collect statistics about branches taken.
276 Do not alter compare-and-branch instructions for long displacements;
283 The following options are available when @value{AS} is configured for the
284 Motorola 68000 series.
289 Shorten references to undefined symbols, to one word instead of two.
291 @item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040
292 @itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32
293 Specify what processor in the 68000 family is the target. The default
294 is normally the 68020, but this can be changed at configuration time.
296 @item -m68881 | -m68882 | -mno-68881 | -mno-68882
297 The target machine does (or does not) have a floating-point coprocessor.
298 The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
299 the basic 68000 is not compatible with the 68881, a combination of the
300 two can be specified, since it's possible to do emulation of the
301 coprocessor instructions with the main processor.
303 @item -m68851 | -mno-68851
304 The target machine does (or does not) have a memory-management
305 unit coprocessor. The default is to assume an MMU for 68020 and up.
311 The following options are available when @code{@value{AS}} is configured
312 for the SPARC architecture:
315 @item -Av6 | -Av7 | -Av8 | -Asparclite
316 Explicitly select a variant of the SPARC architecture.
319 Warn when the assembler switches to another architecture.
324 The following options are available when @value{AS} is configured for
325 the MIPS R2000/R3000 processors.
330 This option sets the largest size of an object that will be referenced
331 implicitly with the @code{gp} register. It is only accepted for targets
332 that use ECOFF format, such as a DECstation running Ultrix. The default
337 These options are ignored. They are accepted for compatibility with the
344 * Manual:: Structure of this Manual
345 * GNU Assembler:: @value{AS}, the GNU Assembler
346 * Object Formats:: Object File Formats
347 * Command Line:: Command Line
348 * Input Files:: Input Files
349 * Object:: Output (Object) File
350 * Errors:: Error and Warning Messages
354 @section Structure of this Manual
356 @cindex manual, structure and purpose
357 This manual is intended to describe what you need to know to use
358 @sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including
359 notation for symbols, constants, and expressions; the directives that
360 @code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}.
363 We also cover special features in the @value{TARGET}
364 configuration of @code{@value{AS}}, including assembler directives.
367 This manual also describes some of the machine-dependent features of
368 various flavors of the assembler.
371 This manual also describes how the assembler works internally, and
372 provides some information that may be useful to people attempting to
373 port the assembler to another machine.
377 @cindex machine instructions (not covered)
378 On the other hand, this manual is @emph{not} intended as an introduction
379 to programming in assembly language---let alone programming in general!
380 In a similar vein, we make no attempt to introduce the machine
381 architecture; we do @emph{not} describe the instruction set, standard
382 mnemonics, registers or addressing modes that are standard to a
383 particular architecture.
385 You may want to consult the manufacturer's
386 machine architecture manual for this information.
390 For information on the H8/300 machine instruction set, see @cite{H8/300
391 Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H,
392 see @cite{H8/300H Series Programming Manual} (Hitachi).
395 For information on the H8/500 machine instruction set, see @cite{H8/500
396 Series Programming Manual} (Hitachi M21T001).
399 For information on the Hitachi SH machine instruction set, see
400 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
403 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
407 @c I think this is premature---pesch@cygnus.com, 17jan1991
409 Throughout this manual, we assume that you are running @dfn{GNU},
410 the portable operating system from the @dfn{Free Software
411 Foundation, Inc.}. This restricts our attention to certain kinds of
412 computer (in particular, the kinds of computers that GNU can run on);
413 once this assumption is granted examples and definitions need less
416 @code{@value{AS}} is part of a team of programs that turn a high-level
417 human-readable series of instructions into a low-level
418 computer-readable series of instructions. Different versions of
419 @code{@value{AS}} are used for different kinds of computer.
422 @c There used to be a section "Terminology" here, which defined
423 @c "contents", "byte", "word", and "long". Defining "word" to any
424 @c particular size is confusing when the .word directive may generate 16
425 @c bits on one machine and 32 bits on another; in general, for the user
426 @c version of this manual, none of these terms seem essential to define.
427 @c They were used very little even in the former draft of the manual;
428 @c this draft makes an effort to avoid them (except in names of
432 @section @value{AS}, the GNU Assembler
434 GNU @code{as} is really a family of assemblers.
436 This manual describes @code{@value{AS}}, a member of that family which is
437 configured for the @value{TARGET} architectures.
439 If you use (or have used) the GNU assembler on one architecture, you
440 should find a fairly similar environment when you use it on another
441 architecture. Each version has much in common with the others,
442 including object file formats, most assembler directives (often called
443 @dfn{pseudo-ops}) and assembler syntax.@refill
445 @cindex purpose of @sc{gnu} @code{@value{AS}}
446 @code{@value{AS}} is primarily intended to assemble the output of the
447 GNU C compiler @code{@value{GCC}} for use by the linker
448 @code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}}
449 assemble correctly everything that other assemblers for the same
450 machine would assemble.
452 Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
455 @c This remark should appear in generic version of manual; assumption
456 @c here is that generic version sets M680x0.
457 This doesn't mean @code{@value{AS}} always uses the same syntax as another
458 assembler for the same architecture; for example, we know of several
459 incompatible versions of 680x0 assembly language syntax.
462 Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
463 program in one pass of the source file. This has a subtle impact on the
464 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
467 @section Object File Formats
469 @cindex object file format
470 The GNU assembler can be configured to produce several alternative
471 object file formats. For the most part, this does not affect how you
472 write assembly language programs; but directives for debugging symbols
473 are typically different in different file formats. @xref{Symbol
474 Attributes,,Symbol Attributes}.
477 On the @value{TARGET}, @code{@value{AS}} is configured to produce
478 @value{OBJ-NAME} format object files.
480 @c The following should exhaust all configs that set MULTI-OBJ, ideally
482 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
483 @code{a.out} or COFF format object files.
486 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
487 @code{b.out} or COFF format object files.
490 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
491 SOM or ELF format object files.
496 @section Command Line
498 @cindex command line conventions
499 After the program name @code{@value{AS}}, the command line may contain
500 options and file names. Options may appear in any order, and may be
501 before, after, or between file names. The order of file names is
504 @cindex standard input, as input file
506 @file{--} (two hyphens) by itself names the standard input file
507 explicitly, as one of the files for @code{@value{AS}} to assemble.
509 @cindex options, command line
510 Except for @samp{--} any command line argument that begins with a
511 hyphen (@samp{-}) is an option. Each option changes the behavior of
512 @code{@value{AS}}. No option changes the way another option works. An
513 option is a @samp{-} followed by one or more letters; the case of
514 the letter is important. All options are optional.
516 Some options expect exactly one file name to follow them. The file
517 name may either immediately follow the option's letter (compatible
518 with older assemblers) or it may be the next command argument (GNU
519 standard). These two command lines are equivalent:
522 @value{AS} -o my-object-file.o mumble.s
523 @value{AS} -omy-object-file.o mumble.s
530 @cindex source program
532 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
533 describe the program input to one run of @code{@value{AS}}. The program may
534 be in one or more files; how the source is partitioned into files
535 doesn't change the meaning of the source.
537 @c I added "con" prefix to "catenation" just to prove I can overcome my
538 @c APL training... pesch@cygnus.com
539 The source program is a concatenation of the text in all the files, in the
542 Each time you run @code{@value{AS}} it assembles exactly one source
543 program. The source program is made up of one or more files.
544 (The standard input is also a file.)
546 You give @code{@value{AS}} a command line that has zero or more input file
547 names. The input files are read (from left file name to right). A
548 command line argument (in any position) that has no special meaning
549 is taken to be an input file name.
551 If you give @code{@value{AS}} no file names it attempts to read one input file
552 from the @code{@value{AS}} standard input, which is normally your terminal. You
553 may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program
556 Use @samp{--} if you need to explicitly name the standard input file
557 in your command line.
559 If the source is empty, @code{@value{AS}} will produce a small, empty object
562 @subheading Filenames and Line-numbers
564 @cindex input file linenumbers
565 @cindex line numbers, in input files
566 There are two ways of locating a line in the input file (or files) and
567 either may be used in reporting error messages. One way refers to a line
568 number in a physical file; the other refers to a line number in a
569 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
571 @dfn{Physical files} are those files named in the command line given
572 to @code{@value{AS}}.
574 @dfn{Logical files} are simply names declared explicitly by assembler
575 directives; they bear no relation to physical files. Logical file names
576 help error messages reflect the original source file, when @code{@value{AS}}
577 source is itself synthesized from other files.
578 @xref{App-File,,@code{.app-file}}.
581 @section Output (Object) File
587 Every time you run @code{@value{AS}} it produces an output file, which is
588 your assembly language program translated into numbers. This file
589 is the object file, named
593 if @code{@value{AS}} is configured for the Intel 80960, or
599 unless you tell @code{@value{AS}} to
600 give it another name by using the @code{-o} option. Conventionally,
601 object file names end with @file{.o}. The default name of
602 @file{a.out} is used for historical reasons: older assemblers were
603 capable of assembling self-contained programs directly into a
605 (For some formats, this isn't currently possible, but it can be done for
606 @code{a.out} format.)
610 The object file is meant for input to the linker @code{@value{LD}}. It contains
611 assembled program code, information to help @code{@value{LD}} integrate
612 the assembled program into a runnable file, and (optionally) symbolic
613 information for the debugger.
615 @c link above to some info file(s) like the description of a.out.
616 @c don't forget to describe GNU info as well as Unix lossage.
619 @section Error and Warning Messages
621 @cindex error messsages
622 @cindex warning messages
623 @cindex messages from @code{@value{AS}}
624 @code{@value{AS}} may write warnings and error messages to the standard error
625 file (usually your terminal). This should not happen when a compiler
626 runs @code{@value{AS}} automatically. Warnings report an assumption made so
627 that @code{@value{AS}} could keep assembling a flawed program; errors report a
628 grave problem that stops the assembly.
630 @cindex format of warning messages
631 Warning messages have the format
634 file_name:@b{NNN}:Warning Message Text
638 @cindex line numbers, in warnings/errors
639 (where @b{NNN} is a line number). If a logical file name has been given
640 (@pxref{App-File,,@code{.app-file}}) it is used for the filename,
641 otherwise the name of the current input file is used. If a logical line
644 (@pxref{Line,,@code{.line}})
648 (@pxref{Line,,@code{.line}})
651 (@pxref{Ln,,@code{.ln}})
654 then it is used to calculate the number printed,
655 otherwise the actual line in the current source file is printed. The
656 message text is intended to be self explanatory (in the grand Unix
659 @cindex format of error messages
660 Error messages have the format
662 file_name:@b{NNN}:FATAL:Error Message Text
664 The file name and line number are derived as for warning
665 messages. The actual message text may be rather less explanatory
666 because many of them aren't supposed to happen.
669 @chapter Command-Line Options
671 @cindex options, all versions of @code{@value{AS}}
672 This chapter describes command-line options available in @emph{all}
673 versions of the GNU assembler; @pxref{Machine Dependencies}, for options specific
675 to the @value{TARGET}.
678 to particular machine architectures.
681 If you are invoking @code{@value{AS}} via the GNU C compiler (version 2), you
682 can use the @samp{-Wa} option to pass arguments through to the
683 assembler. The assembler arguments must be separated from each other
684 (and the @samp{-Wa}) by commas. For example:
687 gcc -c -g -O -Wa,-alh,-L file.c
690 will cause a listing to be emitted to standard output with high-level
693 Many compiler command-line options, such as @samp{-R} and many
694 machine-specific options, will be automatically be passed to the
695 assembler by the compiler, so usually you do not need to use this
696 @samp{-Wa} mechanism.
699 * a:: -a[dhlns] enable listings
700 * D:: -D for compatibility
701 * f:: -f to work faster
702 * I:: -I for .include search path
703 @ifclear DIFF-TBL-KLUGE
704 * K:: -K for compatibility
706 @ifset DIFF-TBL-KLUGE
707 * K:: -K for difference tables
710 * L:: -L to retain local labels
711 * o:: -o to name the object file
712 * R:: -R to join data and text sections
713 * v:: -v to announce version
714 * W:: -W to suppress warnings
718 @section Enable Listings: @code{-a[dhlns]}
726 @cindex listings, enabling
727 @cindex assembly listings, enabling
729 These options enable listing output from the assembler. By itself,
730 @samp{-a} requests high-level, assembly, and symbols listing.
731 Other letters may be used to select specific options for the list:
732 @samp{-ah} requests a high-level language listing,
733 @samp{-al} requests an output-program assembly listing, and
734 @samp{-as} requests a symbol table listing.
735 High-level listings require that a compiler debugging option like
736 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
739 The @samp{-ad} option may be used to omit debugging pseudo-ops from the
742 Once you have specified one of these options, you can further control
743 listing output and its appearance using the directives @code{.list},
744 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
746 The @samp{-an} option turns off all forms processing.
747 If you do not request listing output with one of the @samp{-a} options, the
748 listing-control directives have no effect.
750 The letters after @samp{-a} may be combined into one option,
751 @emph{e.g.}, @samp{-aln}.
757 This option has no effect whatsoever, but it is accepted to make it more
758 likely that scripts written for other assemblers will also work with
762 @section Work Faster: @code{-f}
765 @cindex trusted compiler
766 @cindex faster processing (@code{-f})
767 @samp{-f} should only be used when assembling programs written by a
768 (trusted) compiler. @samp{-f} stops the assembler from doing whitespace
769 and comment pre-processing on
770 the input file(s) before assembling them. @xref{Pre-processing,
774 @emph{Warning:} if the files actually need to be pre-processed (if they
775 contain comments, for example), @code{@value{AS}} will not work correctly if
780 @section @code{.include} search path: @code{-I} @var{path}
782 @kindex -I @var{path}
783 @cindex paths for @code{.include}
784 @cindex search path for @code{.include}
785 @cindex @code{include} directive search path
786 Use this option to add a @var{path} to the list of directories
787 @code{@value{AS}} will search for files specified in @code{.include}
788 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
789 many times as necessary to include a variety of paths. The current
790 working directory is always searched first; after that, @code{@value{AS}}
791 searches any @samp{-I} directories in the same order as they were
792 specified (left to right) on the command line.
795 @section Difference Tables: @code{-K}
798 @ifclear DIFF-TBL-KLUGE
799 On the @value{TARGET} family, this option is allowed, but has no effect. It is
800 permitted for compatibility with the GNU assembler on other platforms,
801 where it can be used to warn when the assembler alters the machine code
802 generated for @samp{.word} directives in difference tables. The @value{TARGET}
803 family does not have the addressing limitations that sometimes lead to this
804 alteration on other platforms.
807 @ifset DIFF-TBL-KLUGE
808 @cindex difference tables, warning
809 @cindex warning for altered difference tables
810 @code{@value{AS}} sometimes alters the code emitted for directives of the form
811 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
812 You can use the @samp{-K} option if you want a warning issued when this
817 @section Include Local Labels: @code{-L}
820 @cindex local labels, retaining in output
821 Labels beginning with @samp{L} (upper case only) are called @dfn{local
822 labels}. @xref{Symbol Names}. Normally you don't see such labels when
823 debugging, because they are intended for the use of programs (like
824 compilers) that compose assembler programs, not for your notice.
825 Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you don't
826 normally debug with them.
828 This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols
829 in the object file. Usually if you do this you also tell the linker
830 @code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
832 By default, a local label is any label beginning with @samp{L}, but each
833 target is allowed to redefine the local label prefix.
835 On the HPPA local labels begin with @samp{L$}.
839 @section Name the Object File: @code{-o}
842 @cindex naming object file
843 @cindex object file name
844 There is always one object file output when you run @code{@value{AS}}. By
845 default it has the name
848 @file{a.out} (or @file{b.out}, for Intel 960 targets only).
862 You use this option (which takes exactly one filename) to give the
863 object file a different name.
865 Whatever the object file is called, @code{@value{AS}} will overwrite any
866 existing file of the same name.
869 @section Join Data and Text Sections: @code{-R}
872 @cindex data and text sections, joining
873 @cindex text and data sections, joining
874 @cindex joining text and data sections
875 @cindex merging text and data sections
876 @code{-R} tells @code{@value{AS}} to write the object file as if all
877 data-section data lives in the text section. This is only done at
878 the very last moment: your binary data are the same, but data
879 section parts are relocated differently. The data section part of
880 your object file is zero bytes long because all its bytes are
881 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
883 When you specify @code{-R} it would be possible to generate shorter
884 address displacements (because we don't have to cross between text and
885 data section). We refrain from doing this simply for compatibility with
886 older versions of @code{@value{AS}}. In future, @code{-R} may work this way.
889 When @code{@value{AS}} is configured for COFF output,
890 this option is only useful if you use sections named @samp{.text} and
895 @code{-R} is not supported for any of the HPPA targets . Using
896 @code{-R} will generate a warning from @code{@value{AS}}.
900 @section Announce Version: @code{-v}
904 @cindex @code{@value{AS}} version
905 @cindex version of @code{@value{AS}}
906 You can find out what version of as is running by including the
907 option @samp{-v} (which you can also spell as @samp{-version}) on the
911 @section Suppress Warnings: @code{-W}
914 @cindex suppressing warnings
915 @cindex warnings, suppressing
916 @code{@value{AS}} should never give a warning or error message when
917 assembling compiler output. But programs written by people often
918 cause @code{@value{AS}} to give a warning that a particular assumption was
919 made. All such warnings are directed to the standard error file.
920 If you use this option, no warnings are issued. This option only
921 affects the warning messages: it does not change any particular of how
922 @code{@value{AS}} assembles your file. Errors, which stop the assembly, are
928 @cindex machine-independent syntax
929 @cindex syntax, machine-independent
930 This chapter describes the machine-independent syntax allowed in a
931 source file. @code{@value{AS}} syntax is similar to what many other
932 assemblers use; it is inspired by the BSD 4.2
937 assembler, except that @code{@value{AS}} does not assemble Vax bit-fields.
941 * Pre-processing:: Pre-processing
942 * Whitespace:: Whitespace
943 * Comments:: Comments
944 * Symbol Intro:: Symbols
945 * Statements:: Statements
946 * Constants:: Constants
950 @section Pre-Processing
952 @cindex preprocessing
953 The @code{@value{AS}} internal pre-processor:
955 @cindex whitespace, removed by preprocessor
957 adjusts and removes extra whitespace. It leaves one space or tab before
958 the keywords on a line, and turns any other whitespace on the line into
961 @cindex comments, removed by preprocessor
963 removes all comments, replacing them with a single space, or an
964 appropriate number of newlines.
966 @cindex constants, converted by preprocessor
968 converts character constants into the appropriate numeric values.
971 Note that it does not do macro processing, include file handling, or
972 anything else you may get from your C compiler's pre-processor. You can
973 do include file processing with the @code{.include} directive
974 (@pxref{Include,,@code{.include}}). Other ``CPP'' style pre-processing
975 can be done with the @sc{GNU} C compiler, by giving the input file a
976 @code{.S} suffix; see the compiler documentation for details.
978 Excess whitespace, comments, and character constants
979 cannot be used in the portions of the input text that are not
982 @cindex turning preprocessing on and off
983 @cindex preprocessing, turning on and off
986 If the first line of an input file is @code{#NO_APP} or the @samp{-f}
987 option is given, the input file will not be pre-processed. Within such
988 an input file, parts of the file can be pre-processed by putting a line
989 that says @code{#APP} before the text that should be pre-processed, and
990 putting a line that says @code{#NO_APP} after them. This feature is
991 mainly intend to support @code{asm} statements in compilers whose output
992 normally does not need to be pre-processed.
998 @dfn{Whitespace} is one or more blanks or tabs, in any order.
999 Whitespace is used to separate symbols, and to make programs neater for
1000 people to read. Unless within character constants
1001 (@pxref{Characters,,Character Constants}), any whitespace means the same
1002 as exactly one space.
1008 There are two ways of rendering comments to @code{@value{AS}}. In both
1009 cases the comment is equivalent to one space.
1011 Anything from @samp{/*} through the next @samp{*/} is a comment.
1012 This means you may not nest these comments.
1016 The only way to include a newline ('\n') in a comment
1017 is to use this sort of comment.
1020 /* This sort of comment does not nest. */
1023 @cindex line comment character
1024 Anything from the @dfn{line comment} character to the next newline
1025 is considered a comment and is ignored. The line comment character is
1027 @samp{#} on the Vax;
1030 @samp{#} on the i960;
1033 @samp{!} on the SPARC;
1036 @samp{|} on the 680x0;
1039 @samp{;} for the AMD 29K family;
1042 @samp{;} for the H8/300 family;
1045 @samp{!} for the H8/500 family;
1048 @samp{;} for the HPPA;
1051 @samp{!} for the Hitachi SH;
1054 @samp{!} for the Z8000;
1056 see @ref{Machine Dependencies}. @refill
1057 @c FIXME What about i386, m88k, i860?
1060 On some machines there are two different line comment characters. One
1061 will only begin a comment if it is the first non-whitespace character on
1062 a line, while the other will always begin a comment.
1066 @cindex lines starting with @code{#}
1067 @cindex logical line numbers
1068 To be compatible with past assemblers, a special interpretation is
1069 given to lines that begin with @samp{#}. Following the @samp{#} an
1070 absolute expression (@pxref{Expressions}) is expected: this will be
1071 the logical line number of the @b{next} line. Then a string
1072 (@xref{Strings}.) is allowed: if present it is a new logical file
1073 name. The rest of the line, if any, should be whitespace.
1075 If the first non-whitespace characters on the line are not numeric,
1076 the line is ignored. (Just like a comment.)
1078 # This is an ordinary comment.
1079 # 42-6 "new_file_name" # New logical file name
1080 # This is logical line # 36.
1082 This feature is deprecated, and may disappear from future versions
1083 of @code{@value{AS}}.
1088 @cindex characters used in symbols
1089 @ifclear SPECIAL-SYMS
1090 A @dfn{symbol} is one or more characters chosen from the set of all
1091 letters (both upper and lower case), digits and the three characters
1097 A @dfn{symbol} is one or more characters chosen from the set of all
1098 letters (both upper and lower case), digits and the three characters
1099 @samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in
1105 On most machines, you can also use @code{$} in symbol names; exceptions
1106 are noted in @ref{Machine Dependencies}.
1108 No symbol may begin with a digit. Case is significant.
1109 There is no length limit: all characters are significant. Symbols are
1110 delimited by characters not in that set, or by the beginning of a file
1111 (since the source program must end with a newline, the end of a file is
1112 not a possible symbol delimiter). @xref{Symbols}.
1113 @cindex length of symbols
1118 @cindex statements, structure of
1119 @cindex line separator character
1120 @cindex statement separator character
1122 @ifclear abnormal-separator
1123 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
1124 semicolon (@samp{;}). The newline or semicolon is considered part of
1125 the preceding statement. Newlines and semicolons within character
1126 constants are an exception: they don't end statements.
1128 @ifset abnormal-separator
1130 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
1131 sign (@samp{@@}). The newline or at sign is considered part of the
1132 preceding statement. Newlines and at signs within character constants
1133 are an exception: they don't end statements.
1136 A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation
1137 point (@samp{!}). The newline or exclamation point is considered part of the
1138 preceding statement. Newlines and exclamation points within character
1139 constants are an exception: they don't end statements.
1142 A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
1143 H8/300) a dollar sign (@samp{$}); or (for the
1146 (@samp{;}). The newline or separator character is considered part of
1147 the preceding statement. Newlines and separators within character
1148 constants are an exception: they don't end statements.
1153 A @dfn{statement} ends at a newline character (@samp{\n}) or line
1154 separator character. (The line separator is usually @samp{;}, unless
1155 this conflicts with the comment character; @pxref{Machine Dependencies}.) The
1156 newline or separator character is considered part of the preceding
1157 statement. Newlines and separators within character constants are an
1158 exception: they don't end statements.
1161 @cindex newline, required at file end
1162 @cindex EOF, newline must precede
1163 It is an error to end any statement with end-of-file: the last
1164 character of any input file should be a newline.@refill
1166 @cindex continuing statements
1167 @cindex multi-line statements
1168 @cindex statement on multiple lines
1169 You may write a statement on more than one line if you put a
1170 backslash (@kbd{\}) immediately in front of any newlines within the
1171 statement. When @code{@value{AS}} reads a backslashed newline both
1172 characters are ignored. You can even put backslashed newlines in
1173 the middle of symbol names without changing the meaning of your
1176 An empty statement is allowed, and may include whitespace. It is ignored.
1178 @cindex instructions and directives
1179 @cindex directives and instructions
1180 @c "key symbol" is not used elsewhere in the document; seems pedantic to
1181 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
1183 A statement begins with zero or more labels, optionally followed by a
1184 key symbol which determines what kind of statement it is. The key
1185 symbol determines the syntax of the rest of the statement. If the
1186 symbol begins with a dot @samp{.} then the statement is an assembler
1187 directive: typically valid for any computer. If the symbol begins with
1188 a letter the statement is an assembly language @dfn{instruction}: it
1189 will assemble into a machine language instruction.
1191 Different versions of @code{@value{AS}} for different computers will
1192 recognize different instructions. In fact, the same symbol may
1193 represent a different instruction in a different computer's assembly
1197 @cindex @code{:} (label)
1198 @cindex label (@code{:})
1199 A label is a symbol immediately followed by a colon (@code{:}).
1200 Whitespace before a label or after a colon is permitted, but you may not
1201 have whitespace between a label's symbol and its colon. @xref{Labels}.
1204 For HPPA targets, labels need not be immediately followed by a colon, but
1205 the definition of a label must begin in column zero. This also implies that
1206 only one label may be defined on each line.
1210 label: .directive followed by something
1211 another_label: # This is an empty statement.
1212 instruction operand_1, operand_2, @dots{}
1219 A constant is a number, written so that its value is known by
1220 inspection, without knowing any context. Like this:
1223 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
1224 .ascii "Ring the bell\7" # A string constant.
1225 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
1226 .float 0f-314159265358979323846264338327\
1227 95028841971.693993751E-40 # - pi, a flonum.
1232 * Characters:: Character Constants
1233 * Numbers:: Number Constants
1237 @subsection Character Constants
1239 @cindex character constants
1240 @cindex constants, character
1241 There are two kinds of character constants. A @dfn{character} stands
1242 for one character in one byte and its value may be used in
1243 numeric expressions. String constants (properly called string
1244 @emph{literals}) are potentially many bytes and their values may not be
1245 used in arithmetic expressions.
1249 * Chars:: Characters
1253 @subsubsection Strings
1255 @cindex string constants
1256 @cindex constants, string
1257 A @dfn{string} is written between double-quotes. It may contain
1258 double-quotes or null characters. The way to get special characters
1259 into a string is to @dfn{escape} these characters: precede them with
1260 a backslash @samp{\} character. For example @samp{\\} represents
1261 one backslash: the first @code{\} is an escape which tells
1262 @code{@value{AS}} to interpret the second character literally as a backslash
1263 (which prevents @code{@value{AS}} from recognizing the second @code{\} as an
1264 escape character). The complete list of escapes follows.
1266 @cindex escape codes, character
1267 @cindex character escape codes
1270 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1273 @cindex @code{\b} (backspace character)
1274 @cindex backspace (@code{\b})
1275 Mnemonic for backspace; for ASCII this is octal code 010.
1278 @c Mnemonic for EOText; for ASCII this is octal code 004.
1281 @cindex @code{\f} (formfeed character)
1282 @cindex formfeed (@code{\f})
1283 Mnemonic for FormFeed; for ASCII this is octal code 014.
1286 @cindex @code{\n} (newline character)
1287 @cindex newline (@code{\n})
1288 Mnemonic for newline; for ASCII this is octal code 012.
1291 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1294 @cindex @code{\r} (carriage return character)
1295 @cindex carriage return (@code{\r})
1296 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1299 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1300 @c other assemblers.
1303 @cindex @code{\t} (tab)
1304 @cindex tab (@code{\t})
1305 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1308 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1309 @c @item \x @var{digit} @var{digit} @var{digit}
1310 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1312 @item \ @var{digit} @var{digit} @var{digit}
1313 @cindex @code{\@var{ddd}} (octal character code)
1314 @cindex octal character code (@code{\@var{ddd}})
1315 An octal character code. The numeric code is 3 octal digits.
1316 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1317 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1320 @item \@code{x} @var{hex-digit} @var{hex-digit}
1321 @cindex @code{\@var{xdd}} (hex character code)
1322 @cindex hex character code (@code{\@var{xdd}})
1323 A hex character code. The numeric code is 2 hexidecimal digits. Either
1324 an upper or lower case @code{x} may be used.
1328 @cindex @code{\\} (@samp{\} character)
1329 @cindex backslash (@code{\\})
1330 Represents one @samp{\} character.
1333 @c Represents one @samp{'} (accent acute) character.
1334 @c This is needed in single character literals
1335 @c (@xref{Characters,,Character Constants}.) to represent
1339 @cindex @code{\"} (doublequote character)
1340 @cindex doublequote (@code{\"})
1341 Represents one @samp{"} character. Needed in strings to represent
1342 this character, because an unescaped @samp{"} would end the string.
1344 @item \ @var{anything-else}
1345 Any other character when escaped by @kbd{\} will give a warning, but
1346 assemble as if the @samp{\} was not present. The idea is that if
1347 you used an escape sequence you clearly didn't want the literal
1348 interpretation of the following character. However @code{@value{AS}} has no
1349 other interpretation, so @code{@value{AS}} knows it is giving you the wrong
1350 code and warns you of the fact.
1353 Which characters are escapable, and what those escapes represent,
1354 varies widely among assemblers. The current set is what we think
1355 the BSD 4.2 assembler recognizes, and is a subset of what most C
1356 compilers recognize. If you are in doubt, don't use an escape
1360 @subsubsection Characters
1362 @cindex single character constant
1363 @cindex character, single
1364 @cindex constant, single character
1365 A single character may be written as a single quote immediately
1366 followed by that character. The same escapes apply to characters as
1367 to strings. So if you want to write the character backslash, you
1368 must write @kbd{'\\} where the first @code{\} escapes the second
1369 @code{\}. As you can see, the quote is an acute accent, not a
1370 grave accent. A newline
1372 @ifclear abnormal-separator
1373 (or semicolon @samp{;})
1375 @ifset abnormal-separator
1377 (or at sign @samp{@@})
1380 (or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
1386 immediately following an acute accent is taken as a literal character
1387 and does not count as the end of a statement. The value of a character
1388 constant in a numeric expression is the machine's byte-wide code for
1389 that character. @code{@value{AS}} assumes your character code is ASCII:
1390 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1393 @subsection Number Constants
1395 @cindex constants, number
1396 @cindex number constants
1397 @code{@value{AS}} distinguishes three kinds of numbers according to how they
1398 are stored in the target machine. @emph{Integers} are numbers that
1399 would fit into an @code{int} in the C language. @emph{Bignums} are
1400 integers, but they are stored in more than 32 bits. @emph{Flonums}
1401 are floating point numbers, described below.
1404 * Integers:: Integers
1409 * Bit Fields:: Bit Fields
1415 @subsubsection Integers
1417 @cindex constants, integer
1419 @cindex binary integers
1420 @cindex integers, binary
1421 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1422 the binary digits @samp{01}.
1424 @cindex octal integers
1425 @cindex integers, octal
1426 An octal integer is @samp{0} followed by zero or more of the octal
1427 digits (@samp{01234567}).
1429 @cindex decimal integers
1430 @cindex integers, decimal
1431 A decimal integer starts with a non-zero digit followed by zero or
1432 more digits (@samp{0123456789}).
1434 @cindex hexadecimal integers
1435 @cindex integers, hexadecimal
1436 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1437 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1439 Integers have the usual values. To denote a negative integer, use
1440 the prefix operator @samp{-} discussed under expressions
1441 (@pxref{Prefix Ops,,Prefix Operators}).
1444 @subsubsection Bignums
1447 @cindex constants, bignum
1448 A @dfn{bignum} has the same syntax and semantics as an integer
1449 except that the number (or its negative) takes more than 32 bits to
1450 represent in binary. The distinction is made because in some places
1451 integers are permitted while bignums are not.
1454 @subsubsection Flonums
1456 @cindex floating point numbers
1457 @cindex constants, floating point
1459 @cindex precision, floating point
1460 A @dfn{flonum} represents a floating point number. The translation is
1461 indirect: a decimal floating point number from the text is converted by
1462 @code{@value{AS}} to a generic binary floating point number of more than
1463 sufficient precision. This generic floating point number is converted
1464 to a particular computer's floating point format (or formats) by a
1465 portion of @code{@value{AS}} specialized to that computer.
1467 A flonum is written by writing (in order)
1472 @samp{0} is optional on the HPPA.
1476 A letter, to tell @code{@value{AS}} the rest of the number is a flonum.
1478 @kbd{e} is recommended. Case is not important.
1480 @c FIXME: verify if flonum syntax really this vague for most cases
1481 (Any otherwise illegal letter
1482 will work here, but that might be changed. Vax BSD 4.2 assembler seems
1483 to allow any of @samp{defghDEFGH}.)
1486 On the H8/300, H8/500,
1488 and AMD 29K architectures, the letter must be
1489 one of the letters @samp{DFPRSX} (in upper or lower case).
1491 On the Intel 960 architecture, the letter must be
1492 one of the letters @samp{DFT} (in upper or lower case).
1494 On the HPPA architecture, the letter must be @samp{E} (upper case only).
1498 One of the letters @samp{DFPRSX} (in upper or lower case).
1501 One of the letters @samp{DFPRSX} (in upper or lower case).
1504 One of the letters @samp{DFT} (in upper or lower case).
1507 On the HPPA architecture, the letter must be @samp{E} (upper case only).
1512 An optional sign: either @samp{+} or @samp{-}.
1515 An optional @dfn{integer part}: zero or more decimal digits.
1518 An optional @dfn{fractional part}: @samp{.} followed by zero
1519 or more decimal digits.
1522 An optional exponent, consisting of:
1526 An @samp{E} or @samp{e}.
1527 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1528 @c principle this can perfectly well be different on different targets.
1530 Optional sign: either @samp{+} or @samp{-}.
1532 One or more decimal digits.
1537 At least one of the integer part or the fractional part must be
1538 present. The floating point number has the usual base-10 value.
1540 @code{@value{AS}} does all processing using integers. Flonums are computed
1541 independently of any floating point hardware in the computer running
1546 @c Bit fields are written as a general facility but are also controlled
1547 @c by a conditional-compilation flag---which is as of now (21mar91)
1548 @c turned on only by the i960 config of GAS.
1550 @subsubsection Bit Fields
1553 @cindex constants, bit field
1554 You can also define numeric constants as @dfn{bit fields}.
1555 specify two numbers separated by a colon---
1557 @var{mask}:@var{value}
1560 the first will act as a mask; @code{@value{AS}} will bitwise-and it with the
1563 The resulting number is then packed
1565 @c this conditional paren in case bit fields turned on elsewhere than 960
1566 (in host-dependent byte order)
1568 into a field whose width depends on which assembler directive has the
1569 bit-field as its argument. Overflow (a result from the bitwise and
1570 requiring more binary digits to represent) is not an error; instead,
1571 more constants are generated, of the specified width, beginning with the
1572 least significant digits.@refill
1574 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1575 @code{.short}, and @code{.word} accept bit-field arguments.
1580 @chapter Sections and Relocation
1585 * Secs Background:: Background
1586 * Ld Sections:: @value{LD} Sections
1587 * As Sections:: @value{AS} Internal Sections
1588 * Sub-Sections:: Sub-Sections
1592 @node Secs Background
1595 Roughly, a section is a range of addresses, with no gaps; all data
1596 ``in'' those addresses is treated the same for some particular purpose.
1597 For example there may be a ``read only'' section.
1599 @cindex linker, and assembler
1600 @cindex assembler, and linker
1601 The linker @code{@value{LD}} reads many object files (partial programs) and
1602 combines their contents to form a runnable program. When @code{@value{AS}}
1603 emits an object file, the partial program is assumed to start at address
1604 0. @code{@value{LD}} will assign the final addresses the partial program
1605 occupies, so that different partial programs don't overlap. This is
1606 actually an over-simplification, but it will suffice to explain how
1607 @code{@value{AS}} uses sections.
1609 @code{@value{LD}} moves blocks of bytes of your program to their run-time
1610 addresses. These blocks slide to their run-time addresses as rigid
1611 units; their length does not change and neither does the order of bytes
1612 within them. Such a rigid unit is called a @emph{section}. Assigning
1613 run-time addresses to sections is called @dfn{relocation}. It includes
1614 the task of adjusting mentions of object-file addresses so they refer to
1615 the proper run-time addresses.
1617 For the H8/300 and H8/500,
1618 and for the Hitachi SH,
1619 @code{@value{AS}} pads sections if needed to
1620 ensure they end on a word (sixteen bit) boundary.
1623 @cindex standard @code{@value{AS}} sections
1624 An object file written by @code{@value{AS}} has at least three sections, any
1625 of which may be empty. These are named @dfn{text}, @dfn{data} and
1630 When it generates COFF output,
1632 @code{@value{AS}} can also generate whatever other named sections you specify
1633 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1634 If you don't use any directives that place output in the @samp{.text}
1635 or @samp{.data} sections, these sections will still exist, but will be empty.
1640 When @code{@value{AS}} generates SOM or ELF output for the HPPA,
1642 @code{@value{AS}} can also generate whatever other named sections you
1643 specify using the @samp{.space} and @samp{.subspace} directives. See
1644 @cite{HP9000 Series 800 Assembly Language Reference Manual}
1645 (HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
1646 assembler directives.
1649 Additionally, @code{@value{AS}} uses different names for the standard
1650 text, data, and bss sections when generating SOM output. Program text
1651 is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
1652 BSS into @samp{$BSS$}.
1656 Within the object file, the text section starts at address @code{0}, the
1657 data section follows, and the bss section follows the data section.
1660 When generating either SOM or ELF output files on the HPPA, the text
1661 section starts at address @code{0}, the data section at address
1662 @code{0x4000000}, and the bss section follows the data section.
1665 To let @code{@value{LD}} know which data will change when the sections are
1666 relocated, and how to change that data, @code{@value{AS}} also writes to the
1667 object file details of the relocation needed. To perform relocation
1668 @code{@value{LD}} must know, each time an address in the object
1672 Where in the object file is the beginning of this reference to
1675 How long (in bytes) is this reference?
1677 Which section does the address refer to? What is the numeric value of
1679 (@var{address}) @minus{} (@var{start-address of section})?
1682 Is the reference to an address ``Program-Counter relative''?
1685 @cindex addresses, format of
1686 @cindex section-relative addressing
1687 In fact, every address @code{@value{AS}} ever uses is expressed as
1689 (@var{section}) + (@var{offset into section})
1692 Further, every expression @code{@value{AS}} computes is of this section-relative
1693 nature. @dfn{Absolute expression} means an expression with section
1694 ``absolute'' (@pxref{Ld Sections}). A @dfn{pass1 expression} means
1695 an expression with section ``pass1'' (@pxref{As Sections,,@value{AS}
1696 Internal Sections}). In this manual we use the notation @{@var{secname}
1697 @var{N}@} to mean ``offset @var{N} into section @var{secname}''.
1699 Apart from text, data and bss sections you need to know about the
1700 @dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
1701 addresses in the absolute section remain unchanged. For example, address
1702 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by @code{@value{LD}}.
1703 Although two partial programs' data sections will not overlap addresses
1704 after linking, @emph{by definition} their absolute sections will overlap.
1705 Address @code{@{absolute@ 239@}} in one partial program will always be the same
1706 address when the program is running as address @code{@{absolute@ 239@}} in any
1707 other partial program.
1709 The idea of sections is extended to the @dfn{undefined} section. Any
1710 address whose section is unknown at assembly time is by definition
1711 rendered @{undefined @var{U}@}---where @var{U} will be filled in later.
1712 Since numbers are always defined, the only way to generate an undefined
1713 address is to mention an undefined symbol. A reference to a named
1714 common block would be such a symbol: its value is unknown at assembly
1715 time so it has section @emph{undefined}.
1717 By analogy the word @emph{section} is used to describe groups of sections in
1718 the linked program. @code{@value{LD}} puts all partial programs' text
1719 sections in contiguous addresses in the linked program. It is
1720 customary to refer to the @emph{text section} of a program, meaning all
1721 the addresses of all partial program's text sections. Likewise for
1722 data and bss sections.
1724 Some sections are manipulated by @code{@value{LD}}; others are invented for
1725 use of @code{@value{AS}} and have no meaning except during assembly.
1728 @section @value{LD} Sections
1729 @code{@value{LD}} deals with just four kinds of sections, summarized below.
1734 @cindex named sections
1735 @cindex sections, named
1736 @item named sections
1739 @cindex text section
1740 @cindex data section
1744 These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as
1745 separate but equal sections. Anything you can say of one section is
1748 When the program is running, however, it is
1749 customary for the text section to be unalterable. The
1750 text section is often shared among processes: it will contain
1751 instructions, constants and the like. The data section of a running
1752 program is usually alterable: for example, C variables would be stored
1753 in the data section.
1758 This section contains zeroed bytes when your program begins running. It
1759 is used to hold unitialized variables or common storage. The length of
1760 each partial program's bss section is important, but because it starts
1761 out containing zeroed bytes there is no need to store explicit zero
1762 bytes in the object file. The bss section was invented to eliminate
1763 those explicit zeros from object files.
1765 @cindex absolute section
1766 @item absolute section
1767 Address 0 of this section is always ``relocated'' to runtime address 0.
1768 This is useful if you want to refer to an address that @code{@value{LD}} must
1769 not change when relocating. In this sense we speak of absolute
1770 addresses being ``unrelocatable'': they don't change during relocation.
1772 @cindex undefined section
1773 @item undefined section
1774 This ``section'' is a catch-all for address references to objects not in
1775 the preceding sections.
1776 @c FIXME: ref to some other doc on obj-file formats could go here.
1779 @cindex relocation example
1780 An idealized example of three relocatable sections follows.
1782 The example uses the traditional section names @samp{.text} and @samp{.data}.
1784 Memory addresses are on the horizontal axis.
1788 @c END TEXI2ROFF-KILL
1791 partial program # 1: |ttttt|dddd|00|
1798 partial program # 2: |TTT|DDD|000|
1801 +--+---+-----+--+----+---+-----+~~
1802 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1803 +--+---+-----+--+----+---+-----+~~
1805 addresses: 0 @dots{}
1809 @c FIXME make sure no page breaks inside figure!!
1812 \line{\it Partial program \#1: \hfil}
1813 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1814 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1816 \line{\it Partial program \#2: \hfil}
1817 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1818 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1820 \line{\it linked program: \hfil}
1821 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1822 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1823 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1824 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1826 \line{\it addresses: \hfil}
1830 @c END TEXI2ROFF-KILL
1833 @section @value{AS} Internal Sections
1835 @cindex internal @code{@value{AS}} sections
1836 @cindex sections in messages, internal
1837 These sections are meant only for the internal use of @code{@value{AS}}. They
1838 have no meaning at run-time. You don't really need to know about these
1839 sections for most purposes; but they can be mentioned in @code{@value{AS}}
1840 warning messages, so it might be helpful to have an idea of their
1841 meanings to @code{@value{AS}}. These sections are used to permit the
1842 value of every expression in your assembly language program to be a
1843 section-relative address.
1846 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
1847 @cindex assembler internal logic error
1848 An internal assembler logic error has been found. This means there is a
1849 bug in the assembler.
1852 @cindex expr (internal section)
1853 The assembler stores complex expression internally as combinations of
1854 symbols. When it needs to represent an expression as a symbol, it puts
1855 it in the expr section.
1857 @c FIXME item transfer[t] vector preload
1858 @c FIXME item transfer[t] vector postload
1859 @c FIXME item register
1863 @section Sub-Sections
1865 @cindex numbered subsections
1866 @cindex grouping data
1872 fall into two sections: text and data.
1874 You may have separate groups of
1876 data in named sections
1880 data in named sections
1886 that you want to end up near to each other in the object file, even
1887 though they are not contiguous in the assembler source.
1888 @code{@value{AS}} allows you to use @dfn{subsections} for this purpose.
1889 Within each section, there can be numbered subsections with values from
1890 0 to 8192. Objects assembled into the same subsection will be grouped
1891 with other objects in the same subsection when they are all put into the
1892 object file. For example, a compiler might want to store constants in
1893 the text section, but might not want to have them interspersed with the
1894 program being assembled. In this case, the compiler could issue a
1895 @samp{.text 0} before each section of code being output, and a
1896 @samp{.text 1} before each group of constants being output.
1898 Subsections are optional. If you don't use subsections, everything
1899 will be stored in subsection number zero.
1902 Each subsection is zero-padded up to a multiple of four bytes.
1903 (Subsections may be padded a different amount on different flavors
1904 of @code{@value{AS}}.)
1908 On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
1909 boundary (two bytes).
1910 The same is true on the Hitachi SH.
1913 @c FIXME section padding (alignment)?
1914 @c Rich Pixley says padding here depends on target obj code format; that
1915 @c doesn't seem particularly useful to say without further elaboration,
1916 @c so for now I say nothing about it. If this is a generic BFD issue,
1917 @c these paragraphs might need to vanish from this manual, and be
1918 @c discussed in BFD chapter of binutils (or some such).
1921 On the AMD 29K family, no particular padding is added to section or
1922 subsection sizes; @value{AS} forces no alignment on this platform.
1926 Subsections appear in your object file in numeric order, lowest numbered
1927 to highest. (All this to be compatible with other people's assemblers.)
1928 The object file contains no representation of subsections; @code{@value{LD}} and
1929 other programs that manipulate object files will see no trace of them.
1930 They just see all your text subsections as a text section, and all your
1931 data subsections as a data section.
1933 To specify which subsection you want subsequent statements assembled
1934 into, use a numeric argument to specify it, in a @samp{.text
1935 @var{expression}} or a @samp{.data @var{expression}} statement.
1938 When generating COFF output, you
1943 can also use an extra subsection
1944 argument with arbitrary named sections: @samp{.section @var{name},
1947 @var{Expression} should be an absolute expression.
1948 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
1949 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
1950 begins in @code{text 0}. For instance:
1952 .text 0 # The default subsection is text 0 anyway.
1953 .ascii "This lives in the first text subsection. *"
1955 .ascii "But this lives in the second text subsection."
1957 .ascii "This lives in the data section,"
1958 .ascii "in the first data subsection."
1960 .ascii "This lives in the first text section,"
1961 .ascii "immediately following the asterisk (*)."
1964 Each section has a @dfn{location counter} incremented by one for every
1965 byte assembled into that section. Because subsections are merely a
1966 convenience restricted to @code{@value{AS}} there is no concept of a subsection
1967 location counter. There is no way to directly manipulate a location
1968 counter---but the @code{.align} directive will change it, and any label
1969 definition will capture its current value. The location counter of the
1970 section that statements are being assembled into is said to be the
1971 @dfn{active} location counter.
1974 @section bss Section
1977 @cindex common variable storage
1978 The bss section is used for local common variable storage.
1979 You may allocate address space in the bss section, but you may
1980 not dictate data to load into it before your program executes. When
1981 your program starts running, all the contents of the bss
1982 section are zeroed bytes.
1984 Addresses in the bss section are allocated with special directives; you
1985 may not assemble anything directly into the bss section. Hence there
1986 are no bss subsections. @xref{Comm,,@code{.comm}},
1987 @pxref{Lcomm,,@code{.lcomm}}.
1993 Symbols are a central concept: the programmer uses symbols to name
1994 things, the linker uses symbols to link, and the debugger uses symbols
1998 @cindex debuggers, and symbol order
1999 @emph{Warning:} @code{@value{AS}} does not place symbols in the object file in
2000 the same order they were declared. This may break some debuggers.
2005 * Setting Symbols:: Giving Symbols Other Values
2006 * Symbol Names:: Symbol Names
2007 * Dot:: The Special Dot Symbol
2008 * Symbol Attributes:: Symbol Attributes
2015 A @dfn{label} is written as a symbol immediately followed by a colon
2016 @samp{:}. The symbol then represents the current value of the
2017 active location counter, and is, for example, a suitable instruction
2018 operand. You are warned if you use the same symbol to represent two
2019 different locations: the first definition overrides any other
2023 On the HPPA, a @dfn{label} need not be immediately followed by a colon,
2024 but instead must start in column zero. Only one @dfn{label} may be
2025 defined on a single line.
2028 @node Setting Symbols
2029 @section Giving Symbols Other Values
2031 @cindex assigning values to symbols
2032 @cindex symbol values, assigning
2033 A symbol can be given an arbitrary value by writing a symbol, followed
2034 by an equals sign @samp{=}, followed by an expression
2035 (@pxref{Expressions}). This is equivalent to using the @code{.set}
2036 directive. @xref{Set,,@code{.set}}.
2039 @section Symbol Names
2041 @cindex symbol names
2042 @cindex names, symbol
2043 @ifclear SPECIAL-SYMS
2044 Symbol names begin with a letter or with one of @samp{._}. On most
2045 machines, you can also use @code{$} in symbol names; exceptions are
2046 noted in @ref{Machine Dependencies}. That character may be followed by any
2047 string of digits, letters, dollar signs (unless otherwise noted in
2048 @ref{Machine Dependencies}), and underscores.
2051 For the AMD 29K family, @samp{?} is also allowed in the
2052 body of a symbol name, though not at its beginning.
2057 Symbol names begin with a letter or with one of @samp{._}. On the
2059 H8/500, you can also use @code{$} in symbol names. That character may
2060 be followed by any string of digits, letters, dollar signs (save on the
2061 H8/300), and underscores.
2065 Case of letters is significant: @code{foo} is a different symbol name
2068 Each symbol has exactly one name. Each name in an assembly language
2069 program refers to exactly one symbol. You may use that symbol name any
2070 number of times in a program.
2072 @subheading Local Symbol Names
2074 @cindex local symbol names
2075 @cindex symbol names, local
2076 @cindex temporary symbol names
2077 @cindex symbol names, temporary
2078 Local symbols help compilers and programmers use names temporarily.
2079 There are ten local symbol names, which are re-used throughout the
2080 program. You may refer to them using the names @samp{0} @samp{1}
2081 @dots{} @samp{9}. To define a local symbol, write a label of the form
2082 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
2083 recent previous definition of that symbol write @samp{@b{N}b}, using the
2084 same digit as when you defined the label. To refer to the next
2085 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
2086 a choice of 10 forward references. The @samp{b} stands for
2087 ``backwards'' and the @samp{f} stands for ``forwards''.
2089 Local symbols are not emitted by the current GNU C compiler.
2091 There is no restriction on how you can use these labels, but
2092 remember that at any point in the assembly you can refer to at most
2093 10 prior local labels and to at most 10 forward local labels.
2095 Local symbol names are only a notation device. They are immediately
2096 transformed into more conventional symbol names before the assembler
2097 uses them. The symbol names stored in the symbol table, appearing in
2098 error messages and optionally emitted to the object file have these
2103 All local labels begin with @samp{L}. Normally both @code{@value{AS}} and
2104 @code{@value{LD}} forget symbols that start with @samp{L}. These labels are
2105 used for symbols you are never intended to see. If you give the
2106 @samp{-L} option then @code{@value{AS}} will retain these symbols in the
2107 object file. If you also instruct @code{@value{LD}} to retain these symbols,
2108 you may use them in debugging.
2111 If the label is written @samp{0:} then the digit is @samp{0}.
2112 If the label is written @samp{1:} then the digit is @samp{1}.
2113 And so on up through @samp{9:}.
2116 This unusual character is included so you don't accidentally invent
2117 a symbol of the same name. The character has ASCII value
2120 @item @emph{ordinal number}
2121 This is a serial number to keep the labels distinct. The first
2122 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
2123 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
2127 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
2128 @code{3:} is named @code{L3@ctrl{A}44}.
2131 @section The Special Dot Symbol
2133 @cindex dot (symbol)
2134 @cindex @code{.} (symbol)
2135 @cindex current address
2136 @cindex location counter
2137 The special symbol @samp{.} refers to the current address that
2138 @code{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
2139 .long .} will cause @code{melvin} to contain its own address.
2140 Assigning a value to @code{.} is treated the same as a @code{.org}
2141 directive. Thus, the expression @samp{.=.+4} is the same as saying
2142 @ifclear no-space-dir
2151 @node Symbol Attributes
2152 @section Symbol Attributes
2154 @cindex symbol attributes
2155 @cindex attributes, symbol
2156 Every symbol has, as well as its name, the attributes ``Value'' and
2157 ``Type''. Depending on output format, symbols can also have auxiliary
2160 The detailed definitions are in @file{a.out.h}.
2163 If you use a symbol without defining it, @code{@value{AS}} assumes zero for
2164 all these attributes, and probably won't warn you. This makes the
2165 symbol an externally defined symbol, which is generally what you
2169 * Symbol Value:: Value
2170 * Symbol Type:: Type
2173 * a.out Symbols:: Symbol Attributes: @code{a.out}
2177 * a.out Symbols:: Symbol Attributes: @code{a.out}
2180 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
2185 * COFF Symbols:: Symbol Attributes for COFF
2188 * SOM Symbols:: Symbol Attributes for SOM
2195 @cindex value of a symbol
2196 @cindex symbol value
2197 The value of a symbol is (usually) 32 bits. For a symbol which labels a
2198 location in the text, data, bss or absolute sections the value is the
2199 number of addresses from the start of that section to the label.
2200 Naturally for text, data and bss sections the value of a symbol changes
2201 as @code{@value{LD}} changes section base addresses during linking. Absolute
2202 symbols' values do not change during linking: that is why they are
2205 The value of an undefined symbol is treated in a special way. If it is
2206 0 then the symbol is not defined in this assembler source program, and
2207 @code{@value{LD}} will try to determine its value from other programs it is
2208 linked with. You make this kind of symbol simply by mentioning a symbol
2209 name without defining it. A non-zero value represents a @code{.comm}
2210 common declaration. The value is how much common storage to reserve, in
2211 bytes (addresses). The symbol refers to the first address of the
2217 @cindex type of a symbol
2219 The type attribute of a symbol contains relocation (section)
2220 information, any flag settings indicating that a symbol is external, and
2221 (optionally), other information for linkers and debuggers. The exact
2222 format depends on the object-code output format in use.
2227 @c The following avoids a "widow" subsection title. @group would be
2228 @c better if it were available outside examples.
2231 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
2233 @cindex @code{b.out} symbol attributes
2234 @cindex symbol attributes, @code{b.out}
2235 These symbol attributes appear only when @code{@value{AS}} is configured for
2236 one of the Berkeley-descended object output formats---@code{a.out} or
2242 @subsection Symbol Attributes: @code{a.out}
2244 @cindex @code{a.out} symbol attributes
2245 @cindex symbol attributes, @code{a.out}
2251 @subsection Symbol Attributes: @code{a.out}
2253 @cindex @code{a.out} symbol attributes
2254 @cindex symbol attributes, @code{a.out}
2258 * Symbol Desc:: Descriptor
2259 * Symbol Other:: Other
2263 @subsubsection Descriptor
2265 @cindex descriptor, of @code{a.out} symbol
2266 This is an arbitrary 16-bit value. You may establish a symbol's
2267 descriptor value by using a @code{.desc} statement
2268 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
2272 @subsubsection Other
2274 @cindex other attribute, of @code{a.out} symbol
2275 This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}.
2280 @subsection Symbol Attributes for COFF
2282 @cindex COFF symbol attributes
2283 @cindex symbol attributes, COFF
2285 The COFF format supports a multitude of auxiliary symbol attributes;
2286 like the primary symbol attributes, they are set between @code{.def} and
2287 @code{.endef} directives.
2289 @subsubsection Primary Attributes
2291 @cindex primary attributes, COFF symbols
2292 The symbol name is set with @code{.def}; the value and type,
2293 respectively, with @code{.val} and @code{.type}.
2295 @subsubsection Auxiliary Attributes
2297 @cindex auxiliary attributes, COFF symbols
2298 The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
2299 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2300 information for COFF.
2305 @subsection Symbol Attributes for SOM
2307 @cindex SOM symbol attributes
2308 @cindex symbol attributes, SOM
2310 The SOM format supports a multitude of symbol attributes set with the
2311 with the @code{.EXPORT} and @code{.IMPORT} directives.
2313 The attributes are described in @cite{HP9000 Series 800 Assembly
2314 Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
2315 @code{EXPORT} assembler directive documentation.
2319 @chapter Expressions
2323 @cindex numeric values
2324 An @dfn{expression} specifies an address or numeric value.
2325 Whitespace may precede and/or follow an expression.
2328 * Empty Exprs:: Empty Expressions
2329 * Integer Exprs:: Integer Expressions
2333 @section Empty Expressions
2335 @cindex empty expressions
2336 @cindex expressions, empty
2337 An empty expression has no value: it is just whitespace or null.
2338 Wherever an absolute expression is required, you may omit the
2339 expression and @code{@value{AS}} will assume a value of (absolute) 0. This
2340 is compatible with other assemblers.
2343 @section Integer Expressions
2345 @cindex integer expressions
2346 @cindex expressions, integer
2347 An @dfn{integer expression} is one or more @emph{arguments} delimited
2348 by @emph{operators}.
2351 * Arguments:: Arguments
2352 * Operators:: Operators
2353 * Prefix Ops:: Prefix Operators
2354 * Infix Ops:: Infix Operators
2358 @subsection Arguments
2360 @cindex expression arguments
2361 @cindex arguments in expressions
2362 @cindex operands in expressions
2363 @cindex arithmetic operands
2364 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2365 contexts arguments are sometimes called ``arithmetic operands''. In
2366 this manual, to avoid confusing them with the ``instruction operands'' of
2367 the machine language, we use the term ``argument'' to refer to parts of
2368 expressions only, reserving the word ``operand'' to refer only to machine
2369 instruction operands.
2371 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2372 @var{section} is one of text, data, bss, absolute,
2373 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2376 Numbers are usually integers.
2378 A number can be a flonum or bignum. In this case, you are warned
2379 that only the low order 32 bits are used, and @code{@value{AS}} pretends
2380 these 32 bits are an integer. You may write integer-manipulating
2381 instructions that act on exotic constants, compatible with other
2384 @cindex subexpressions
2385 Subexpressions are a left parenthesis @samp{(} followed by an integer
2386 expression, followed by a right parenthesis @samp{)}; or a prefix
2387 operator followed by an argument.
2390 @subsection Operators
2392 @cindex operators, in expressions
2393 @cindex arithmetic functions
2394 @cindex functions, in expressions
2395 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2396 operators are followed by an argument. Infix operators appear
2397 between their arguments. Operators may be preceded and/or followed by
2401 @subsection Prefix Operator
2403 @cindex prefix operators
2404 @code{@value{AS}} has the following @dfn{prefix operators}. They each take
2405 one argument, which must be absolute.
2407 @c the tex/end tex stuff surrounding this small table is meant to make
2408 @c it align, on the printed page, with the similar table in the next
2409 @c section (which is inside an enumerate).
2411 \global\advance\leftskip by \itemindent
2416 @dfn{Negation}. Two's complement negation.
2418 @dfn{Complementation}. Bitwise not.
2422 \global\advance\leftskip by -\itemindent
2426 @subsection Infix Operators
2428 @cindex infix operators
2429 @cindex operators, permitted arguments
2430 @dfn{Infix operators} take two arguments, one on either side. Operators
2431 have precedence, but operations with equal precedence are performed left
2432 to right. Apart from @code{+} or @code{-}, both arguments must be
2433 absolute, and the result is absolute.
2436 @cindex operator precedence
2437 @cindex precedence of operators
2444 @dfn{Multiplication}.
2447 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2454 @dfn{Shift Left}. Same as the C operator @samp{<<}.
2458 @dfn{Shift Right}. Same as the C operator @samp{>>}.
2462 Intermediate precedence
2467 @dfn{Bitwise Inclusive Or}.
2473 @dfn{Bitwise Exclusive Or}.
2476 @dfn{Bitwise Or Not}.
2484 @cindex addition, permitted arguments
2485 @cindex plus, permitted arguments
2486 @cindex arguments for addition
2487 @dfn{Addition}. If either argument is absolute, the result
2488 has the section of the other argument.
2489 If either argument is pass1 or undefined, the result is pass1.
2490 Otherwise @code{+} is illegal.
2493 @cindex subtraction, permitted arguments
2494 @cindex minus, permitted arguments
2495 @cindex arguments for subtraction
2496 @dfn{Subtraction}. If the right argument is absolute, the
2497 result has the section of the left argument.
2498 If either argument is pass1 the result is pass1.
2499 If either argument is undefined the result is difference section.
2500 If both arguments are in the same section, the result is absolute---provided
2501 that section is one of text, data or bss.
2502 Otherwise subtraction is illegal.
2506 The sense of the rule for addition is that it's only meaningful to add
2507 the @emph{offsets} in an address; you can only have a defined section in
2508 one of the two arguments.
2510 Similarly, you can't subtract quantities from two different sections.
2513 @chapter Assembler Directives
2515 @cindex directives, machine independent
2516 @cindex pseudo-ops, machine independent
2517 @cindex machine independent directives
2518 All assembler directives have names that begin with a period (@samp{.}).
2519 The rest of the name is letters, usually in lower case.
2521 This chapter discusses directives that are available regardless of the
2522 target machine configuration for the GNU assembler.
2524 Some machine configurations provide additional directives.
2525 @xref{Machine Dependencies}.
2528 @ifset machine-directives
2529 @xref{Machine Dependencies} for additional directives.
2534 * Abort:: @code{.abort}
2536 * ABORT:: @code{.ABORT}
2539 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2540 * App-File:: @code{.app-file @var{string}}
2541 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2542 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2543 * Byte:: @code{.byte @var{expressions}}
2544 * Comm:: @code{.comm @var{symbol} , @var{length} }
2545 * Data:: @code{.data @var{subsection}}
2547 * Def:: @code{.def @var{name}}
2550 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2556 * Double:: @code{.double @var{flonums}}
2557 * Eject:: @code{.eject}
2558 * Else:: @code{.else}
2560 * Endef:: @code{.endef}
2563 * Endif:: @code{.endif}
2564 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2565 * Extern:: @code{.extern}
2566 @ifclear no-file-dir
2567 * File:: @code{.file @var{string}}
2570 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2571 * Float:: @code{.float @var{flonums}}
2572 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2573 * hword:: @code{.hword @var{expressions}}
2574 * Ident:: @code{.ident}
2575 * If:: @code{.if @var{absolute expression}}
2576 * Include:: @code{.include "@var{file}"}
2577 * Int:: @code{.int @var{expressions}}
2578 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2579 * Lflags:: @code{.lflags}
2580 @ifclear no-line-dir
2581 * Line:: @code{.line @var{line-number}}
2584 * Ln:: @code{.ln @var{line-number}}
2585 * List:: @code{.list}
2586 * Long:: @code{.long @var{expressions}}
2588 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2591 * Nolist:: @code{.nolist}
2592 * Octa:: @code{.octa @var{bignums}}
2593 * Org:: @code{.org @var{new-lc} , @var{fill}}
2594 * Psize:: @code{.psize @var{lines}, @var{columns}}
2595 * Quad:: @code{.quad @var{bignums}}
2596 * Sbttl:: @code{.sbttl "@var{subheading}"}
2598 * Scl:: @code{.scl @var{class}}
2601 * Section:: @code{.section @var{name}, @var{subsection}}
2604 * Set:: @code{.set @var{symbol}, @var{expression}}
2605 * Short:: @code{.short @var{expressions}}
2606 * Single:: @code{.single @var{flonums}}
2608 * Size:: @code{.size}
2611 * Space:: @code{.space @var{size} , @var{fill}}
2613 * Stab:: @code{.stabd, .stabn, .stabs}
2616 * Tag:: @code{.tag @var{structname}}
2619 * Text:: @code{.text @var{subsection}}
2620 * Title:: @code{.title "@var{heading}"}
2622 * Type:: @code{.type @var{int}}
2623 * Val:: @code{.val @var{addr}}
2626 * Word:: @code{.word @var{expressions}}
2627 * Deprecated:: Deprecated Directives
2631 @section @code{.abort}
2633 @cindex @code{abort} directive
2634 @cindex stopping the assembly
2635 This directive stops the assembly immediately. It is for
2636 compatibility with other assemblers. The original idea was that the
2637 assembly language source would be piped into the assembler. If the sender
2638 of the source quit, it could use this directive tells @code{@value{AS}} to
2639 quit also. One day @code{.abort} will not be supported.
2643 @section @code{.ABORT}
2645 @cindex @code{ABORT} directive
2646 When producing COFF output, @code{@value{AS}} accepts this directive as a
2647 synonym for @samp{.abort}.
2650 When producing @code{b.out} output, @code{@value{AS}} accepts this directive,
2656 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2658 @cindex padding the location counter
2659 @cindex @code{align} directive
2660 Pad the location counter (in the current subsection) to a particular
2661 storage boundary. The first expression (which must be absolute) is the
2662 number of low-order zero bits the location counter will have after
2663 advancement. For example @samp{.align 3} will advance the location
2664 counter until it a multiple of 8. If the location counter is already a
2665 multiple of 8, no change is needed.
2668 For the HPPA, the first expression (which must be absolute) is the
2669 alignment request in bytes. For example @samp{.align 8} will advance
2670 the location counter until it is a multiple of 8. If the location counter
2671 is already a multiple of 8, no change is needed.
2674 The second expression (also absolute) gives the value to be stored in
2675 the padding bytes. It (and the comma) may be omitted. If it is
2676 omitted, the padding bytes are zero.
2679 @section @code{.app-file @var{string}}
2681 @cindex logical file name
2682 @cindex file name, logical
2683 @cindex @code{app-file} directive
2685 @ifclear no-file-dir
2686 (which may also be spelled @samp{.file})
2688 tells @code{@value{AS}} that we are about to start a new
2689 logical file. @var{string} is the new file name. In general, the
2690 filename is recognized whether or not it is surrounded by quotes @samp{"};
2691 but if you wish to specify an empty file name is permitted,
2692 you must give the quotes--@code{""}. This statement may go away in
2693 future: it is only recognized to be compatible with old @code{@value{AS}}
2697 @section @code{.ascii "@var{string}"}@dots{}
2699 @cindex @code{ascii} directive
2700 @cindex string literals
2701 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2702 separated by commas. It assembles each string (with no automatic
2703 trailing zero byte) into consecutive addresses.
2706 @section @code{.asciz "@var{string}"}@dots{}
2708 @cindex @code{asciz} directive
2709 @cindex zero-terminated strings
2710 @cindex null-terminated strings
2711 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2712 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2715 @section @code{.byte @var{expressions}}
2717 @cindex @code{byte} directive
2718 @cindex integers, one byte
2719 @code{.byte} expects zero or more expressions, separated by commas.
2720 Each expression is assembled into the next byte.
2723 @section @code{.comm @var{symbol} , @var{length} }
2725 @cindex @code{comm} directive
2726 @cindex symbol, common
2727 @code{.comm} declares a named common area in the bss section. Normally
2728 @code{@value{LD}} reserves memory addresses for it during linking, so no partial
2729 program defines the location of the symbol. Use @code{.comm} to tell
2730 @code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}}
2731 will allocate space for each @code{.comm} symbol that is at least as
2732 long as the longest @code{.comm} request in any of the partial programs
2733 linked. @var{length} is an absolute expression.
2736 The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
2737 @samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
2741 @section @code{.data @var{subsection}}
2743 @cindex @code{data} directive
2744 @code{.data} tells @code{@value{AS}} to assemble the following statements onto the
2745 end of the data subsection numbered @var{subsection} (which is an
2746 absolute expression). If @var{subsection} is omitted, it defaults
2751 @section @code{.def @var{name}}
2753 @cindex @code{def} directive
2754 @cindex COFF symbols, debugging
2755 @cindex debugging COFF symbols
2756 Begin defining debugging information for a symbol @var{name}; the
2757 definition extends until the @code{.endef} directive is encountered.
2760 This directive is only observed when @code{@value{AS}} is configured for COFF
2761 format output; when producing @code{b.out}, @samp{.def} is recognized,
2768 @section @code{.desc @var{symbol}, @var{abs-expression}}
2770 @cindex @code{desc} directive
2771 @cindex COFF symbol descriptor
2772 @cindex symbol descriptor, COFF
2773 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2774 to the low 16 bits of an absolute expression.
2777 The @samp{.desc} directive is not available when @code{@value{AS}} is
2778 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2779 object format. For the sake of compatibility, @code{@value{AS}} will accept
2780 it, but produce no output, when configured for COFF.
2786 @section @code{.dim}
2788 @cindex @code{dim} directive
2789 @cindex COFF auxiliary symbol information
2790 @cindex auxiliary symbol information, COFF
2791 This directive is generated by compilers to include auxiliary debugging
2792 information in the symbol table. It is only permitted inside
2793 @code{.def}/@code{.endef} pairs.
2796 @samp{.dim} is only meaningful when generating COFF format output; when
2797 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
2803 @section @code{.double @var{flonums}}
2805 @cindex @code{double} directive
2806 @cindex floating point numbers (double)
2807 @code{.double} expects zero or more flonums, separated by commas. It
2808 assembles floating point numbers.
2810 The exact kind of floating point numbers emitted depends on how
2811 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
2815 On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
2816 in @sc{ieee} format.
2821 @section @code{.eject}
2823 @cindex @code{eject} directive
2824 @cindex new page, in listings
2825 @cindex page, in listings
2826 @cindex listing control: new page
2827 Force a page break at this point, when generating assembly listings.
2830 @section @code{.else}
2832 @cindex @code{else} directive
2833 @code{.else} is part of the @code{@value{AS}} support for conditional
2834 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2835 of code to be assembled if the condition for the preceding @code{.if}
2839 @node End, Endef, Else, Pseudo Ops
2840 @section @code{.end}
2842 @cindex @code{end} directive
2843 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2844 meant to do something eventually (which is why it isn't documented here
2845 as "for compatibility with blah").
2850 @section @code{.endef}
2852 @cindex @code{endef} directive
2853 This directive flags the end of a symbol definition begun with
2857 @samp{.endef} is only meaningful when generating COFF format output; if
2858 @code{@value{AS}} is configured to generate @code{b.out}, it accepts this
2859 directive but ignores it.
2864 @section @code{.endif}
2866 @cindex @code{endif} directive
2867 @code{.endif} is part of the @code{@value{AS}} support for conditional assembly;
2868 it marks the end of a block of code that is only assembled
2869 conditionally. @xref{If,,@code{.if}}.
2872 @section @code{.equ @var{symbol}, @var{expression}}
2874 @cindex @code{equ} directive
2875 @cindex assigning values to symbols
2876 @cindex symbols, assigning values to
2877 This directive sets the value of @var{symbol} to @var{expression}.
2878 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
2881 The syntax for @code{equ} on the HPPA is
2882 @samp{@var{symbol} .equ @var{expression}}.
2886 @section @code{.extern}
2888 @cindex @code{extern} directive
2889 @code{.extern} is accepted in the source program---for compatibility
2890 with other assemblers---but it is ignored. @code{@value{AS}} treats
2891 all undefined symbols as external.
2893 @ifclear no-file-dir
2895 @section @code{.file @var{string}}
2897 @cindex @code{file} directive
2898 @cindex logical file name
2899 @cindex file name, logical
2900 @code{.file} (which may also be spelled @samp{.app-file}) tells
2901 @code{@value{AS}} that we are about to start a new logical file.
2902 @var{string} is the new file name. In general, the filename is
2903 recognized whether or not it is surrounded by quotes @samp{"}; but if
2904 you wish to specify an empty file name, you must give the
2905 quotes--@code{""}. This statement may go away in future: it is only
2906 recognized to be compatible with old @code{@value{AS}} programs.
2908 In some configurations of @code{@value{AS}}, @code{.file} has already been
2909 removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}.
2914 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
2916 @cindex @code{fill} directive
2917 @cindex writing patterns in memory
2918 @cindex patterns, writing in memory
2919 @var{result}, @var{size} and @var{value} are absolute expressions.
2920 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
2921 may be zero or more. @var{Size} may be zero or more, but if it is
2922 more than 8, then it is deemed to have the value 8, compatible with
2923 other people's assemblers. The contents of each @var{repeat} bytes
2924 is taken from an 8-byte number. The highest order 4 bytes are
2925 zero. The lowest order 4 bytes are @var{value} rendered in the
2926 byte-order of an integer on the computer @code{@value{AS}} is assembling for.
2927 Each @var{size} bytes in a repetition is taken from the lowest order
2928 @var{size} bytes of this number. Again, this bizarre behavior is
2929 compatible with other people's assemblers.
2931 @var{size} and @var{value} are optional.
2932 If the second comma and @var{value} are absent, @var{value} is
2933 assumed zero. If the first comma and following tokens are absent,
2934 @var{size} is assumed to be 1.
2937 @section @code{.float @var{flonums}}
2939 @cindex floating point numbers (single)
2940 @cindex @code{float} directive
2941 This directive assembles zero or more flonums, separated by commas. It
2942 has the same effect as @code{.single}.
2944 The exact kind of floating point numbers emitted depends on how
2945 @code{@value{AS}} is configured.
2946 @xref{Machine Dependencies}.
2950 On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
2951 in @sc{ieee} format.
2956 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2958 @cindex @code{global} directive
2959 @cindex symbol, making visible to linker
2960 @code{.global} makes the symbol visible to @code{@value{LD}}. If you define
2961 @var{symbol} in your partial program, its value is made available to
2962 other partial programs that are linked with it. Otherwise,
2963 @var{symbol} will take its attributes from a symbol of the same name
2964 from another partial program it is linked with.
2966 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
2967 compatibility with other assemblers.
2970 On the HPPA symbols are made visible to @code{@value{LD}} with the
2971 @code{.EXPORT} directive. Using @code{.EXPORT} is necessary to provide
2972 the linker with the correct symbol type information necessary for linking
2977 @section @code{.hword @var{expressions}}
2979 @cindex @code{hword} directive
2980 @cindex integers, 16-bit
2981 @cindex numbers, 16-bit
2982 @cindex sixteen bit integers
2983 This expects zero or more @var{expressions}, and emits
2984 a 16 bit number for each.
2987 This directive is a synonym for @samp{.short}; depending on the target
2988 architecture, it may also be a synonym for @samp{.word}.
2992 This directive is a synonym for @samp{.short}.
2995 This directive is a synonym for both @samp{.short} and @samp{.word}.
3000 @section @code{.ident}
3002 @cindex @code{ident} directive
3003 This directive is used by some assemblers to place tags in object files.
3004 @code{@value{AS}} simply accepts the directive for source-file
3005 compatibility with such assemblers, but does not actually emit anything
3009 @section @code{.if @var{absolute expression}}
3011 @cindex conditional assembly
3012 @cindex @code{if} directive
3013 @code{.if} marks the beginning of a section of code which is only
3014 considered part of the source program being assembled if the argument
3015 (which must be an @var{absolute expression}) is non-zero. The end of
3016 the conditional section of code must be marked by @code{.endif}
3017 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
3018 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
3020 The following variants of @code{.if} are also supported:
3022 @item .ifdef @var{symbol}
3023 @cindex @code{ifdef} directive
3024 Assembles the following section of code if the specified @var{symbol}
3029 @cindex @code{ifeqs} directive
3030 Not yet implemented.
3033 @item .ifndef @var{symbol}
3034 @itemx ifnotdef @var{symbol}
3035 @cindex @code{ifndef} directive
3036 @cindex @code{ifnotdef} directive
3037 Assembles the following section of code if the specified @var{symbol}
3038 has not been defined. Both spelling variants are equivalent.
3042 Not yet implemented.
3047 @section @code{.include "@var{file}"}
3049 @cindex @code{include} directive
3050 @cindex supporting files, including
3051 @cindex files, including
3052 This directive provides a way to include supporting files at specified
3053 points in your source program. The code from @var{file} is assembled as
3054 if it followed the point of the @code{.include}; when the end of the
3055 included file is reached, assembly of the original file continues. You
3056 can control the search paths used with the @samp{-I} command-line option
3057 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
3061 @section @code{.int @var{expressions}}
3063 @cindex @code{int} directive
3065 @cindex integers, 32-bit
3066 Expect zero or more @var{expressions}, of any section, separated by
3067 commas. For each expression, emit a 32-bit
3071 @cindex integers, 32-bit
3072 Expect zero or more @var{expressions}, of any section, separated by
3073 commas. For each expression, emit a 32-bit
3077 Expect zero or more @var{expressions}, of any section, separated by
3078 commas. For each expression, emit a
3081 number that will, at run time, be the value of that expression. The
3082 byte order of the expression depends on what kind of computer will run
3087 On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
3088 integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits
3094 @section @code{.lcomm @var{symbol} , @var{length}}
3096 @cindex @code{lcomm} directive
3097 @cindex local common symbols
3098 @cindex symbols, local common
3099 Reserve @var{length} (an absolute expression) bytes for a local common
3100 denoted by @var{symbol}. The section and value of @var{symbol} are
3101 those of the new local common. The addresses are allocated in the bss
3102 section, so at run-time the bytes will start off zeroed. @var{Symbol}
3103 is not declared global (@pxref{Global,,@code{.global}}), so is normally
3104 not visible to @code{@value{LD}}.
3107 The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
3108 @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
3112 @section @code{.lflags}
3114 @cindex @code{lflags} directive (ignored)
3115 @code{@value{AS}} accepts this directive, for compatibility with other
3116 assemblers, but ignores it.
3118 @ifclear no-line-dir
3120 @section @code{.line @var{line-number}}
3122 @cindex @code{line} directive
3126 @section @code{.ln @var{line-number}}
3128 @cindex @code{ln} directive
3130 @cindex logical line number
3132 Tell @code{@value{AS}} to change the logical line number. @var{line-number} must be
3133 an absolute expression. The next line will have that logical line
3134 number. So any other statements on the current line (after a statement
3135 separator character)
3136 will be reported as on logical line number
3137 @var{line-number} @minus{} 1.
3138 One day this directive will be unsupported: it is used only
3139 for compatibility with existing assembler programs.
3143 @emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
3144 only available with the name @code{.ln}, rather than as either
3145 @code{.line} or @code{.ln}.
3150 @ifclear no-line-dir
3151 Even though this is a directive associated with the @code{a.out} or
3152 @code{b.out} object-code formats, @code{@value{AS}} will still recognize it
3153 when producing COFF output, and will treat @samp{.line} as though it
3154 were the COFF @samp{.ln} @emph{if} it is found outside a
3155 @code{.def}/@code{.endef} pair.
3157 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
3158 used by compilers to generate auxiliary symbol information for
3163 @section @code{.ln @var{line-number}}
3165 @cindex @code{ln} directive
3166 @ifclear no-line-dir
3167 @samp{.ln} is a synonym for @samp{.line}.
3170 Tell @code{@value{AS}} to change the logical line number. @var{line-number}
3171 must be an absolute expression. The next line will have that logical
3172 line number, so any other statements on the current line (after a
3173 statement separator character @code{;}) will be reported as on logical
3174 line number @var{line-number} @minus{} 1.
3177 This directive is accepted, but ignored, when @code{@value{AS}} is
3178 configured for @code{b.out}; its effect is only associated with COFF
3184 @section @code{.list}
3186 @cindex @code{list} directive
3187 @cindex listing control, turning on
3188 Control (in conjunction with the @code{.nolist} directive) whether or
3189 not assembly listings are generated. These two directives maintain an
3190 internal counter (which is zero initially). @code{.list} increments the
3191 counter, and @code{.nolist} decrements it. Assembly listings are
3192 generated whenever the counter is greater than zero.
3194 By default, listings are disabled. When you enable them (with the
3195 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
3196 the initial value of the listing counter is one.
3199 @section @code{.long @var{expressions}}
3201 @cindex @code{long} directive
3202 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
3205 @c no one seems to know what this is for or whether this description is
3206 @c what it really ought to do
3208 @section @code{.lsym @var{symbol}, @var{expression}}
3210 @cindex @code{lsym} directive
3211 @cindex symbol, not referenced in assembly
3212 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
3213 the hash table, ensuring it cannot be referenced by name during the
3214 rest of the assembly. This sets the attributes of the symbol to be
3215 the same as the expression value:
3217 @var{other} = @var{descriptor} = 0
3218 @var{type} = @r{(section of @var{expression})}
3219 @var{value} = @var{expression}
3222 The new symbol is not flagged as external.
3226 @section @code{.nolist}
3228 @cindex @code{nolist} directive
3229 @cindex listing control, turning off
3230 Control (in conjunction with the @code{.list} directive) whether or
3231 not assembly listings are generated. These two directives maintain an
3232 internal counter (which is zero initially). @code{.list} increments the
3233 counter, and @code{.nolist} decrements it. Assembly listings are
3234 generated whenever the counter is greater than zero.
3237 @section @code{.octa @var{bignums}}
3239 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
3240 @cindex @code{octa} directive
3241 @cindex integer, 16-byte
3242 @cindex sixteen byte integer
3243 This directive expects zero or more bignums, separated by commas. For each
3244 bignum, it emits a 16-byte integer.
3246 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
3247 hence @emph{octa}-word for 16 bytes.
3250 @section @code{.org @var{new-lc} , @var{fill}}
3252 @cindex @code{org} directive
3253 @cindex location counter, advancing
3254 @cindex advancing location counter
3255 @cindex current address, advancing
3256 @code{.org} will advance the location counter of the current section to
3257 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3258 expression with the same section as the current subsection. That is,
3259 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3260 wrong section, the @code{.org} directive is ignored. To be compatible
3261 with former assemblers, if the section of @var{new-lc} is absolute,
3262 @code{@value{AS}} will issue a warning, then pretend the section of @var{new-lc}
3263 is the same as the current subsection.
3265 @code{.org} may only increase the location counter, or leave it
3266 unchanged; you cannot use @code{.org} to move the location counter
3269 @c double negative used below "not undefined" because this is a specific
3270 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3271 @c section. pesch@cygnus.com 18feb91
3272 Because @code{@value{AS}} tries to assemble programs in one pass @var{new-lc}
3273 may not be undefined. If you really detest this restriction we eagerly await
3274 a chance to share your improved assembler.
3276 Beware that the origin is relative to the start of the section, not
3277 to the start of the subsection. This is compatible with other
3278 people's assemblers.
3280 When the location counter (of the current subsection) is advanced, the
3281 intervening bytes are filled with @var{fill} which should be an
3282 absolute expression. If the comma and @var{fill} are omitted,
3283 @var{fill} defaults to zero.
3286 @section @code{.psize @var{lines} , @var{columns}}
3288 @cindex @code{psize} directive
3289 @cindex listing control: paper size
3290 @cindex paper size, for listings
3291 Use this directive to declare the number of lines---and, optionally, the
3292 number of columns---to use for each page, when generating listings.
3294 If you don't use @code{.psize}, listings will use a default line-count
3295 of 60. You may omit the comma and @var{columns} specification; the
3296 default width is 200 columns.
3298 @code{@value{AS}} will generate formfeeds whenever the specified number of
3299 lines is exceeded (or whenever you explicitly request one, using
3302 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3303 those explicitly specified with @code{.eject}.
3306 @section @code{.quad @var{bignums}}
3308 @cindex @code{quad} directive
3309 @code{.quad} expects zero or more bignums, separated by commas. For
3310 each bignum, it emits
3312 an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
3313 warning message; and just takes the lowest order 8 bytes of the bignum.
3314 @cindex eight-byte integer
3315 @cindex integer, 8-byte
3317 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3318 hence @emph{quad}-word for 8 bytes.
3321 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3322 warning message; and just takes the lowest order 16 bytes of the bignum.
3323 @cindex sixteen-byte integer
3324 @cindex integer, 16-byte
3328 @section @code{.sbttl "@var{subheading}"}
3330 @cindex @code{sbttl} directive
3331 @cindex subtitles for listings
3332 @cindex listing control: subtitle
3333 Use @var{subheading} as the title (third line, immediately after the
3334 title line) when generating assembly listings.
3336 This directive affects subsequent pages, as well as the current page if
3337 it appears within ten lines of the top of a page.
3341 @section @code{.scl @var{class}}
3343 @cindex @code{scl} directive
3344 @cindex symbol storage class (COFF)
3345 @cindex COFF symbol storage class
3346 Set the storage-class value for a symbol. This directive may only be
3347 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3348 whether a symbol is static or external, or it may record further
3349 symbolic debugging information.
3352 The @samp{.scl} directive is primarily associated with COFF output; when
3353 configured to generate @code{b.out} output format, @code{@value{AS}} will
3354 accept this directive but ignore it.
3360 @section @code{.section @var{name}, @var{subsection}}
3362 @cindex @code{section} directive
3363 @cindex named section (COFF)
3364 @cindex COFF named section
3365 Assemble the following code into end of subsection numbered
3366 @var{subsection} in the COFF named section @var{name}. If you omit
3367 @var{subsection}, @code{@value{AS}} uses subsection number zero.
3368 @samp{.section .text} is equivalent to the @code{.text} directive;
3369 @samp{.section .data} is equivalent to the @code{.data} directive.
3373 @section @code{.set @var{symbol}, @var{expression}}
3375 @cindex @code{set} directive
3376 @cindex symbol value, setting
3377 This directive sets the value of @var{symbol} to @var{expression}. This
3378 will change @var{symbol}'s value and type to conform to
3379 @var{expression}. If @var{symbol} was flagged as external, it remains
3380 flagged. (@xref{Symbol Attributes}.)
3382 You may @code{.set} a symbol many times in the same assembly.
3383 If the expression's section is unknowable during pass 1, a second
3384 pass over the source program will be forced. The second pass is
3385 currently not implemented. @code{@value{AS}} will abort with an error
3386 message if one is required.
3388 If you @code{.set} a global symbol, the value stored in the object
3389 file is the last value stored into it.
3392 The syntax for @code{set} on the HPPA is
3393 @samp{@var{symbol} .set @var{expression}}.
3397 @section @code{.short @var{expressions}}
3399 @cindex @code{short} directive
3401 @code{.short} is normally the same as @samp{.word}.
3402 @xref{Word,,@code{.word}}.
3404 In some configurations, however, @code{.short} and @code{.word} generate
3405 numbers of different lengths; @pxref{Machine Dependencies}.
3409 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3412 This expects zero or more @var{expressions}, and emits
3413 a 16 bit number for each.
3418 @section @code{.single @var{flonums}}
3420 @cindex @code{single} directive
3421 @cindex floating point numbers (single)
3422 This directive assembles zero or more flonums, separated by commas. It
3423 has the same effect as @code{.float}.
3425 The exact kind of floating point numbers emitted depends on how
3426 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
3430 On the @value{TARGET} family, @code{.single} emits 32-bit floating point
3431 numbers in @sc{ieee} format.
3437 @section @code{.size}
3439 @cindex @code{size} directive
3440 This directive is generated by compilers to include auxiliary debugging
3441 information in the symbol table. It is only permitted inside
3442 @code{.def}/@code{.endef} pairs.
3445 @samp{.size} is only meaningful when generating COFF format output; when
3446 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3451 @ifclear no-space-dir
3453 @section @code{.space @var{size} , @var{fill}}
3455 @cindex @code{space} directive
3456 @cindex filling memory
3457 This directive emits @var{size} bytes, each of value @var{fill}. Both
3458 @var{size} and @var{fill} are absolute expressions. If the comma
3459 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3465 @section @code{.space}
3466 @cindex @code{space} directive
3468 On the AMD 29K, this directive is ignored; it is accepted for
3469 compatibility with other AMD 29K assemblers.
3472 @emph{Warning:} @code{.space} has a completely different meaning for HPPA
3473 targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800
3474 Assembly Language Reference Manual} (HP 92432-90001) for the meaning of
3475 the @code{.space} directive.
3479 @emph{Warning:} In most versions of the GNU assembler, the directive
3480 @code{.space} has the effect of @code{.block} @xref{Machine Dependencies}.
3486 @section @code{.stabd, .stabn, .stabs}
3488 @cindex symbolic debuggers, information for
3489 @cindex @code{stab@var{x}} directives
3490 There are three directives that begin @samp{.stab}.
3491 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3492 The symbols are not entered in the @code{@value{AS}} hash table: they
3493 cannot be referenced elsewhere in the source file.
3494 Up to five fields are required:
3498 This is the symbol's name. It may contain any character except
3499 @samp{\000}, so is more general than ordinary symbol names. Some
3500 debuggers used to code arbitrarily complex structures into symbol names
3504 An absolute expression. The symbol's type is set to the low 8 bits of
3505 this expression. Any bit pattern is permitted, but @code{@value{LD}}
3506 and debuggers will choke on silly bit patterns.
3509 An absolute expression. The symbol's ``other'' attribute is set to the
3510 low 8 bits of this expression.
3513 An absolute expression. The symbol's descriptor is set to the low 16
3514 bits of this expression.
3517 An absolute expression which becomes the symbol's value.
3520 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3521 or @code{.stabs} statement, the symbol has probably already been created
3522 and you will get a half-formed symbol in your object file. This is
3523 compatible with earlier assemblers!
3526 @cindex @code{stabd} directive
3527 @item .stabd @var{type} , @var{other} , @var{desc}
3529 The ``name'' of the symbol generated is not even an empty string.
3530 It is a null pointer, for compatibility. Older assemblers used a
3531 null pointer so they didn't waste space in object files with empty
3534 The symbol's value is set to the location counter,
3535 relocatably. When your program is linked, the value of this symbol
3536 will be where the location counter was when the @code{.stabd} was
3539 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3540 @cindex @code{stabn} directive
3541 The name of the symbol is set to the empty string @code{""}.
3543 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3544 @cindex @code{stabs} directive
3545 All five fields are specified.
3552 @section @code{.tag @var{structname}}
3554 @cindex COFF structure debugging
3555 @cindex structure debugging, COFF
3556 @cindex @code{tag} directive
3557 This directive is generated by compilers to include auxiliary debugging
3558 information in the symbol table. It is only permitted inside
3559 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3560 definitions in the symbol table with instances of those structures.
3563 @samp{.tag} is only used when generating COFF format output; when
3564 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3570 @section @code{.text @var{subsection}}
3572 @cindex @code{text} directive
3573 Tells @code{@value{AS}} to assemble the following statements onto the end of
3574 the text subsection numbered @var{subsection}, which is an absolute
3575 expression. If @var{subsection} is omitted, subsection number zero
3579 @section @code{.title "@var{heading}"}
3581 @cindex @code{title} directive
3582 @cindex listing control: title line
3583 Use @var{heading} as the title (second line, immediately after the
3584 source file name and pagenumber) when generating assembly listings.
3586 This directive affects subsequent pages, as well as the current page if
3587 it appears within ten lines of the top of a page.
3591 @section @code{.type @var{int}}
3593 @cindex COFF symbol type
3594 @cindex symbol type, COFF
3595 @cindex @code{type} directive
3596 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3597 records the integer @var{int} as the type attribute of a symbol table entry.
3600 @samp{.type} is associated only with COFF format output; when
3601 @code{@value{AS}} is configured for @code{b.out} output, it accepts this
3602 directive but ignores it.
3608 @section @code{.val @var{addr}}
3610 @cindex @code{val} directive
3611 @cindex COFF value attribute
3612 @cindex value attribute, COFF
3613 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3614 records the address @var{addr} as the value attribute of a symbol table
3618 @samp{.val} is used only for COFF output; when @code{@value{AS}} is
3619 configured for @code{b.out}, it accepts this directive but ignores it.
3624 @section @code{.word @var{expressions}}
3626 @cindex @code{word} directive
3627 This directive expects zero or more @var{expressions}, of any section,
3628 separated by commas.
3631 For each expression, @code{@value{AS}} emits a 32-bit number.
3634 For each expression, @code{@value{AS}} emits a 16-bit number.
3639 The size of the number emitted, and its byte order,
3640 depends on what kind of computer will run the program.
3643 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3644 @c happen---32-bit addressability, period; no long/short jumps.
3645 @ifset DIFF-TBL-KLUGE
3646 @cindex difference tables altered
3647 @cindex altered difference tables
3649 @emph{Warning: Special Treatment to support Compilers}
3653 Machines with a 32-bit address space, but that do less than 32-bit
3654 addressing, require the following special treatment. If the machine of
3655 interest to you does 32-bit addressing (or doesn't require it;
3656 @pxref{Machine Dependencies}), you can ignore this issue.
3659 In order to assemble compiler output into something that will work,
3660 @code{@value{AS}} will occasionlly do strange things to @samp{.word} directives.
3661 Directives of the form @samp{.word sym1-sym2} are often emitted by
3662 compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a
3663 directive of the form @samp{.word sym1-sym2}, and the difference between
3664 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}} will
3665 create a @dfn{secondary jump table}, immediately before the next label.
3666 This secondary jump table will be preceded by a short-jump to the
3667 first byte after the secondary table. This short-jump prevents the flow
3668 of control from accidentally falling into the new table. Inside the
3669 table will be a long-jump to @code{sym2}. The original @samp{.word}
3670 will contain @code{sym1} minus the address of the long-jump to
3673 If there were several occurrences of @samp{.word sym1-sym2} before the
3674 secondary jump table, all of them will be adjusted. If there was a
3675 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3676 long-jump to @code{sym4} will be included in the secondary jump table,
3677 and the @code{.word} directives will be adjusted to contain @code{sym3}
3678 minus the address of the long-jump to @code{sym4}; and so on, for as many
3679 entries in the original jump table as necessary.
3682 @emph{This feature may be disabled by compiling @code{@value{AS}} with the
3683 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3684 assembly language programmers.
3687 @c end DIFF-TBL-KLUGE
3690 @section Deprecated Directives
3692 @cindex deprecated directives
3693 @cindex obsolescent directives
3694 One day these directives won't work.
3695 They are included for compatibility with older assemblers.
3703 @node Machine Dependencies
3704 @chapter Machine Dependent Features
3706 @cindex machine dependencies
3707 The machine instruction sets are (almost by definition) different on
3708 each machine where @code{@value{AS}} runs. Floating point representations
3709 vary as well, and @code{@value{AS}} often supports a few additional
3710 directives or command-line options for compatibility with other
3711 assemblers on a particular platform. Finally, some versions of
3712 @code{@value{AS}} support special pseudo-instructions for branch
3715 This chapter discusses most of these differences, though it does not
3716 include details on any machine's instruction set. For details on that
3717 subject, see the hardware manufacturer's manual.
3721 * Vax-Dependent:: VAX Dependent Features
3724 * AMD29K-Dependent:: AMD 29K Dependent Features
3727 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
3730 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
3733 * HPPA-Dependent:: HPPA Dependent Features
3736 * SH-Dependent:: Hitachi SH Dependent Features
3739 * i960-Dependent:: Intel 80960 Dependent Features
3742 * M68K-Dependent:: M680x0 Dependent Features
3745 * Sparc-Dependent:: SPARC Dependent Features
3748 * Z8000-Dependent:: Z8000 Dependent Features
3751 * i386-Dependent:: 80386 Dependent Features
3758 @c The following major nodes are *sections* in the GENERIC version, *chapters*
3759 @c in single-cpu versions. This is mainly achieved by @lowersections. There is a
3760 @c peculiarity: to preserve cross-references, there must be a node called
3761 @c "Machine Dependencies". Hence the conditional nodenames in each
3762 @c major node below. Node defaulting in makeinfo requires adjacency of
3763 @c node and sectioning commands; hence the repetition of @chapter BLAH
3764 @c in both conditional blocks.
3769 @chapter VAX Dependent Features
3774 @node Machine Dependencies
3775 @chapter VAX Dependent Features
3781 * Vax-Opts:: VAX Command-Line Options
3782 * VAX-float:: VAX Floating Point
3783 * VAX-directives:: Vax Machine Directives
3784 * VAX-opcodes:: VAX Opcodes
3785 * VAX-branch:: VAX Branch Improvement
3786 * VAX-operands:: VAX Operands
3787 * VAX-no:: Not Supported on VAX
3792 @section VAX Command-Line Options
3794 @cindex command-line options ignored, VAX
3795 @cindex VAX command-line options ignored
3796 The Vax version of @code{@value{AS}} accepts any of the following options,
3797 gives a warning message that the option was ignored and proceeds.
3798 These options are for compatibility with scripts designed for other
3799 people's assemblers.
3802 @item @kbd{-D} (Debug)
3803 @itemx @kbd{-S} (Symbol Table)
3804 @itemx @kbd{-T} (Token Trace)
3805 @cindex @code{-D}, ignored on VAX
3806 @cindex @code{-S}, ignored on VAX
3807 @cindex @code{-T}, ignored on VAX
3808 These are obsolete options used to debug old assemblers.
3810 @item @kbd{-d} (Displacement size for JUMPs)
3811 @cindex @code{-d}, VAX option
3812 This option expects a number following the @kbd{-d}. Like options
3813 that expect filenames, the number may immediately follow the
3814 @kbd{-d} (old standard) or constitute the whole of the command line
3815 argument that follows @kbd{-d} (GNU standard).
3817 @item @kbd{-V} (Virtualize Interpass Temporary File)
3818 @cindex @code{-V}, redundant on VAX
3819 Some other assemblers use a temporary file. This option
3820 commanded them to keep the information in active memory rather
3821 than in a disk file. @code{@value{AS}} always does this, so this
3822 option is redundant.
3824 @item @kbd{-J} (JUMPify Longer Branches)
3825 @cindex @code{-J}, ignored on VAX
3826 Many 32-bit computers permit a variety of branch instructions
3827 to do the same job. Some of these instructions are short (and
3828 fast) but have a limited range; others are long (and slow) but
3829 can branch anywhere in virtual memory. Often there are 3
3830 flavors of branch: short, medium and long. Some other
3831 assemblers would emit short and medium branches, unless told by
3832 this option to emit short and long branches.
3834 @item @kbd{-t} (Temporary File Directory)
3835 @cindex @code{-t}, ignored on VAX
3836 Some other assemblers may use a temporary file, and this option
3837 takes a filename being the directory to site the temporary
3838 file. Since @code{@value{AS}} does not use a temporary disk file, this
3839 option makes no difference. @kbd{-t} needs exactly one
3843 @cindex VMS (VAX) options
3844 @cindex options for VAX/VMS
3845 @cindex VAX/VMS options
3846 @cindex @code{-h} option, VAX/VMS
3847 @cindex @code{-+} option, VAX/VMS
3848 @cindex Vax-11 C compatibility
3849 @cindex symbols with lowercase, VAX/VMS
3850 @c FIXME! look into "I think" below, correct if needed, delete.
3851 The Vax version of the assembler accepts two options when
3852 compiled for VMS. They are @kbd{-h}, and @kbd{-+}. The
3853 @kbd{-h} option prevents @code{@value{AS}} from modifying the
3854 symbol-table entries for symbols that contain lowercase
3855 characters (I think). The @kbd{-+} option causes @code{@value{AS}} to
3856 print warning messages if the FILENAME part of the object file,
3857 or any symbol name is larger than 31 characters. The @kbd{-+}
3858 option also insertes some code following the @samp{_main}
3859 symbol so that the object file will be compatible with Vax-11
3863 @section VAX Floating Point
3865 @cindex VAX floating point
3866 @cindex floating point, VAX
3867 Conversion of flonums to floating point is correct, and
3868 compatible with previous assemblers. Rounding is
3869 towards zero if the remainder is exactly half the least significant bit.
3871 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
3874 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
3875 are rendered correctly. Again, rounding is towards zero in the
3878 @cindex @code{float} directive, VAX
3879 @cindex @code{double} directive, VAX
3880 The @code{.float} directive produces @code{f} format numbers.
3881 The @code{.double} directive produces @code{d} format numbers.
3883 @node VAX-directives
3884 @section Vax Machine Directives
3886 @cindex machine directives, VAX
3887 @cindex VAX machine directives
3888 The Vax version of the assembler supports four directives for
3889 generating Vax floating point constants. They are described in the
3892 @cindex wide floating point directives, VAX
3895 @cindex @code{dfloat} directive, VAX
3896 This expects zero or more flonums, separated by commas, and
3897 assembles Vax @code{d} format 64-bit floating point constants.
3900 @cindex @code{ffloat} directive, VAX
3901 This expects zero or more flonums, separated by commas, and
3902 assembles Vax @code{f} format 32-bit floating point constants.
3905 @cindex @code{gfloat} directive, VAX
3906 This expects zero or more flonums, separated by commas, and
3907 assembles Vax @code{g} format 64-bit floating point constants.
3910 @cindex @code{hfloat} directive, VAX
3911 This expects zero or more flonums, separated by commas, and
3912 assembles Vax @code{h} format 128-bit floating point constants.
3917 @section VAX Opcodes
3919 @cindex VAX opcode mnemonics
3920 @cindex opcode mnemonics, VAX
3921 @cindex mnemonics for opcodes, VAX
3922 All DEC mnemonics are supported. Beware that @code{case@dots{}}
3923 instructions have exactly 3 operands. The dispatch table that
3924 follows the @code{case@dots{}} instruction should be made with
3925 @code{.word} statements. This is compatible with all unix
3926 assemblers we know of.
3929 @section VAX Branch Improvement
3931 @cindex VAX branch improvement
3932 @cindex branch improvement, VAX
3933 @cindex pseudo-ops for branch, VAX
3934 Certain pseudo opcodes are permitted. They are for branch
3935 instructions. They expand to the shortest branch instruction that
3936 will reach the target. Generally these mnemonics are made by
3937 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
3938 This feature is included both for compatibility and to help
3939 compilers. If you don't need this feature, don't use these
3940 opcodes. Here are the mnemonics, and the code they can expand into.
3944 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
3946 @item (byte displacement)
3948 @item (word displacement)
3950 @item (long displacement)
3955 Unconditional branch.
3957 @item (byte displacement)
3959 @item (word displacement)
3961 @item (long displacement)
3965 @var{COND} may be any one of the conditional branches
3966 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
3967 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
3968 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
3969 @var{COND} may also be one of the bit tests
3970 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
3971 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
3972 @var{NOTCOND} is the opposite condition to @var{COND}.
3974 @item (byte displacement)
3975 @kbd{b@var{COND} @dots{}}
3976 @item (word displacement)
3977 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
3978 @item (long displacement)
3979 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
3982 @var{X} may be one of @code{b d f g h l w}.
3984 @item (word displacement)
3985 @kbd{@var{OPCODE} @dots{}}
3986 @item (long displacement)
3988 @var{OPCODE} @dots{}, foo ;
3995 @var{YYY} may be one of @code{lss leq}.
3997 @var{ZZZ} may be one of @code{geq gtr}.
3999 @item (byte displacement)
4000 @kbd{@var{OPCODE} @dots{}}
4001 @item (word displacement)
4003 @var{OPCODE} @dots{}, foo ;
4005 foo: brw @var{destination} ;
4008 @item (long displacement)
4010 @var{OPCODE} @dots{}, foo ;
4012 foo: jmp @var{destination} ;
4021 @item (byte displacement)
4022 @kbd{@var{OPCODE} @dots{}}
4023 @item (word displacement)
4025 @var{OPCODE} @dots{}, foo ;
4027 foo: brw @var{destination} ;
4030 @item (long displacement)
4032 @var{OPCODE} @dots{}, foo ;
4034 foo: jmp @var{destination} ;
4041 @section VAX Operands
4043 @cindex VAX operand notation
4044 @cindex operand notation, VAX
4045 @cindex immediate character, VAX
4046 @cindex VAX immediate character
4047 The immediate character is @samp{$} for Unix compatibility, not
4048 @samp{#} as DEC writes it.
4050 @cindex indirect character, VAX
4051 @cindex VAX indirect character
4052 The indirect character is @samp{*} for Unix compatibility, not
4053 @samp{@@} as DEC writes it.
4055 @cindex displacement sizing character, VAX
4056 @cindex VAX displacement sizing character
4057 The displacement sizing character is @samp{`} (an accent grave) for
4058 Unix compatibility, not @samp{^} as DEC writes it. The letter
4059 preceding @samp{`} may have either case. @samp{G} is not
4060 understood, but all other letters (@code{b i l s w}) are understood.
4062 @cindex register names, VAX
4063 @cindex VAX register names
4064 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
4065 pc}. Any case of letters will do.
4072 Any expression is permitted in an operand. Operands are comma
4075 @c There is some bug to do with recognizing expressions
4076 @c in operands, but I forget what it is. It is
4077 @c a syntax clash because () is used as an address mode
4078 @c and to encapsulate sub-expressions.
4081 @section Not Supported on VAX
4083 @cindex VAX bitfields not supported
4084 @cindex bitfields, not supported on VAX
4085 Vax bit fields can not be assembled with @code{@value{AS}}. Someone
4086 can add the required code if they really need it.
4092 @node AMD29K-Dependent
4093 @chapter AMD 29K Dependent Features
4096 @node Machine Dependencies
4097 @chapter AMD 29K Dependent Features
4100 @cindex AMD 29K support
4103 * AMD29K Options:: Options
4104 * AMD29K Syntax:: Syntax
4105 * AMD29K Floating Point:: Floating Point
4106 * AMD29K Directives:: AMD 29K Machine Directives
4107 * AMD29K Opcodes:: Opcodes
4110 @node AMD29K Options
4112 @cindex AMD 29K options (none)
4113 @cindex options for AMD29K (none)
4114 @code{@value{AS}} has no additional command-line options for the AMD
4120 * AMD29K-Chars:: Special Characters
4121 * AMD29K-Regs:: Register Names
4125 @subsection Special Characters
4127 @cindex line comment character, AMD 29K
4128 @cindex AMD 29K line comment character
4129 @samp{;} is the line comment character.
4131 @cindex line separator, AMD 29K
4132 @cindex AMD 29K line separator
4133 @cindex statement separator, AMD 29K
4134 @cindex AMD 29K statement separator
4135 @samp{@@} can be used instead of a newline to separate statements.
4137 @cindex identifiers, AMD 29K
4138 @cindex AMD 29K identifiers
4139 The character @samp{?} is permitted in identifiers (but may not begin
4143 @subsection Register Names
4145 @cindex AMD 29K register names
4146 @cindex register names, AMD 29K
4147 General-purpose registers are represented by predefined symbols of the
4148 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
4149 (for local registers), where @var{nnn} represents a number between
4150 @code{0} and @code{127}, written with no leading zeros. The leading
4151 letters may be in either upper or lower case; for example, @samp{gr13}
4152 and @samp{LR7} are both valid register names.
4154 You may also refer to general-purpose registers by specifying the
4155 register number as the result of an expression (prefixed with @samp{%%}
4156 to flag the expression as a register number):
4161 ---where @var{expression} must be an absolute expression evaluating to a
4162 number between @code{0} and @code{255}. The range [0, 127] refers to
4163 global registers, and the range [128, 255] to local registers.
4165 @cindex special purpose registers, AMD 29K
4166 @cindex AMD 29K special purpose registers
4167 @cindex protected registers, AMD 29K
4168 @cindex AMD 29K protected registers
4169 In addition, @code{@value{AS}} understands the following protected
4170 special-purpose register names for the AMD 29K family:
4180 These unprotected special-purpose register names are also recognized:
4188 @node AMD29K Floating Point
4189 @section Floating Point
4191 @cindex floating point, AMD 29K (@sc{ieee})
4192 @cindex AMD 29K floating point (@sc{ieee})
4193 The AMD 29K family uses @sc{ieee} floating-point numbers.
4195 @node AMD29K Directives
4196 @section AMD 29K Machine Directives
4198 @cindex machine directives, AMD 29K
4199 @cindex AMD 29K machine directives
4201 @item .block @var{size} , @var{fill}
4202 @cindex @code{block} directive, AMD 29K
4203 This directive emits @var{size} bytes, each of value @var{fill}. Both
4204 @var{size} and @var{fill} are absolute expressions. If the comma
4205 and @var{fill} are omitted, @var{fill} is assumed to be zero.
4207 In other versions of the GNU assembler, this directive is called
4213 @cindex @code{cputype} directive, AMD 29K
4214 This directive is ignored; it is accepted for compatibility with other
4218 @cindex @code{file} directive, AMD 29K
4219 This directive is ignored; it is accepted for compatibility with other
4223 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
4224 used for the directive called @code{.app-file} in the AMD 29K support.
4228 @cindex @code{line} directive, AMD 29K
4229 This directive is ignored; it is accepted for compatibility with other
4233 @c since we're ignoring .lsym...
4234 @item .reg @var{symbol}, @var{expression}
4235 @cindex @code{reg} directive, AMD 29K
4236 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
4240 @cindex @code{sect} directive, AMD 29K
4241 This directive is ignored; it is accepted for compatibility with other
4244 @item .use @var{section name}
4245 @cindex @code{use} directive, AMD 29K
4246 Establishes the section and subsection for the following code;
4247 @var{section name} may be one of @code{.text}, @code{.data},
4248 @code{.data1}, or @code{.lit}. With one of the first three @var{section
4249 name} options, @samp{.use} is equivalent to the machine directive
4250 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
4254 @node AMD29K Opcodes
4257 @cindex AMD 29K opcodes
4258 @cindex opcodes for AMD 29K
4259 @code{@value{AS}} implements all the standard AMD 29K opcodes. No
4260 additional pseudo-instructions are needed on this family.
4262 For information on the 29K machine instruction set, see @cite{Am29000
4263 User's Manual}, Advanced Micro Devices, Inc.
4268 @node Machine Dependencies
4269 @chapter Machine Dependent Features
4271 The machine instruction sets are different on each Hitachi chip family,
4272 and there are also some syntax differences among the families. This
4273 chapter describes the specific @code{@value{AS}} features for each
4277 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
4278 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
4279 * SH-Dependent:: Hitachi SH Dependent Features
4289 @node H8/300-Dependent
4290 @chapter H8/300 Dependent Features
4292 @cindex H8/300 support
4294 * H8/300 Options:: Options
4295 * H8/300 Syntax:: Syntax
4296 * H8/300 Floating Point:: Floating Point
4297 * H8/300 Directives:: H8/300 Machine Directives
4298 * H8/300 Opcodes:: Opcodes
4301 @node H8/300 Options
4304 @cindex H8/300 options (none)
4305 @cindex options, H8/300 (none)
4306 @code{@value{AS}} has no additional command-line options for the Hitachi
4312 * H8/300-Chars:: Special Characters
4313 * H8/300-Regs:: Register Names
4314 * H8/300-Addressing:: Addressing Modes
4318 @subsection Special Characters
4320 @cindex line comment character, H8/300
4321 @cindex H8/300 line comment character
4322 @samp{;} is the line comment character.
4324 @cindex line separator, H8/300
4325 @cindex statement separator, H8/300
4326 @cindex H8/300 line separator
4327 @samp{$} can be used instead of a newline to separate statements.
4328 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4331 @subsection Register Names
4333 @cindex H8/300 registers
4334 @cindex register names, H8/300
4335 You can use predefined symbols of the form @samp{r@var{n}h} and
4336 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4337 general-purpose registers. @var{n} is a digit from @samp{0} to
4338 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4341 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4342 to the H8/300 registers as 16-bit registers (you must use this form for
4345 On the H8/300H, you can also use the eight predefined symbols
4346 @samp{er@var{n}} (@samp{er0} @dots{} @samp{er7}) to refer to the 32-bit
4347 general purpose registers.
4349 The two control registers are called @code{pc} (program counter; a
4350 16-bit register, except on the H8/300H where it is 24 bits) and
4351 @code{ccr} (condition code register; an 8-bit register). @code{r7} is
4352 used as the stack pointer, and can also be called @code{sp}.
4354 @node H8/300-Addressing
4355 @subsection Addressing Modes
4357 @cindex addressing modes, H8/300
4358 @cindex H8/300 addressing modes
4359 @value{AS} understands the following addressing modes for the H8/300:
4367 @item @@(@var{d}, r@var{n})
4368 @itemx @@(@var{d}:16, r@var{n})
4369 @itemx @@(@var{d}:24, r@var{n})
4370 Register indirect: 16-bit or 24-bit displacement @var{d} from register
4371 @var{n}. (24-bit displacements are only meaningful on the H8/300H.)
4374 Register indirect with post-increment
4377 Register indirect with pre-decrement
4379 @item @code{@@}@var{aa}
4380 @itemx @code{@@}@var{aa}:8
4381 @itemx @code{@@}@var{aa}:16
4382 @itemx @code{@@}@var{aa}:24
4383 Absolute address @code{aa}. (The address size @samp{:24} only makes
4384 sense on the H8/300H.)
4390 Immediate data @var{xx}. You may specify the @samp{:8}, @samp{:16}, or
4391 @samp{:32} for clarity, if you wish; but @code{@value{AS}} neither
4392 requires this nor uses it---the data size required is taken from
4395 @item @code{@@}@code{@@}@var{aa}
4396 @itemx @code{@@}@code{@@}@var{aa}:8
4397 Memory indirect. You may specify the @samp{:8} for clarity, if you
4398 wish; but @code{@value{AS}} neither requires this nor uses it.
4401 @node H8/300 Floating Point
4402 @section Floating Point
4404 @cindex floating point, H8/300 (@sc{ieee})
4405 @cindex H8/300 floating point (@sc{ieee})
4406 The H8/300 family has no hardware floating point, but the @code{.float}
4407 directive generates @sc{ieee} floating-point numbers for compatibility
4408 with other development tools.
4411 @node H8/300 Directives
4412 @section H8/300 Machine Directives
4414 @cindex H8/300 machine directives (none)
4415 @cindex machine directives, H8/300 (none)
4416 @cindex @code{word} directive, H8/300
4417 @cindex @code{int} directive, H8/300
4418 @code{@value{AS}} has only one machine-dependent directive for the
4423 @cindex H8/300H, assembling for
4424 Recognize and emit additional instructions for the H8/300H variant, and
4425 also make @code{.int} emit 32-bit numbers rather than the usual (16-bit)
4426 for the H8/300 family.
4429 On the H8/300 family (including the H8/300H) @samp{.word} directives
4430 generate 16-bit numbers.
4432 @node H8/300 Opcodes
4435 @cindex H8/300 opcode summary
4436 @cindex opcode summary, H8/300
4437 @cindex mnemonics, H8/300
4438 @cindex instruction summary, H8/300
4439 For detailed information on the H8/300 machine instruction set, see
4440 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025). For
4441 information specific to the H8/300H, see @cite{H8/300H Series
4442 Programming Manual} (Hitachi).
4444 @code{@value{AS}} implements all the standard H8/300 opcodes. No additional
4445 pseudo-instructions are needed on this family.
4447 The following table summarizes the H8/300 opcodes, and their arguments.
4448 Entries marked @samp{*} are opcodes used only on the H8/300H.
4451 @c Using @group seems to use the normal baselineskip, not the smallexample
4452 @c baselineskip; looks approx doublespaced.
4454 Rs @r{source register}
4455 Rd @r{destination register}
4456 abs @r{absolute address}
4457 imm @r{immediate data}
4458 disp:N @r{N-bit displacement from a register}
4459 pcrel:N @r{N-bit displacement relative to program counter}
4461 add.b #imm,rd * andc #imm,ccr
4462 add.b rs,rd band #imm,rd
4463 add.w rs,rd band #imm,@@rd
4464 * add.w #imm,rd band #imm,@@abs:8
4465 * add.l rs,rd bra pcrel:8
4466 * add.l #imm,rd * bra pcrel:16
4467 adds #imm,rd bt pcrel:8
4468 addx #imm,rd * bt pcrel:16
4469 addx rs,rd brn pcrel:8
4470 and.b #imm,rd * brn pcrel:16
4471 and.b rs,rd bf pcrel:8
4472 * and.w rs,rd * bf pcrel:16
4473 * and.w #imm,rd bhi pcrel:8
4474 * and.l #imm,rd * bhi pcrel:16
4475 * and.l rs,rd bls pcrel:8
4477 * bls pcrel:16 bld #imm,rd
4478 bcc pcrel:8 bld #imm,@@rd
4479 * bcc pcrel:16 bld #imm,@@abs:8
4480 bhs pcrel:8 bnot #imm,rd
4481 * bhs pcrel:16 bnot #imm,@@rd
4482 bcs pcrel:8 bnot #imm,@@abs:8
4483 * bcs pcrel:16 bnot rs,rd
4484 blo pcrel:8 bnot rs,@@rd
4485 * blo pcrel:16 bnot rs,@@abs:8
4486 bne pcrel:8 bor #imm,rd
4487 * bne pcrel:16 bor #imm,@@rd
4488 beq pcrel:8 bor #imm,@@abs:8
4489 * beq pcrel:16 bset #imm,rd
4490 bvc pcrel:8 bset #imm,@@rd
4491 * bvc pcrel:16 bset #imm,@@abs:8
4492 bvs pcrel:8 bset rs,rd
4493 * bvs pcrel:16 bset rs,@@rd
4494 bpl pcrel:8 bset rs,@@abs:8
4495 * bpl pcrel:16 bsr pcrel:8
4496 bmi pcrel:8 bsr pcrel:16
4497 * bmi pcrel:16 bst #imm,rd
4498 bge pcrel:8 bst #imm,@@rd
4499 * bge pcrel:16 bst #imm,@@abs:8
4500 blt pcrel:8 btst #imm,rd
4501 * blt pcrel:16 btst #imm,@@rd
4502 bgt pcrel:8 btst #imm,@@abs:8
4503 * bgt pcrel:16 btst rs,rd
4504 ble pcrel:8 btst rs,@@rd
4505 * ble pcrel:16 btst rs,@@abs:8
4506 bclr #imm,rd bxor #imm,rd
4507 bclr #imm,@@rd bxor #imm,@@rd
4508 bclr #imm,@@abs:8 bxor #imm,@@abs:8
4509 bclr rs,rd cmp.b #imm,rd
4510 bclr rs,@@rd cmp.b rs,rd
4511 bclr rs,@@abs:8 cmp.w rs,rd
4512 biand #imm,rd cmp.w rs,rd
4513 biand #imm,@@rd * cmp.w #imm,rd
4514 biand #imm,@@abs:8 * cmp.l #imm,rd
4515 bild #imm,rd * cmp.l rs,rd
4516 bild #imm,@@rd daa rs
4517 bild #imm,@@abs:8 das rs
4518 bior #imm,rd dec.b rs
4519 bior #imm,@@rd * dec.w #imm,rd
4520 bior #imm,@@abs:8 * dec.l #imm,rd
4521 bist #imm,rd divxu.b rs,rd
4522 bist #imm,@@rd * divxu.w rs,rd
4523 bist #imm,@@abs:8 * divxs.b rs,rd
4524 bixor #imm,rd * divxs.w rs,rd
4525 bixor #imm,@@rd eepmov
4526 bixor #imm,@@abs:8 * eepmovw
4528 * exts.w rd mov.w rs,@@abs:16
4529 * exts.l rd * mov.l #imm,rd
4530 * extu.w rd * mov.l rs,rd
4531 * extu.l rd * mov.l @@rs,rd
4532 inc rs * mov.l @@(disp:16,rs),rd
4533 * inc.w #imm,rd * mov.l @@(disp:24,rs),rd
4534 * inc.l #imm,rd * mov.l @@rs+,rd
4535 jmp @@rs * mov.l @@abs:16,rd
4536 jmp abs * mov.l @@abs:24,rd
4537 jmp @@@@abs:8 * mov.l rs,@@rd
4538 jsr @@rs * mov.l rs,@@(disp:16,rd)
4539 jsr abs * mov.l rs,@@(disp:24,rd)
4540 jsr @@@@abs:8 * mov.l rs,@@-rd
4541 ldc #imm,ccr * mov.l rs,@@abs:16
4542 ldc rs,ccr * mov.l rs,@@abs:24
4543 * ldc @@abs:16,ccr movfpe @@abs:16,rd
4544 * ldc @@abs:24,ccr movtpe rs,@@abs:16
4545 * ldc @@(disp:16,rs),ccr mulxu.b rs,rd
4546 * ldc @@(disp:24,rs),ccr * mulxu.w rs,rd
4547 * ldc @@rs+,ccr * mulxs.b rs,rd
4548 * ldc @@rs,ccr * mulxs.w rs,rd
4549 * mov.b @@(disp:24,rs),rd neg.b rs
4550 * mov.b rs,@@(disp:24,rd) * neg.w rs
4551 mov.b @@abs:16,rd * neg.l rs
4553 mov.b @@abs:8,rd not.b rs
4554 mov.b rs,@@abs:8 * not.w rs
4555 mov.b rs,rd * not.l rs
4556 mov.b #imm,rd or.b #imm,rd
4557 mov.b @@rs,rd or.b rs,rd
4558 mov.b @@(disp:16,rs),rd * or.w #imm,rd
4559 mov.b @@rs+,rd * or.w rs,rd
4560 mov.b @@abs:8,rd * or.l #imm,rd
4561 mov.b rs,@@rd * or.l rs,rd
4562 mov.b rs,@@(disp:16,rd) orc #imm,ccr
4563 mov.b rs,@@-rd pop.w rs
4564 mov.b rs,@@abs:8 * pop.l rs
4565 mov.w rs,@@rd push.w rs
4566 * mov.w @@(disp:24,rs),rd * push.l rs
4567 * mov.w rs,@@(disp:24,rd) rotl.b rs
4568 * mov.w @@abs:24,rd * rotl.w rs
4569 * mov.w rs,@@abs:24 * rotl.l rs
4570 mov.w rs,rd rotr.b rs
4571 mov.w #imm,rd * rotr.w rs
4572 mov.w @@rs,rd * rotr.l rs
4573 mov.w @@(disp:16,rs),rd rotxl.b rs
4574 mov.w @@rs+,rd * rotxl.w rs
4575 mov.w @@abs:16,rd * rotxl.l rs
4576 mov.w rs,@@(disp:16,rd) rotxr.b rs
4577 mov.w rs,@@-rd * rotxr.w rs
4579 * rotxr.l rs * stc ccr,@@(disp:24,rd)
4581 rte * stc ccr,@@abs:16
4582 rts * stc ccr,@@abs:24
4583 shal.b rs sub.b rs,rd
4584 * shal.w rs sub.w rs,rd
4585 * shal.l rs * sub.w #imm,rd
4586 shar.b rs * sub.l rs,rd
4587 * shar.w rs * sub.l #imm,rd
4588 * shar.l rs subs #imm,rd
4589 shll.b rs subx #imm,rd
4590 * shll.w rs subx rs,rd
4591 * shll.l rs * trapa #imm
4592 shlr.b rs xor #imm,rd
4593 * shlr.w rs xor rs,rd
4594 * shlr.l rs * xor.w #imm,rd
4596 stc ccr,rd * xor.l #imm,rd
4597 * stc ccr,@@rs * xor.l rs,rd
4598 * stc ccr,@@(disp:16,rd) xorc #imm,ccr
4601 @cindex size suffixes, H8/300
4602 @cindex H8/300 size suffixes
4603 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4604 @code{sub}) are defined with variants using the suffixes @samp{.b},
4605 @samp{.w}, and @samp{.l} to specify the size of a memory operand.
4606 @code{@value{AS}} supports these suffixes, but does not require them;
4607 since one of the operands is always a register, @code{@value{AS}} can
4608 deduce the correct size.
4610 For example, since @code{r0} refers to a 16-bit register,
4613 @exdent is equivalent to
4617 If you use the size suffixes, @code{@value{AS}} issues a warning when
4618 the suffix and the register size do not match.
4623 @node H8/500-Dependent
4624 @chapter H8/500 Dependent Features
4626 @cindex H8/500 support
4628 * H8/500 Options:: Options
4629 * H8/500 Syntax:: Syntax
4630 * H8/500 Floating Point:: Floating Point
4631 * H8/500 Directives:: H8/500 Machine Directives
4632 * H8/500 Opcodes:: Opcodes
4635 @node H8/500 Options
4638 @cindex H8/500 options (none)
4639 @cindex options, H8/500 (none)
4640 @code{@value{AS}} has no additional command-line options for the Hitachi
4647 * H8/500-Chars:: Special Characters
4648 * H8/500-Regs:: Register Names
4649 * H8/500-Addressing:: Addressing Modes
4653 @subsection Special Characters
4655 @cindex line comment character, H8/500
4656 @cindex H8/500 line comment character
4657 @samp{!} is the line comment character.
4659 @cindex line separator, H8/500
4660 @cindex statement separator, H8/500
4661 @cindex H8/500 line separator
4662 @samp{;} can be used instead of a newline to separate statements.
4664 @cindex symbol names, @samp{$} in
4665 @cindex @code{$} in symbol names
4666 Since @samp{$} has no special meaning, you may use it in symbol names.
4669 @subsection Register Names
4671 @cindex H8/500 registers
4672 @cindex registers, H8/500
4673 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
4674 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, and @samp{r7} to refer to
4675 the H8/500 registers.
4677 The H8/500 also has these control registers:
4699 condition code register
4702 All registers are 16 bits long. To represent 32 bit numbers, use two
4703 adjacent registers; for distant memory addresses, use one of the segment
4704 pointers (@code{cp} for the program counter; @code{dp} for
4705 @code{r0}--@code{r3}; @code{ep} for @code{r4} and @code{r5}; and
4706 @code{tp} for @code{r6} and @code{r7}.
4708 @node H8/500-Addressing
4709 @subsection Addressing Modes
4711 @cindex addressing modes, H8/500
4712 @cindex H8/500 addressing modes
4713 @value{AS} understands the following addressing modes for the H8/500:
4721 @item @@(d:8, R@var{n})
4722 Register indirect with 8 bit signed displacement
4724 @item @@(d:16, R@var{n})
4725 Register indirect with 16 bit signed displacement
4728 Register indirect with pre-decrement
4731 Register indirect with post-increment
4734 8 bit absolute address
4737 16 bit absolute address
4746 @node H8/500 Floating Point
4747 @section Floating Point
4749 @cindex floating point, H8/500 (@sc{ieee})
4750 @cindex H8/500 floating point (@sc{ieee})
4751 The H8/500 family uses @sc{ieee} floating-point numbers.
4753 @node H8/500 Directives
4754 @section H8/500 Machine Directives
4756 @cindex H8/500 machine directives (none)
4757 @cindex machine directives, H8/500 (none)
4758 @cindex @code{word} directive, H8/500
4759 @cindex @code{int} directive, H8/500
4760 @code{@value{AS}} has no machine-dependent directives for the H8/500.
4761 However, on this platform the @samp{.int} and @samp{.word} directives
4762 generate 16-bit numbers.
4764 @node H8/500 Opcodes
4767 @cindex H8/500 opcode summary
4768 @cindex opcode summary, H8/500
4769 @cindex mnemonics, H8/500
4770 @cindex instruction summary, H8/500
4771 For detailed information on the H8/500 machine instruction set, see
4772 @cite{H8/500 Series Programming Manual} (Hitachi M21T001).
4774 @code{@value{AS}} implements all the standard H8/500 opcodes. No additional
4775 pseudo-instructions are needed on this family.
4777 The following table summarizes H8/500 opcodes and their operands:
4779 @c Use @group if it ever works, instead of @page
4783 abs8 @r{8-bit absolute address}
4784 abs16 @r{16-bit absolute address}
4785 abs24 @r{24-bit absolute address}
4786 crb @r{@code{ccr}, @code{br}, @code{ep}, @code{dp}, @code{tp}, @code{dp}}
4787 disp8 @r{8-bit displacement}
4788 ea @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4789 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16},}
4790 @r{@code{#xx:8}, @code{#xx:16}}
4791 ea_mem @r{@code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4792 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4793 ea_noimm @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4794 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4796 imm4 @r{4-bit immediate data}
4797 imm8 @r{8-bit immediate data}
4798 imm16 @r{16-bit immediate data}
4799 pcrel8 @r{8-bit offset from program counter}
4800 pcrel16 @r{16-bit offset from program counter}
4801 qim @r{@code{-2}, @code{-1}, @code{1}, @code{2}}
4803 rs @r{a register distinct from rd}
4804 rlist @r{comma-separated list of registers in parentheses;}
4805 @r{register ranges @code{rd-rs} are allowed}
4806 sp @r{stack pointer (@code{r7})}
4807 sr @r{status register}
4808 sz @r{size; @samp{.b} or @samp{.w}. If omitted, default @samp{.w}}
4810 ldc[.b] ea,crb bcc[.w] pcrel16
4811 ldc[.w] ea,sr bcc[.b] pcrel8
4812 add[:q] sz qim,ea_noimm bhs[.w] pcrel16
4813 add[:g] sz ea,rd bhs[.b] pcrel8
4814 adds sz ea,rd bcs[.w] pcrel16
4815 addx sz ea,rd bcs[.b] pcrel8
4816 and sz ea,rd blo[.w] pcrel16
4817 andc[.b] imm8,crb blo[.b] pcrel8
4818 andc[.w] imm16,sr bne[.w] pcrel16
4820 bra[.w] pcrel16 beq[.w] pcrel16
4821 bra[.b] pcrel8 beq[.b] pcrel8
4822 bt[.w] pcrel16 bvc[.w] pcrel16
4823 bt[.b] pcrel8 bvc[.b] pcrel8
4824 brn[.w] pcrel16 bvs[.w] pcrel16
4825 brn[.b] pcrel8 bvs[.b] pcrel8
4826 bf[.w] pcrel16 bpl[.w] pcrel16
4827 bf[.b] pcrel8 bpl[.b] pcrel8
4828 bhi[.w] pcrel16 bmi[.w] pcrel16
4829 bhi[.b] pcrel8 bmi[.b] pcrel8
4830 bls[.w] pcrel16 bge[.w] pcrel16
4831 bls[.b] pcrel8 bge[.b] pcrel8
4833 blt[.w] pcrel16 mov[:g][.b] imm8,ea_mem
4834 blt[.b] pcrel8 mov[:g][.w] imm16,ea_mem
4835 bgt[.w] pcrel16 movfpe[.b] ea,rd
4836 bgt[.b] pcrel8 movtpe[.b] rs,ea_noimm
4837 ble[.w] pcrel16 mulxu sz ea,rd
4838 ble[.b] pcrel8 neg sz ea
4839 bclr sz imm4,ea_noimm nop
4840 bclr sz rs,ea_noimm not sz ea
4841 bnot sz imm4,ea_noimm or sz ea,rd
4842 bnot sz rs,ea_noimm orc[.b] imm8,crb
4843 bset sz imm4,ea_noimm orc[.w] imm16,sr
4844 bset sz rs,ea_noimm pjmp abs24
4845 bsr[.b] pcrel8 pjmp @@rd
4846 bsr[.w] pcrel16 pjsr abs24
4847 btst sz imm4,ea_noimm pjsr @@rd
4848 btst sz rs,ea_noimm prtd imm8
4849 clr sz ea prtd imm16
4850 cmp[:e][.b] imm8,rd prts
4851 cmp[:i][.w] imm16,rd rotl sz ea
4852 cmp[:g].b imm8,ea_noimm rotr sz ea
4853 cmp[:g][.w] imm16,ea_noimm rotxl sz ea
4854 Cmp[:g] sz ea,rd rotxr sz ea
4856 divxu sz ea,rd rtd imm16
4858 exts[.b] rd scb/f rs,pcrel8
4859 extu[.b] rd scb/ne rs,pcrel8
4860 jmp @@rd scb/eq rs,pcrel8
4861 jmp @@(imm8,rd) shal sz ea
4862 jmp @@(imm16,rd) shar sz ea
4863 jmp abs16 shll sz ea
4865 jsr @@(imm8,rd) sleep
4866 jsr @@(imm16,rd) stc[.b] crb,ea_noimm
4867 jsr abs16 stc[.w] sr,ea_noimm
4868 ldm @@sp+,(rlist) stm (rlist),@@-sp
4869 link fp,imm8 sub sz ea,rd
4870 link fp,imm16 subs sz ea,rd
4871 mov[:e][.b] imm8,rd subx sz ea,rd
4872 mov[:i][.w] imm16,rd swap[.b] rd
4873 mov[:l][.w] abs8,rd tas[.b] ea
4874 mov[:l].b abs8,rd trapa imm4
4875 mov[:s][.w] rs,abs8 trap/vs
4876 mov[:s].b rs,abs8 tst sz ea
4877 mov[:f][.w] @@(disp8,fp),rd unlk fp
4878 mov[:f][.w] rs,@@(disp8,fp) xch[.w] rs,rd
4879 mov[:f].b @@(disp8,fp),rd xor sz ea,rd
4880 mov[:f].b rs,@@(disp8,fp) xorc.b imm8,crb
4881 mov[:g] sz rs,ea_mem xorc.w imm16,sr
4889 @node HPPA-Dependent
4890 @chapter HPPA Dependent Features
4894 * HPPA Notes:: Notes
4895 * HPPA Options:: Options
4896 * HPPA Syntax:: Syntax
4897 * HPPA Floating Point:: Floating Point
4898 * HPPA Directives:: HPPA Machine Directives
4899 * HPPA Opcodes:: Opcodes
4904 As a back end for GNU CC @code{@value{AS}} has been throughly tested and should
4905 work extremely well. We have tested it only minimally on hand written assembly
4906 code and no one has tested it much on the assembly output from the HP
4909 The format of the debugging sections has changed since the original
4910 @code{@value{AS}} port (version 1.3X) was released; therefore,
4911 you must rebuild all objects and libraries with the new
4912 assembler so that you can debug the final executable.
4914 The HPPA @code{@value{AS}} port generates a small subset of the relocations
4915 available in the SOM and ELF object file formats. Additional relocation
4916 support will be added as it becomes necessary.
4920 @code{@value{AS}} has no machine-dependent directives for the HPPA.
4925 The assembler syntax closely follows the HPPA instruction set
4926 reference manual; assembler directives and general syntax closely follow the
4927 HPPA assembly language reference manual with a few noteworthy differences.
4929 First a colon may immediately follow a label definition. This is
4930 simply for compatability with how most assembly language programmers
4933 Some obscure expression parsing problems may affect hand written code which
4934 uses the @code{spop} instructions, or code which makes significant
4935 use of the @code{!} line separator.
4937 @code{@value{AS}} is much less forgiving about missing arguments and other
4938 similar oversights. @code{@value{AS}} will flag missing arguments as
4939 syntax errors; this is regarded as a feature, not a bug.
4941 Finally, @code{@value{AS}} allows you to use an external symbol without
4942 explicitly importing the symbol. @emph{Warning:} in the future this will be
4943 an error for HPPA targets.
4945 Special characters for HPPA targets include:
4947 @samp{;} is the line comment character.
4949 @samp{!} can be used instead of a newline to separate statements.
4951 Since @samp{$} has no special meaning, you may use it in symbol names.
4953 @node HPPA Floating Point
4954 @section Floating Point
4955 @cindex floating point, HPPA (@sc{ieee})
4956 @cindex HPPA floating point (@sc{ieee})
4957 The HPPA family uses @sc{ieee} floating-point numbers.
4959 @node HPPA Directives
4960 @section HPPA Machine Directives
4961 For detailed information on the HPPA machine instruction set, see
4962 @cite{HP9000 Series 800 Assembly Language Reference Manual}
4965 @code{@value{AS}} does not support the following assembler directives
4966 found in the HP manual:
4977 @code{@value{AS}} supports one additional assembler directive for the
4978 HPPA: @code{.PARAM}. It conveys register argument locations for
4979 static functions. Its syntax closely follows the @code{.EXPORT} directive.
4983 For detailed information on the HPPA machine instruction set, see
4984 @cite{PA-RISC Architecture and Instruction Set Reference Manual}
4991 @chapter Hitachi SH Dependent Features
4995 * SH Options:: Options
4996 * SH Syntax:: Syntax
4997 * SH Floating Point:: Floating Point
4998 * SH Directives:: SH Machine Directives
4999 * SH Opcodes:: Opcodes
5005 @cindex SH options (none)
5006 @cindex options, SH (none)
5007 @code{@value{AS}} has no additional command-line options for the Hitachi
5014 * SH-Chars:: Special Characters
5015 * SH-Regs:: Register Names
5016 * SH-Addressing:: Addressing Modes
5020 @subsection Special Characters
5022 @cindex line comment character, SH
5023 @cindex SH line comment character
5024 @samp{!} is the line comment character.
5026 @cindex line separator, SH
5027 @cindex statement separator, SH
5028 @cindex SH line separator
5029 You can use @samp{;} instead of a newline to separate statements.
5031 @cindex symbol names, @samp{$} in
5032 @cindex @code{$} in symbol names
5033 Since @samp{$} has no special meaning, you may use it in symbol names.
5036 @subsection Register Names
5038 @cindex SH registers
5039 @cindex registers, SH
5040 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
5041 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, @samp{r7}, @samp{r8},
5042 @samp{r9}, @samp{r10}, @samp{r11}, @samp{r12}, @samp{r13}, @samp{r14},
5043 and @samp{r15} to refer to the SH registers.
5045 The SH also has these control registers:
5049 procedure register (holds return address)
5056 high and low multiply accumulator registers
5062 global base register
5065 vector base register (for interrupt vectors)
5069 @subsection Addressing Modes
5071 @cindex addressing modes, SH
5072 @cindex SH addressing modes
5073 @code{@value{AS}} understands the following addressing modes for the SH.
5074 @code{R@var{n}} in the following refers to any of the numbered
5075 registers, but @emph{not} the control registers.
5085 Register indirect with pre-decrement
5088 Register indirect with post-increment
5090 @item @@(@var{disp}, R@var{n})
5091 Register indirect with displacement
5093 @item @@(R0, R@var{n})
5096 @item @@(@var{disp}, GBR)
5103 @itemx @@(@var{disp}, PC)
5104 PC relative address (for branch or for addressing memory). The
5105 @code{@value{AS}} implementation allows you to use the simpler form
5106 @var{addr} anywhere a PC relative address is called for; the alternate
5107 form is supported for compatibility with other assemblers.
5113 @node SH Floating Point
5114 @section Floating Point
5116 @cindex floating point, SH (@sc{ieee})
5117 @cindex SH floating point (@sc{ieee})
5118 The SH family uses @sc{ieee} floating-point numbers.
5121 @section SH Machine Directives
5123 @cindex SH machine directives (none)
5124 @cindex machine directives, SH (none)
5125 @cindex @code{word} directive, SH
5126 @cindex @code{int} directive, SH
5127 @code{@value{AS}} has no machine-dependent directives for the SH.
5132 @cindex SH opcode summary
5133 @cindex opcode summary, SH
5134 @cindex mnemonics, SH
5135 @cindex instruction summary, SH
5136 For detailed information on the SH machine instruction set, see
5137 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
5139 @code{@value{AS}} implements all the standard SH opcodes. No additional
5140 pseudo-instructions are needed on this family. Note, however, that
5141 because @code{@value{AS}} supports a simpler form of PC-relative
5142 addressing, you may simply write (for example)
5149 where other assemblers might require an explicit displacement to
5150 @code{bar} from the program counter:
5153 mov.l @@(@var{disp}, PC)
5156 Here is a summary of SH opcodes:
5161 Rn @r{a numbered register}
5162 Rm @r{another numbered register}
5163 #imm @r{immediate data}
5164 disp @r{displacement}
5165 disp8 @r{8-bit displacement}
5166 disp12 @r{12-bit displacement}
5168 add #imm,Rn lds.l @@Rn+,PR
5169 add Rm,Rn mac.w @@Rm+,@@Rn+
5170 addc Rm,Rn mov #imm,Rn
5171 addv Rm,Rn mov Rm,Rn
5172 and #imm,R0 mov.b Rm,@@(R0,Rn)
5173 and Rm,Rn mov.b Rm,@@-Rn
5174 and.b #imm,@@(R0,GBR) mov.b Rm,@@Rn
5175 bf disp8 mov.b @@(disp,Rm),R0
5176 bra disp12 mov.b @@(disp,GBR),R0
5177 bsr disp12 mov.b @@(R0,Rm),Rn
5178 bt disp8 mov.b @@Rm+,Rn
5180 clrt mov.b R0,@@(disp,Rm)
5181 cmp/eq #imm,R0 mov.b R0,@@(disp,GBR)
5182 cmp/eq Rm,Rn mov.l Rm,@@(disp,Rn)
5183 cmp/ge Rm,Rn mov.l Rm,@@(R0,Rn)
5184 cmp/gt Rm,Rn mov.l Rm,@@-Rn
5185 cmp/hi Rm,Rn mov.l Rm,@@Rn
5186 cmp/hs Rm,Rn mov.l @@(disp,Rn),Rm
5187 cmp/pl Rn mov.l @@(disp,GBR),R0
5188 cmp/pz Rn mov.l @@(disp,PC),Rn
5189 cmp/str Rm,Rn mov.l @@(R0,Rm),Rn
5190 div0s Rm,Rn mov.l @@Rm+,Rn
5192 div1 Rm,Rn mov.l R0,@@(disp,GBR)
5193 exts.b Rm,Rn mov.w Rm,@@(R0,Rn)
5194 exts.w Rm,Rn mov.w Rm,@@-Rn
5195 extu.b Rm,Rn mov.w Rm,@@Rn
5196 extu.w Rm,Rn mov.w @@(disp,Rm),R0
5197 jmp @@Rn mov.w @@(disp,GBR),R0
5198 jsr @@Rn mov.w @@(disp,PC),Rn
5199 ldc Rn,GBR mov.w @@(R0,Rm),Rn
5200 ldc Rn,SR mov.w @@Rm+,Rn
5201 ldc Rn,VBR mov.w @@Rm,Rn
5202 ldc.l @@Rn+,GBR mov.w R0,@@(disp,Rm)
5203 ldc.l @@Rn+,SR mov.w R0,@@(disp,GBR)
5204 ldc.l @@Rn+,VBR mova @@(disp,PC),R0
5206 lds Rn,MACL muls Rm,Rn
5207 lds Rn,PR mulu Rm,Rn
5208 lds.l @@Rn+,MACH neg Rm,Rn
5209 lds.l @@Rn+,MACL negc Rm,Rn
5212 not Rm,Rn stc.l GBR,@@-Rn
5213 or #imm,R0 stc.l SR,@@-Rn
5214 or Rm,Rn stc.l VBR,@@-Rn
5215 or.b #imm,@@(R0,GBR) sts MACH,Rn
5216 rotcl Rn sts MACL,Rn
5218 rotl Rn sts.l MACH,@@-Rn
5219 rotr Rn sts.l MACL,@@-Rn
5224 shar Rn swap.b Rm,Rn
5225 shll Rn swap.w Rm,Rn
5226 shll16 Rn tas.b @@Rn
5228 shll8 Rn tst #imm,R0
5230 shlr16 Rn tst.b #imm,@@(R0,GBR)
5231 shlr2 Rn xor #imm,R0
5233 sleep xor.b #imm,@@(R0,GBR)
5234 stc GBR,Rn xtrct Rm,Rn
5248 @node i960-Dependent
5249 @chapter Intel 80960 Dependent Features
5252 @node Machine Dependencies
5253 @chapter Intel 80960 Dependent Features
5256 @cindex i960 support
5258 * Options-i960:: i960 Command-line Options
5259 * Floating Point-i960:: Floating Point
5260 * Directives-i960:: i960 Machine Directives
5261 * Opcodes for i960:: i960 Opcodes
5264 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
5265 @c long as they're not turned on for other machines than 960.
5269 @section i960 Command-line Options
5271 @cindex i960 options
5272 @cindex options, i960
5275 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
5276 @cindex i960 architecture options
5277 @cindex architecture options, i960
5278 @cindex @code{-A} options, i960
5279 Select the 80960 architecture. Instructions or features not supported
5280 by the selected architecture cause fatal errors.
5282 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
5283 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
5285 If none of these options is specified, @code{@value{AS}} will generate code for any
5286 instruction or feature that is supported by @emph{some} version of the
5287 960 (even if this means mixing architectures!). In principle,
5288 @code{@value{AS}} will attempt to deduce the minimal sufficient processor
5289 type if none is specified; depending on the object code format, the
5290 processor type may be recorded in the object file. If it is critical
5291 that the @code{@value{AS}} output match a specific architecture, specify that
5292 architecture explicitly.
5295 @cindex @code{-b} option, i960
5296 @cindex branch recording, i960
5297 @cindex i960 branch recording
5298 Add code to collect information about conditional branches taken, for
5299 later optimization using branch prediction bits. (The conditional branch
5300 instructions have branch prediction bits in the CA, CB, and CC
5301 architectures.) If @var{BR} represents a conditional branch instruction,
5302 the following represents the code generated by the assembler when
5303 @samp{-b} is specified:
5306 call @var{increment routine}
5307 .word 0 # pre-counter
5309 call @var{increment routine}
5310 .word 0 # post-counter
5313 The counter following a branch records the number of times that branch
5314 was @emph{not} taken; the differenc between the two counters is the
5315 number of times the branch @emph{was} taken.
5317 @cindex @code{gbr960}, i960 postprocessor
5318 @cindex branch statistics table, i960
5319 A table of every such @code{Label} is also generated, so that the
5320 external postprocessor @code{gbr960} (supplied by Intel) can locate all
5321 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
5322 this is a local symbol to permit collecting statistics for many separate
5323 object files. The table is word aligned, and begins with a two-word
5324 header. The first word, initialized to 0, is used in maintaining linked
5325 lists of branch tables. The second word is a count of the number of
5326 entries in the table, which follow immediately: each is a word, pointing
5327 to one of the labels illustrated above.
5331 @c END TEXI2ROFF-KILL
5333 +------------+------------+------------+ ... +------------+
5335 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
5337 +------------+------------+------------+ ... +------------+
5339 __BRANCH_TABLE__ layout
5345 \line{\leftskip=0pt\hskip\tableindent
5346 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
5347 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
5348 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
5350 @c END TEXI2ROFF-KILL
5352 The first word of the header is used to locate multiple branch tables,
5353 since each object file may contain one. Normally the links are
5354 maintained with a call to an initialization routine, placed at the
5355 beginning of each function in the file. The GNU C compiler will
5356 generate these calls automatically when you give it a @samp{-b} option.
5357 For further details, see the documentation of @samp{gbr960}.
5360 @cindex @code{-norelax} option, i960
5361 Normally, Compare-and-Branch instructions with targets that require
5362 displacements greater than 13 bits (or that have external targets) are
5363 replaced with the corresponding compare (or @samp{chkbit}) and branch
5364 instructions. You can use the @samp{-norelax} option to specify that
5365 @code{@value{AS}} should generate errors instead, if the target displacement
5366 is larger than 13 bits.
5368 This option does not affect the Compare-and-Jump instructions; the code
5369 emitted for them is @emph{always} adjusted when necessary (depending on
5370 displacement size), regardless of whether you use @samp{-norelax}.
5373 @node Floating Point-i960
5374 @section Floating Point
5376 @cindex floating point, i960 (@sc{ieee})
5377 @cindex i960 floating point (@sc{ieee})
5378 @code{@value{AS}} generates @sc{ieee} floating-point numbers for the directives
5379 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
5381 @node Directives-i960
5382 @section i960 Machine Directives
5384 @cindex machine directives, i960
5385 @cindex i960 machine directives
5388 @cindex @code{bss} directive, i960
5389 @item .bss @var{symbol}, @var{length}, @var{align}
5390 Reserve @var{length} bytes in the bss section for a local @var{symbol},
5391 aligned to the power of two specified by @var{align}. @var{length} and
5392 @var{align} must be positive absolute expressions. This directive
5393 differs from @samp{.lcomm} only in that it permits you to specify
5394 an alignment. @xref{Lcomm,,@code{.lcomm}}.
5398 @item .extended @var{flonums}
5399 @cindex @code{extended} directive, i960
5400 @code{.extended} expects zero or more flonums, separated by commas; for
5401 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
5402 floating-point number.
5404 @item .leafproc @var{call-lab}, @var{bal-lab}
5405 @cindex @code{leafproc} directive, i960
5406 You can use the @samp{.leafproc} directive in conjunction with the
5407 optimized @code{callj} instruction to enable faster calls of leaf
5408 procedures. If a procedure is known to call no other procedures, you
5409 may define an entry point that skips procedure prolog code (and that does
5410 not depend on system-supplied saved context), and declare it as the
5411 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
5412 entry point that goes through the normal prolog, you can specify that
5413 entry point as @var{call-lab}.
5415 A @samp{.leafproc} declaration is meant for use in conjunction with the
5416 optimized call instruction @samp{callj}; the directive records the data
5417 needed later to choose between converting the @samp{callj} into a
5418 @code{bal} or a @code{call}.
5420 @var{call-lab} is optional; if only one argument is present, or if the
5421 two arguments are identical, the single argument is assumed to be the
5422 @code{bal} entry point.
5424 @item .sysproc @var{name}, @var{index}
5425 @cindex @code{sysproc} directive, i960
5426 The @samp{.sysproc} directive defines a name for a system procedure.
5427 After you define it using @samp{.sysproc}, you can use @var{name} to
5428 refer to the system procedure identified by @var{index} when calling
5429 procedures with the optimized call instruction @samp{callj}.
5431 Both arguments are required; @var{index} must be between 0 and 31
5435 @node Opcodes for i960
5436 @section i960 Opcodes
5438 @cindex opcodes, i960
5439 @cindex i960 opcodes
5440 All Intel 960 machine instructions are supported;
5441 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
5442 selecting the instruction subset for a particular 960
5443 architecture.@refill
5445 Some opcodes are processed beyond simply emitting a single corresponding
5446 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
5447 instructions with target displacements larger than 13 bits.
5450 * callj-i960:: @code{callj}
5451 * Compare-and-branch-i960:: Compare-and-Branch
5455 @subsection @code{callj}
5457 @cindex @code{callj}, i960 pseudo-opcode
5458 @cindex i960 @code{callj} pseudo-opcode
5459 You can write @code{callj} to have the assembler or the linker determine
5460 the most appropriate form of subroutine call: @samp{call},
5461 @samp{bal}, or @samp{calls}. If the assembly source contains
5462 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
5463 defining the operand---then @code{@value{AS}} will translate the
5464 @code{callj}; if not, it will simply emit the @code{callj}, leaving it
5465 for the linker to resolve.
5467 @node Compare-and-branch-i960
5468 @subsection Compare-and-Branch
5470 @cindex i960 compare/branch instructions
5471 @cindex compare/branch instructions, i960
5472 The 960 architectures provide combined Compare-and-Branch instructions
5473 that permit you to store the branch target in the lower 13 bits of the
5474 instruction word itself. However, if you specify a branch target far
5475 enough away that its address won't fit in 13 bits, the assembler can
5476 either issue an error, or convert your Compare-and-Branch instruction
5477 into separate instructions to do the compare and the branch.
5479 @cindex compare and jump expansions, i960
5480 @cindex i960 compare and jump expansions
5481 Whether @code{@value{AS}} gives an error or expands the instruction depends
5482 on two choices you can make: whether you use the @samp{-norelax} option,
5483 and whether you use a ``Compare and Branch'' instruction or a ``Compare
5484 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
5485 expanded if necessary; the ``Branch'' instructions are expanded when
5486 necessary @emph{unless} you specify @code{-norelax}---in which case
5487 @code{@value{AS}} gives an error instead.
5489 These are the Compare-and-Branch instructions, their ``Jump'' variants,
5490 and the instruction pairs they may expand into:
5494 @c END TEXI2ROFF-KILL
5497 Branch Jump Expanded to
5498 ------ ------ ------------
5501 cmpibe cmpije cmpi; be
5502 cmpibg cmpijg cmpi; bg
5503 cmpibge cmpijge cmpi; bge
5504 cmpibl cmpijl cmpi; bl
5505 cmpible cmpijle cmpi; ble
5506 cmpibno cmpijno cmpi; bno
5507 cmpibne cmpijne cmpi; bne
5508 cmpibo cmpijo cmpi; bo
5509 cmpobe cmpoje cmpo; be
5510 cmpobg cmpojg cmpo; bg
5511 cmpobge cmpojge cmpo; bge
5512 cmpobl cmpojl cmpo; bl
5513 cmpoble cmpojle cmpo; ble
5514 cmpobne cmpojne cmpo; bne
5520 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
5521 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
5522 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
5523 bbc& & chkbit; bno\cr
5524 bbs& & chkbit; bo\cr
5525 cmpibe& cmpije& cmpi; be\cr
5526 cmpibg& cmpijg& cmpi; bg\cr
5527 cmpibge& cmpijge& cmpi; bge\cr
5528 cmpibl& cmpijl& cmpi; bl\cr
5529 cmpible& cmpijle& cmpi; ble\cr
5530 cmpibno& cmpijno& cmpi; bno\cr
5531 cmpibne& cmpijne& cmpi; bne\cr
5532 cmpibo& cmpijo& cmpi; bo\cr
5533 cmpobe& cmpoje& cmpo; be\cr
5534 cmpobg& cmpojg& cmpo; bg\cr
5535 cmpobge& cmpojge& cmpo; bge\cr
5536 cmpobl& cmpojl& cmpo; bl\cr
5537 cmpoble& cmpojle& cmpo; ble\cr
5538 cmpobne& cmpojne& cmpo; bne\cr}
5540 @c END TEXI2ROFF-KILL
5546 @node M68K-Dependent
5547 @chapter M680x0 Dependent Features
5550 @node Machine Dependencies
5551 @chapter M680x0 Dependent Features
5554 @cindex M680x0 support
5556 * M68K-Opts:: M680x0 Options
5557 * M68K-Syntax:: Syntax
5558 * M68K-Moto-Syntax:: Motorola Syntax
5559 * M68K-Float:: Floating Point
5560 * M68K-Directives:: 680x0 Machine Directives
5561 * M68K-opcodes:: Opcodes
5565 @section M680x0 Options
5567 @cindex options, M680x0
5568 @cindex M680x0 options
5569 The Motorola 680x0 version of @code{@value{AS}} has two machine dependent options.
5570 One shortens undefined references from 32 to 16 bits, while the
5571 other is used to tell @code{@value{AS}} what kind of machine it is
5574 @cindex @code{-l} option, M680x0
5575 You can use the @kbd{-l} option to shorten the size of references to
5576 undefined symbols. If the @kbd{-l} option is not given, references to
5577 undefined symbols will be a full long (32 bits) wide. (Since @code{@value{AS}}
5578 cannot know where these symbols will end up, @code{@value{AS}} can only allocate
5579 space for the linker to fill in later. Since @code{@value{AS}} doesn't know how
5580 far away these symbols will be, it allocates as much space as it can.)
5581 If this option is given, the references will only be one word wide (16
5582 bits). This may be useful if you want the object file to be as small as
5583 possible, and you know that the relevant symbols will be less than 17
5586 @cindex @code{-m68000} and related options
5587 @cindex architecture options, M680x0
5588 @cindex M680x0 architecture options
5589 The 680x0 version of @code{@value{AS}} is most frequently used to assemble
5590 programs for the Motorola MC68020 microprocessor. Occasionally it is
5591 used to assemble programs for the mostly similar, but slightly different
5592 MC68000 or MC68010 microprocessors. You can give @code{@value{AS}} the options
5593 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
5594 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
5601 This syntax for the Motorola 680x0 was developed at @sc{mit}.
5603 @cindex M680x0 syntax
5604 @cindex syntax, M680x0
5605 @cindex M680x0 size modifiers
5606 @cindex size modifiers, M680x0
5607 The 680x0 version of @code{@value{AS}} uses syntax similar to the Sun
5608 assembler. Intervening periods are now ignored; for example, @samp{movl}
5609 is equivalent to @samp{move.l}.
5612 If @code{@value{AS}} is compiled with SUN_ASM_SYNTAX defined, it will
5613 also allow Sun-style local labels of the form @samp{1$} through
5617 In the following table @dfn{apc} stands for any of the address
5618 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
5619 Program Counter (@samp{pc}), or the zero-address relative to the
5620 program counter (@samp{zpc}).
5622 @cindex M680x0 addressing modes
5623 @cindex addressing modes, M680x0
5624 The following addressing modes are understood:
5627 @samp{#@var{digits}}
5630 @samp{d0} through @samp{d7}
5632 @item Address Register
5633 @samp{a0} through @samp{a7}
5635 @item Address Register Indirect
5636 @samp{a0@@} through @samp{a7@@}@*
5637 @samp{a7} is also known as @samp{sp}, i.e. the Stack Pointer. @code{a6}
5638 is also known as @samp{fp}, the Frame Pointer.
5640 @item Address Register Postincrement
5641 @samp{a0@@+} through @samp{a7@@+}
5643 @item Address Register Predecrement
5644 @samp{a0@@-} through @samp{a7@@-}
5646 @item Indirect Plus Offset
5647 @samp{@var{apc}@@(@var{digits})}
5650 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
5652 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
5655 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
5657 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
5660 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5662 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5664 @item Memory Indirect
5665 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
5668 @samp{@var{symbol}}, or @samp{@var{digits}}
5670 @c pesch@cygnus.com: gnu, rich concur the following needs careful
5671 @c research before documenting.
5672 , or either of the above followed
5673 by @samp{:b}, @samp{:w}, or @samp{:l}.
5677 For some configurations, especially those where the compiler normally
5678 does not prepend an underscore to the names of user variables, the
5679 assembler requires a @samp{%} before any use of a register name. This
5680 is intended to let the assembler distinguish between user variables and
5681 registers named @samp{a0} through @samp{a7}, et cetera. The @samp{%} is
5682 always accepted, but is only required for some configurations, notably
5685 @node M68K-Moto-Syntax
5686 @section Motorola Syntax
5688 @cindex Motorola syntax for the 680x0
5689 @cindex alternate syntax for the 680x0
5691 The standard Motorola syntax for this chip differs from the syntax
5692 already discussed (@pxref{M68K-Syntax,,Syntax}). @code{@value{AS}} can
5693 accept both kinds of syntax, even within a single instruction. The
5694 syntaxes are fully compatible, because the Motorola syntax never uses
5695 the @samp{@@} character and the @sc{mit} syntax always does, except in
5696 cases where the syntaxes are identical.
5698 @cindex M680x0 syntax
5699 @cindex syntax, M680x0
5700 In particular, you may write or generate M68K assembler with the
5701 following conventions:
5703 (In the following table @dfn{apc} stands for any of the address
5704 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
5705 Program Counter (@samp{pc}), or the zero-address relative to the
5706 program counter (@samp{zpc}).)
5708 @cindex M680x0 addressing modes
5709 @cindex addressing modes, M680x0
5710 The following additional addressing modes are understood:
5712 @item Address Register Indirect
5713 @samp{a0} through @samp{a7}@*
5714 @samp{a7} is also known as @samp{sp}, i.e. the Stack Pointer. @code{a6}
5715 is also known as @samp{fp}, the Frame Pointer.
5717 @item Address Register Postincrement
5718 @samp{(a0)+} through @samp{(a7)+}
5720 @item Address Register Predecrement
5721 @samp{-(a0)} through @samp{-(a7)}
5723 @item Indirect Plus Offset
5724 @samp{@var{digits}(@var{apc})}
5727 @samp{@var{digits}(@var{apc},(@var{register}.@var{size}*@var{scale})}@*
5728 or @samp{(@var{apc},@var{register}.@var{size}*@var{scale})}@*
5729 In either case, @var{size} and @var{scale} are optional
5730 (@var{scale} defaults to @samp{1}, @var{size} defaults to @samp{l}).
5731 @var{scale} can be @samp{1}, @samp{2}, @samp{4}, or @samp{8}.
5732 @var{size} can be @samp{w} or @samp{l}. @var{scale} is only supported
5733 on the 68020 and greater.
5737 @section Floating Point
5739 @cindex floating point, M680x0
5740 @cindex M680x0 floating point
5741 @c FIXME is this "not too well tested" crud STILL true?
5742 The floating point code is not too well tested, and may have
5745 Packed decimal (P) format floating literals are not supported.
5746 Feel free to add the code!
5748 The floating point formats generated by directives are these.
5752 @cindex @code{float} directive, M680x0
5753 @code{Single} precision floating point constants.
5756 @cindex @code{double} directive, M680x0
5757 @code{Double} precision floating point constants.
5760 There is no directive to produce regions of memory holding
5761 extended precision numbers, however they can be used as
5762 immediate operands to floating-point instructions. Adding a
5763 directive to create extended precision numbers would not be
5764 hard, but it has not yet seemed necessary.
5766 @node M68K-Directives
5767 @section 680x0 Machine Directives
5769 @cindex M680x0 directives
5770 @cindex directives, M680x0
5771 In order to be compatible with the Sun assembler the 680x0 assembler
5772 understands the following directives.
5776 @cindex @code{data1} directive, M680x0
5777 This directive is identical to a @code{.data 1} directive.
5780 @cindex @code{data2} directive, M680x0
5781 This directive is identical to a @code{.data 2} directive.
5784 @cindex @code{even} directive, M680x0
5785 This directive is identical to a @code{.align 1} directive.
5786 @c Is this true? does it work???
5789 @cindex @code{skip} directive, M680x0
5790 This directive is identical to a @code{.space} directive.
5796 @cindex M680x0 opcodes
5797 @cindex opcodes, M680x0
5798 @cindex instruction set, M680x0
5799 @c pesch@cygnus.com: I don't see any point in the following
5800 @c paragraph. Bugs are bugs; how does saying this
5803 Danger: Several bugs have been found in the opcode table (and
5804 fixed). More bugs may exist. Be careful when using obscure
5809 * M68K-Branch:: Branch Improvement
5810 * M68K-Chars:: Special Characters
5814 @subsection Branch Improvement
5816 @cindex pseudo-opcodes, M680x0
5817 @cindex M680x0 pseudo-opcodes
5818 @cindex branch improvement, M680x0
5819 @cindex M680x0 branch improvement
5820 Certain pseudo opcodes are permitted for branch instructions.
5821 They expand to the shortest branch instruction that will reach the
5822 target. Generally these mnemonics are made by substituting @samp{j} for
5823 @samp{b} at the start of a Motorola mnemonic.
5825 The following table summarizes the pseudo-operations. A @code{*} flags
5826 cases that are more fully described after the table:
5830 +-------------------------------------------------
5832 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
5833 +-------------------------------------------------
5834 jbsr |bsrs bsr bsrl jsr jsr
5835 jra |bras bra bral jmp jmp
5836 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
5837 * dbXX |dbXX dbXX dbXX; bra; jmpl
5838 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
5841 NX: negative of condition XX
5844 @center @code{*}---see full description below
5849 These are the simplest jump pseudo-operations; they always map to one
5850 particular machine instruction, depending on the displacement to the
5854 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
5855 where @var{XX} is a conditional branch or condition-code test. The full
5856 list of pseudo-ops in this family is:
5858 jhi jls jcc jcs jne jeq jvc
5859 jvs jpl jmi jge jlt jgt jle
5862 For the cases of non-PC relative displacements and long displacements on
5863 the 68000 or 68010, @code{@value{AS}} will issue a longer code fragment in terms of
5864 @var{NX}, the opposite condition to @var{XX}. For example, for the
5865 non-PC relative case:
5877 The full family of pseudo-operations covered here is
5879 dbhi dbls dbcc dbcs dbne dbeq dbvc
5880 dbvs dbpl dbmi dbge dblt dbgt dble
5884 Other than for word and byte displacements, when the source reads
5885 @samp{db@var{XX} foo}, @code{@value{AS}} will emit
5894 This family includes
5896 fjne fjeq fjge fjlt fjgt fjle fjf
5897 fjt fjgl fjgle fjnge fjngl fjngle fjngt
5898 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
5899 fjor fjseq fjsf fjsne fjst fjueq fjuge
5900 fjugt fjule fjult fjun
5903 For branch targets that are not PC relative, @code{@value{AS}} emits
5909 when it encounters @samp{fj@var{XX} foo}.
5914 @subsection Special Characters
5916 @cindex special characters, M680x0
5917 @cindex M680x0 immediate character
5918 @cindex immediate character, M680x0
5919 @cindex M680x0 line comment character
5920 @cindex line comment character, M680x0
5921 @cindex comments, M680x0
5922 The immediate character is @samp{#} for Sun compatibility. The
5923 line-comment character is @samp{|}. If a @samp{#} appears at the
5924 beginning of a line, it is treated as a comment unless it looks like
5925 @samp{# line file}, in which case it is treated normally.
5929 @c FIXME! Stop ignoring when filled in.
5934 The 32x32 version of @code{@value{AS}} accepts a @kbd{-m32032} option to
5935 specify thiat it is compiling for a 32032 processor, or a
5936 @kbd{-m32532} to specify that it is compiling for a 32532 option.
5937 The default (if neither is specified) is chosen when the assembler
5941 I don't know anything about the 32x32 syntax assembled by
5942 @code{@value{AS}}. Someone who undersands the processor (I've never seen
5943 one) and the possible syntaxes should write this section.
5945 @section Floating Point
5946 The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{AS}}
5947 will only create single or double precision values. I don't know if the
5948 32x32 understands extended precision numbers.
5950 @section 32x32 Machine Directives
5951 The 32x32 has no machine dependent directives.
5957 @node Sparc-Dependent
5958 @chapter SPARC Dependent Features
5961 @node Machine Dependencies
5962 @chapter SPARC Dependent Features
5965 @cindex SPARC support
5967 * Sparc-Opts:: Options
5968 * Sparc-Float:: Floating Point
5969 * Sparc-Directives:: Sparc Machine Directives
5975 @cindex options for SPARC
5976 @cindex SPARC options
5977 @cindex architectures, SPARC
5978 @cindex SPARC architectures
5979 The SPARC chip family includes several successive levels (or other
5980 variants) of chip, using the same core instruction set, but including
5981 a few additional instructions at each level.
5983 By default, @code{@value{AS}} assumes the core instruction set (SPARC
5984 v6), but ``bumps'' the architecture level as needed: it switches to
5985 successively higher architectures as it encounters instructions that
5986 only exist in the higher levels.
5989 @item -Av6 | -Av7 | -Av8 | -Asparclite
5994 Use one of the @samp{-A} options to select one of the SPARC
5995 architectures explicitly. If you select an architecture explicitly,
5996 @code{@value{AS}} reports a fatal error if it encounters an instruction
5997 or feature requiring a higher level.
6000 Permit the assembler to ``bump'' the architecture level as required, but
6001 warn whenever it is necessary to switch to another level.
6005 @c FIXME: (sparc) Fill in "syntax" section!
6006 @c subsection syntax
6007 I don't know anything about Sparc syntax. Someone who does
6008 will have to write this section.
6012 @section Floating Point
6014 @cindex floating point, SPARC (@sc{ieee})
6015 @cindex SPARC floating point (@sc{ieee})
6016 The Sparc uses @sc{ieee} floating-point numbers.
6018 @node Sparc-Directives
6019 @section Sparc Machine Directives
6021 @cindex SPARC machine directives
6022 @cindex machine directives, SPARC
6023 The Sparc version of @code{@value{AS}} supports the following additional
6028 @cindex @code{common} directive, SPARC
6029 This must be followed by a symbol name, a positive number, and
6030 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
6031 syntax is different.
6034 @cindex @code{half} directive, SPARC
6035 This is functionally identical to @code{.short}.
6038 @cindex @code{proc} directive, SPARC
6039 This directive is ignored. Any text following it on the same
6040 line is also ignored.
6043 @cindex @code{reserve} directive, SPARC
6044 This must be followed by a symbol name, a positive number, and
6045 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
6046 syntax is different.
6049 @cindex @code{seg} directive, SPARC
6050 This must be followed by @code{"text"}, @code{"data"}, or
6051 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
6055 @cindex @code{skip} directive, SPARC
6056 This is functionally identical to the @code{.space} directive.
6059 @cindex @code{word} directive, SPARC
6060 On the Sparc, the .word directive produces 32 bit values,
6061 instead of the 16 bit values it produces on many other machines.
6068 @node i386-Dependent
6069 @chapter 80386 Dependent Features
6072 @node Machine Dependencies
6073 @chapter 80386 Dependent Features
6076 @cindex i386 support
6077 @cindex i80306 support
6079 * i386-Options:: Options
6080 * i386-Syntax:: AT&T Syntax versus Intel Syntax
6081 * i386-Opcodes:: Opcode Naming
6082 * i386-Regs:: Register Naming
6083 * i386-prefixes:: Opcode Prefixes
6084 * i386-Memory:: Memory References
6085 * i386-jumps:: Handling of Jump Instructions
6086 * i386-Float:: Floating Point
6087 * i386-Notes:: Notes
6093 @cindex options for i386 (none)
6094 @cindex i386 options (none)
6095 The 80386 has no machine dependent options.
6098 @section AT&T Syntax versus Intel Syntax
6100 @cindex i386 syntax compatibility
6101 @cindex syntax compatibility, i386
6102 In order to maintain compatibility with the output of @code{@value{GCC}},
6103 @code{@value{AS}} supports AT&T System V/386 assembler syntax. This is quite
6104 different from Intel syntax. We mention these differences because
6105 almost all 80386 documents used only Intel syntax. Notable differences
6106 between the two syntaxes are:
6110 @cindex immediate operands, i386
6111 @cindex i386 immediate operands
6112 @cindex register operands, i386
6113 @cindex i386 register operands
6114 @cindex jump/call operands, i386
6115 @cindex i386 jump/call operands
6116 @cindex operand delimiters, i386
6117 AT&T immediate operands are preceded by @samp{$}; Intel immediate
6118 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
6119 AT&T register operands are preceded by @samp{%}; Intel register operands
6120 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
6121 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
6124 @cindex i386 source, destination operands
6125 @cindex source, destination operands; i386
6126 AT&T and Intel syntax use the opposite order for source and destination
6127 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
6128 @samp{source, dest} convention is maintained for compatibility with
6129 previous Unix assemblers.
6132 @cindex opcode suffixes, i386
6133 @cindex sizes operands, i386
6134 @cindex i386 size suffixes
6135 In AT&T syntax the size of memory operands is determined from the last
6136 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
6137 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
6138 memory references. Intel syntax accomplishes this by prefixes memory
6139 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
6140 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
6141 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
6144 @cindex return instructions, i386
6145 @cindex i386 jump, call, return
6146 Immediate form long jumps and calls are
6147 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
6149 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
6151 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
6152 @samp{ret far @var{stack-adjust}}.
6155 @cindex sections, i386
6156 @cindex i386 sections
6157 The AT&T assembler does not provide support for multiple section
6158 programs. Unix style systems expect all programs to be single sections.
6162 @section Opcode Naming
6164 @cindex i386 opcode naming
6165 @cindex opcode naming, i386
6166 Opcode names are suffixed with one character modifiers which specify the
6167 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
6168 byte, word, and long operands. If no suffix is specified by an
6169 instruction and it contains no memory operands then @code{@value{AS}} tries to
6170 fill in the missing suffix based on the destination register operand
6171 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
6172 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
6173 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
6174 assembler which assumes that a missing opcode suffix implies long
6175 operand size. (This incompatibility does not affect compiler output
6176 since compilers always explicitly specify the opcode suffix.)
6178 Almost all opcodes have the same names in AT&T and Intel format. There
6179 are a few exceptions. The sign extend and zero extend instructions need
6180 two sizes to specify them. They need a size to sign/zero extend
6181 @emph{from} and a size to zero extend @emph{to}. This is accomplished
6182 by using two opcode suffixes in AT&T syntax. Base names for sign extend
6183 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
6184 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
6185 suffixes are tacked on to this base name, the @emph{from} suffix before
6186 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
6187 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
6188 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
6189 and @samp{wl} (from word to long).
6191 @cindex conversion instructions, i386
6192 @cindex i386 conversion instructions
6193 The Intel-syntax conversion instructions
6197 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
6200 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
6203 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
6206 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
6210 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
6211 AT&T naming. @code{@value{AS}} accepts either naming for these instructions.
6213 @cindex jump instructions, i386
6214 @cindex call instructions, i386
6215 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
6216 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
6220 @section Register Naming
6222 @cindex i386 registers
6223 @cindex registers, i386
6224 Register operands are always prefixes with @samp{%}. The 80386 registers
6229 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
6230 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
6231 frame pointer), and @samp{%esp} (the stack pointer).
6234 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
6235 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
6238 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
6239 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
6240 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
6241 @samp{%cx}, and @samp{%dx})
6244 the 6 section registers @samp{%cs} (code section), @samp{%ds}
6245 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
6249 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
6253 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
6254 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
6257 the 2 test registers @samp{%tr6} and @samp{%tr7}.
6260 the 8 floating point register stack @samp{%st} or equivalently
6261 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
6262 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
6266 @section Opcode Prefixes
6268 @cindex i386 opcode prefixes
6269 @cindex opcode prefixes, i386
6270 @cindex prefixes, i386
6271 Opcode prefixes are used to modify the following opcode. They are used
6272 to repeat string instructions, to provide section overrides, to perform
6273 bus lock operations, and to give operand and address size (16-bit
6274 operands are specified in an instruction by prefixing what would
6275 normally be 32-bit operands with a ``operand size'' opcode prefix).
6276 Opcode prefixes are usually given as single-line instructions with no
6277 operands, and must directly precede the instruction they act upon. For
6278 example, the @samp{scas} (scan string) instruction is repeated with:
6284 Here is a list of opcode prefixes:
6288 @cindex section override prefixes, i386
6289 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
6290 @samp{fs}, @samp{gs}. These are automatically added by specifying
6291 using the @var{section}:@var{memory-operand} form for memory references.
6294 @cindex size prefixes, i386
6295 Operand/Address size prefixes @samp{data16} and @samp{addr16}
6296 change 32-bit operands/addresses into 16-bit operands/addresses. Note
6297 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
6298 are not supported (yet).
6301 @cindex bus lock prefixes, i386
6302 @cindex inhibiting interrupts, i386
6303 The bus lock prefix @samp{lock} inhibits interrupts during
6304 execution of the instruction it precedes. (This is only valid with
6305 certain instructions; see a 80386 manual for details).
6308 @cindex coprocessor wait, i386
6309 The wait for coprocessor prefix @samp{wait} waits for the
6310 coprocessor to complete the current instruction. This should never be
6311 needed for the 80386/80387 combination.
6314 @cindex repeat prefixes, i386
6315 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
6316 to string instructions to make them repeat @samp{%ecx} times.
6320 @section Memory References
6322 @cindex i386 memory references
6323 @cindex memory references, i386
6324 An Intel syntax indirect memory reference of the form
6327 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
6331 is translated into the AT&T syntax
6334 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
6338 where @var{base} and @var{index} are the optional 32-bit base and
6339 index registers, @var{disp} is the optional displacement, and
6340 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
6341 to calculate the address of the operand. If no @var{scale} is
6342 specified, @var{scale} is taken to be 1. @var{section} specifies the
6343 optional section register for the memory operand, and may override the
6344 default section register (see a 80386 manual for section register
6345 defaults). Note that section overrides in AT&T syntax @emph{must} have
6346 be preceded by a @samp{%}. If you specify a section override which
6347 coincides with the default section register, @code{@value{AS}} will @emph{not}
6348 output any section register override prefixes to assemble the given
6349 instruction. Thus, section overrides can be specified to emphasize which
6350 section register is used for a given memory operand.
6352 Here are some examples of Intel and AT&T style memory references:
6355 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
6356 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
6357 missing, and the default section is used (@samp{%ss} for addressing with
6358 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
6360 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
6361 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
6362 @samp{foo}. All other fields are missing. The section register here
6363 defaults to @samp{%ds}.
6365 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
6366 This uses the value pointed to by @samp{foo} as a memory operand.
6367 Note that @var{base} and @var{index} are both missing, but there is only
6368 @emph{one} @samp{,}. This is a syntactic exception.
6370 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
6371 This selects the contents of the variable @samp{foo} with section
6372 register @var{section} being @samp{%gs}.
6375 Absolute (as opposed to PC relative) call and jump operands must be
6376 prefixed with @samp{*}. If no @samp{*} is specified, @code{@value{AS}} will
6377 always choose PC relative addressing for jump/call labels.
6379 Any instruction that has a memory operand @emph{must} specify its size (byte,
6380 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
6384 @section Handling of Jump Instructions
6386 @cindex jump optimization, i386
6387 @cindex i386 jump optimization
6388 Jump instructions are always optimized to use the smallest possible
6389 displacements. This is accomplished by using byte (8-bit) displacement
6390 jumps whenever the target is sufficiently close. If a byte displacement
6391 is insufficient a long (32-bit) displacement is used. We do not support
6392 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
6393 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
6394 @samp{%eip} to 16 bits after the word displacement is added.
6396 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
6397 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in
6398 byte displacements, so that it is possible that use of these
6399 instructions (@code{@value{GCC}} does not use them) will cause the assembler to
6400 print an error message (and generate incorrect code). The AT&T 80386
6401 assembler tries to get around this problem by expanding @samp{jcxz foo} to
6410 @section Floating Point
6412 @cindex i386 floating point
6413 @cindex floating point, i386
6414 All 80387 floating point types except packed BCD are supported.
6415 (BCD support may be added without much difficulty). These data
6416 types are 16-, 32-, and 64- bit integers, and single (32-bit),
6417 double (64-bit), and extended (80-bit) precision floating point.
6418 Each supported type has an opcode suffix and a constructor
6419 associated with it. Opcode suffixes specify operand's data
6420 types. Constructors build these data types into memory.
6424 @cindex @code{float} directive, i386
6425 @cindex @code{single} directive, i386
6426 @cindex @code{double} directive, i386
6427 @cindex @code{tfloat} directive, i386
6428 Floating point constructors are @samp{.float} or @samp{.single},
6429 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
6430 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
6431 @samp{t} stands for temporary real, and that the 80387 only supports
6432 this format via the @samp{fldt} (load temporary real to stack top) and
6433 @samp{fstpt} (store temporary real and pop stack) instructions.
6436 @cindex @code{word} directive, i386
6437 @cindex @code{long} directive, i386
6438 @cindex @code{int} directive, i386
6439 @cindex @code{quad} directive, i386
6440 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
6441 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
6442 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
6443 (quad). As with the temporary real format the 64-bit @samp{q} format is
6444 only present in the @samp{fildq} (load quad integer to stack top) and
6445 @samp{fistpq} (store quad integer and pop stack) instructions.
6448 Register to register operations do not require opcode suffixes,
6449 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
6451 @cindex i386 @code{fwait} instruction
6452 @cindex @code{fwait instruction}, i386
6453 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
6454 instructions are almost never needed (this is not the case for the
6455 80286/80287 and 8086/8087 combinations). Therefore, @code{@value{AS}} suppresses
6456 the @samp{fwait} instruction whenever it is implicitly selected by one
6457 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
6458 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
6459 instructions are made equivalent to @samp{f@dots{}} instructions. If
6460 @samp{fwait} is desired it must be explicitly coded.
6465 @cindex i386 @code{mul}, @code{imul} instructions
6466 @cindex @code{mul} instruction, i386
6467 @cindex @code{imul} instruction, i386
6468 There is some trickery concerning the @samp{mul} and @samp{imul}
6469 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
6470 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
6471 for @samp{imul}) can be output only in the one operand form. Thus,
6472 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
6473 the expanding multiply would clobber the @samp{%edx} register, and this
6474 would confuse @code{@value{GCC}} output. Use @samp{imul %ebx} to get the
6475 64-bit product in @samp{%edx:%eax}.
6477 We have added a two operand form of @samp{imul} when the first operand
6478 is an immediate mode expression and the second operand is a register.
6479 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
6480 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
6487 @node Z8000-Dependent
6488 @chapter Z8000 Dependent Features
6491 @node Machine Dependencies
6492 @chapter Z8000 Dependent Features
6495 @cindex Z8000 support
6496 The Z8000 @value{AS} supports both members of the Z8000 family: the
6497 unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with
6500 When the assembler is in unsegmented mode (specified with the
6501 @code{unsegm} directive), an address will take up one word (16 bit)
6502 sized register. When the assembler is in segmented mode (specified with
6503 the @code{segm} directive), a 24-bit address takes up a long (32 bit)
6504 register. @xref{Z8000 Directives,,Assembler Directives for the Z8000},
6505 for a list of other Z8000 specific assembler directives.
6508 * Z8000 Options:: No special command-line options for Z8000
6509 * Z8000 Syntax:: Assembler syntax for the Z8000
6510 * Z8000 Directives:: Special directives for the Z8000
6511 * Z8000 Opcodes:: Opcodes
6517 @cindex Z8000 options
6518 @cindex options, Z8000
6519 @code{@value{AS}} has no additional command-line options for the Zilog
6525 * Z8000-Chars:: Special Characters
6526 * Z8000-Regs:: Register Names
6527 * Z8000-Addressing:: Addressing Modes
6531 @subsection Special Characters
6533 @cindex line comment character, Z8000
6534 @cindex Z8000 line comment character
6535 @samp{!} is the line comment character.
6537 @cindex line separator, Z8000
6538 @cindex statement separator, Z8000
6539 @cindex Z8000 line separator
6540 You can use @samp{;} instead of a newline to separate statements.
6543 @subsection Register Names
6545 @cindex Z8000 registers
6546 @cindex registers, Z8000
6547 The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer
6548 to different sized groups of registers by register number, with the
6549 prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and
6550 @samp{rq} for 64 bit registers. You can also refer to the contents of
6551 the first eight (of the sixteen 16 bit registers) by bytes. They are
6552 named @samp{r@var{n}h} and @samp{r@var{n}l}.
6555 @exdent @emph{byte registers}
6556 r0l r0h r1h r1l r2h r2l r3h r3l
6557 r4h r4l r5h r5l r6h r6l r7h r7l
6559 @exdent @emph{word registers}
6560 r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15
6562 @exdent @emph{long word registers}
6563 rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14
6565 @exdent @emph{quad word registers}
6569 @node Z8000-Addressing
6570 @subsection Addressing Modes
6572 @cindex addressing modes, Z8000
6573 @cindex Z800 addressing modes
6574 @value{AS} understands the following addressing modes for the Z8000:
6584 Direct: the 16 bit or 24 bit address (depending on whether the assembler
6585 is in segmented or unsegmented mode) of the operand is in the instruction.
6587 @item address(r@var{n})
6588 Indexed: the 16 or 24 bit address is added to the 16 bit register to produce
6589 the final address in memory of the operand.
6591 @item r@var{n}(#@var{imm})
6592 Base Address: the 16 or 24 bit register is added to the 16 bit sign
6593 extended immediate displacement to produce the final address in memory
6596 @item r@var{n}(r@var{m})
6597 Base Index: the 16 or 24 bit register r@var{n} is added to the sign
6598 extended 16 bit index register r@var{m} to produce the final address in
6599 memory of the operand.
6602 Immediate data @var{xx}.
6605 @node Z8000 Directives
6606 @section Assembler Directives for the Z8000
6608 @cindex Z8000 directives
6609 @cindex directives, Z8000
6610 The Z8000 port of @value{AS} includes these additional assembler directives,
6611 for compatibility with other Z8000 assemblers. As shown, these do not
6612 begin with @samp{.} (unlike the ordinary @value{AS} directives).
6617 Generates code for the segmented Z8001.
6621 Generates code for the unsegmented Z8002.
6625 Synonym for @code{.file}
6629 Synonum for @code{.global}
6633 Synonym for @code{.word}
6637 Synonym for @code{.long}
6641 Synonym for @code{.byte}
6645 Assemble a string. @code{sval} expects one string literal, delimited by
6646 single quotes. It assembles each byte of the string into consecutive
6647 addresses. You can use the escape sequence @samp{%@var{xx}} (where
6648 @var{xx} represents a two-digit hexadecimal number) to represent the
6649 character whose @sc{ascii} value is @var{xx}. Use this feature to
6650 describe single quote and other characters that may not appear in string
6651 literals as themselves. For example, the C statement @w{@samp{char *a =
6652 "he said \"it's 50% off\"";}} is represented in Z8000 assembly language
6653 (shown with the assembler output in hex at the left) as
6657 @let@nonarrowing=@comment
6660 68652073 sval 'he said %22it%27s 50%25 off%22%00'
6673 synonym for @code{.section}
6677 synonym for @code{.space}
6681 synonym for @code{.align 1}
6687 @cindex Z8000 opcode summary
6688 @cindex opcode summary, Z8000
6689 @cindex mnemonics, Z8000
6690 @cindex instruction summary, Z8000
6691 For detailed information on the Z8000 machine instruction set, see
6692 @cite{Z8000 Technical Manual}.
6694 The following table summarizes the opcodes and their arguments:
6697 @let@nonarrowing=@comment
6701 rs @r{16 bit source register}
6702 rd @r{16 bit destination register}
6703 rbs @r{8 bit source register}
6704 rbd @r{8 bit destination register}
6705 rrs @r{32 bit source register}
6706 rrd @r{32 bit destination register}
6707 rqs @r{64 bit source register}
6708 rqd @r{64 bit destination register}
6709 addr @r{16/24 bit address}
6710 imm @r{immediate data}
6712 adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc
6713 adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc
6714 add rd,@@rs clrb rbd dab rbd
6715 add rd,addr com @@rd dbjnz rbd,disp7
6716 add rd,addr(rs) com addr dec @@rd,imm4m1
6717 add rd,imm16 com addr(rd) dec addr(rd),imm4m1
6718 add rd,rs com rd dec addr,imm4m1
6719 addb rbd,@@rs comb @@rd dec rd,imm4m1
6720 addb rbd,addr comb addr decb @@rd,imm4m1
6721 addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1
6722 addb rbd,imm8 comb rbd decb addr,imm4m1
6723 addb rbd,rbs comflg flags decb rbd,imm4m1
6724 addl rrd,@@rs cp @@rd,imm16 di i2
6725 addl rrd,addr cp addr(rd),imm16 div rrd,@@rs
6726 addl rrd,addr(rs) cp addr,imm16 div rrd,addr
6727 addl rrd,imm32 cp rd,@@rs div rrd,addr(rs)
6728 addl rrd,rrs cp rd,addr div rrd,imm16
6729 and rd,@@rs cp rd,addr(rs) div rrd,rs
6730 and rd,addr cp rd,imm16 divl rqd,@@rs
6731 and rd,addr(rs) cp rd,rs divl rqd,addr
6732 and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs)
6733 and rd,rs cpb addr(rd),imm8 divl rqd,imm32
6734 andb rbd,@@rs cpb addr,imm8 divl rqd,rrs
6735 andb rbd,addr cpb rbd,@@rs djnz rd,disp7
6736 andb rbd,addr(rs) cpb rbd,addr ei i2
6737 andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs
6738 andb rbd,rbs cpb rbd,imm8 ex rd,addr
6739 bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs)
6740 bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs
6741 bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs
6742 bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr
6743 bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs)
6744 bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs
6745 bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8
6746 bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8
6747 bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8
6748 bitb rbd,rs cpl rrd,@@rs ext8f imm8
6749 bpt cpl rrd,addr exts rrd
6750 call @@rd cpl rrd,addr(rs) extsb rd
6751 call addr cpl rrd,imm32 extsl rqd
6752 call addr(rd) cpl rrd,rrs halt
6753 calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs
6754 clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16
6755 clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs
6756 clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16
6757 clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1
6758 clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1
6759 inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs)
6760 inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16
6761 incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs
6762 incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs
6763 incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr
6764 incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs)
6765 ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32
6766 indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs
6767 inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd
6768 inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr
6769 iret ldib @@rd,@@rs,rr neg addr(rd)
6770 jp cc,@@rd ldir @@rd,@@rs,rr neg rd
6771 jp cc,addr ldirb @@rd,@@rs,rr negb @@rd
6772 jp cc,addr(rd) ldk rd,imm4 negb addr
6773 jr cc,disp8 ldl @@rd,rrs negb addr(rd)
6774 ld @@rd,imm16 ldl addr(rd),rrs negb rbd
6775 ld @@rd,rs ldl addr,rrs nop
6776 ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs
6777 ld addr(rd),rs ldl rd(rx),rrs or rd,addr
6778 ld addr,imm16 ldl rrd,@@rs or rd,addr(rs)
6779 ld addr,rs ldl rrd,addr or rd,imm16
6780 ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs
6781 ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs
6782 ld rd,@@rs ldl rrd,rrs orb rbd,addr
6783 ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs)
6784 ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8
6785 ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs
6786 ld rd,rs ldm addr(rd),rs,n out @@rd,rs
6787 ld rd,rs(imm16) ldm addr,rs,n out imm16,rs
6788 ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs
6789 lda rd,addr ldm rd,addr(rs),n outb imm16,rbs
6790 lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra
6791 lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba
6792 lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra
6793 ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra
6794 ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs
6795 ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs
6796 ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs
6797 ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs
6798 ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs
6799 ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs
6800 ldb rbd,@@rs mbit popl addr,@@rs
6801 ldb rbd,addr mreq rd popl rrd,@@rs
6802 ldb rbd,addr(rs) mres push @@rd,@@rs
6803 ldb rbd,imm8 mset push @@rd,addr
6804 ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs)
6805 ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16
6806 push @@rd,rs set addr,imm4 subl rrd,imm32
6807 pushl @@rd,@@rs set rd,imm4 subl rrd,rrs
6808 pushl @@rd,addr set rd,rs tcc cc,rd
6809 pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd
6810 pushl @@rd,rrs setb addr(rd),imm4 test @@rd
6811 res @@rd,imm4 setb addr,imm4 test addr
6812 res addr(rd),imm4 setb rbd,imm4 test addr(rd)
6813 res addr,imm4 setb rbd,rs test rd
6814 res rd,imm4 setflg imm4 testb @@rd
6815 res rd,rs sinb rbd,imm16 testb addr
6816 resb @@rd,imm4 sinb rd,imm16 testb addr(rd)
6817 resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd
6818 resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd
6819 resb rbd,imm4 sinib @@rd,@@rs,ra testl addr
6820 resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd)
6821 resflg imm4 sla rd,imm8 testl rrd
6822 ret cc slab rbd,imm8 trdb @@rd,@@rs,rba
6823 rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba
6824 rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr
6825 rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr
6826 rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr
6827 rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr
6828 rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr
6829 rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr
6830 rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd
6831 rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr
6832 rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd)
6833 rsvd36 sra rd,imm8 tset rd
6834 rsvd38 srab rbd,imm8 tsetb @@rd
6835 rsvd78 sral rrd,imm8 tsetb addr
6836 rsvd7e srl rd,imm8 tsetb addr(rd)
6837 rsvd9d srlb rbd,imm8 tsetb rbd
6838 rsvd9f srll rrd,imm8 xor rd,@@rs
6839 rsvdb9 sub rd,@@rs xor rd,addr
6840 rsvdbf sub rd,addr xor rd,addr(rs)
6841 sbc rd,rs sub rd,addr(rs) xor rd,imm16
6842 sbcb rbd,rbs sub rd,imm16 xor rd,rs
6843 sc imm8 sub rd,rs xorb rbd,@@rs
6844 sda rd,rs subb rbd,@@rs xorb rbd,addr
6845 sdab rbd,rs subb rbd,addr xorb rbd,addr(rs)
6846 sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8
6847 sdl rd,rs subb rbd,imm8 xorb rbd,rbs
6848 sdlb rbd,rs subb rbd,rbs xorb rbd,rbs
6849 sdll rrd,rs subl rrd,@@rs
6850 set @@rd,imm4 subl rrd,addr
6851 set addr(rd),imm4 subl rrd,addr(rs)
6862 @node MIPS-Dependent
6863 @chapter MIPS Dependent Features
6866 @node Machine Dependencies
6867 @chapter MIPS Dependent Features
6869 The MIPS @value{AS} supports the MIPS R2000 and R3000 processors.
6871 It ignores the @kbd{-nocpp}, @kbd{-EL}, and @kbd{-EB} options.
6873 Not all traditional MIPS macro instructions are currently supported.
6874 Specifically, @code{li.d} and @code{li.s} are not currently supported.
6876 When using @code{@value{GCC}} with MIPS @value{AS}, @code{@value{GCC}}
6877 must be configured using the -with-gnu-as switch (this is the case for
6878 Cygnus distributions) or @code{@value{GCC}} must be invoked with the
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 readonly data,
6884 @code{.sdata}, used for small data, and @code{.sbss}, used for small
6887 When assembling for ECOFF, the assembler will automatically use the $gp
6888 ($28) register when forming the address of a small object. Any object
6889 in the .sdata or .sbss sections is considered to be small. For external
6890 objects or objects in the @code{.bss} section, the -G switch may be used
6891 to control the size of objects for which the $gp register will be used;
6892 the default value is 8, meaning that a reference to any object eight
6893 bytes or smaller will use $gp. Passing -G 0 to @value{AS} will prevent
6894 it from using the $gp register. The size of an object in the
6895 @code{.bss} section is set by the @code{.comm} or @code{.lcomm}
6896 pseudo-op that defines it. The size of an external object may be set
6897 using the @code{.extern} pseudo-op. For example, @samp{.extern sym,4}
6898 declares that the object at @code{sym} is 4 bytes in length, whie
6899 leaving @code{sym} otherwise undefined.
6901 Using small ECOFF objects requires linker support, and assumes that the
6902 $gp register has been correctly initialized (normally done automatically
6903 by the startup code). MIPS ECOFF assembly code must avoid modifying the
6906 MIPS ECOFF @value{AS} supports several pseudo-ops 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} pseudo-ops can
6912 only be read by GDB, not by traditional MIPS debuggers (this enhancement
6913 is required to fully support C++ debugging). These psuedo-ops are
6914 primarily used by compilers, not assembly language programmers, and are
6915 described elsewhere in the manual.
6920 @c reverse effect of @down at top of generic Machine-Dep chapter
6925 @c pesch@cygnus.com: we ignore the following chapters, since internals are
6926 @c changing rapidly. These may need to be moved to another
6927 @c book anyhow, if we adopt the model of user/modifier
6930 @chapter Maintaining the Assembler
6931 [[this chapter is still being built]]
6934 We had these goals, in descending priority:
6937 For every program composed by a compiler, @code{@value{AS}} should emit
6938 ``correct'' code. This leaves some latitude in choosing addressing
6939 modes, order of @code{relocation_info} structures in the object
6942 @item Speed, for usual case.
6943 By far the most common use of @code{@value{AS}} will be assembling compiler
6946 @item Upward compatibility for existing assembler code.
6947 Well @dots{} we don't support Vax bit fields but everything else
6948 seems to be upward compatible.
6951 The code should be maintainable with few surprises. (JF: ha!)
6955 We assumed that disk I/O was slow and expensive while memory was
6956 fast and access to memory was cheap. We expect the in-memory data
6957 structures to be less than 10 times the size of the emitted object
6958 file. (Contrast this with the C compiler where in-memory structures
6959 might be 100 times object file size!)
6963 Try to read the source file from disk only one time. For other
6964 reasons, we keep large chunks of the source file in memory during
6965 assembly so this is not a problem. Also the assembly algorithm
6966 should only scan the source text once if the compiler composed the
6967 text according to a few simple rules.
6969 Emit the object code bytes only once. Don't store values and then
6972 Build the object file in memory and do direct writes to disk of
6976 RMS suggested a one-pass algorithm which seems to work well. By not
6977 parsing text during a second pass considerable time is saved on
6978 large programs (@emph{e.g.} the sort of C program @code{yacc} would
6981 It happened that the data structures needed to emit relocation
6982 information to the object file were neatly subsumed into the data
6983 structures that do backpatching of addresses after pass 1.
6985 Many of the functions began life as re-usable modules, loosely
6986 connected. RMS changed this to gain speed. For example, input
6987 parsing routines which used to work on pre-sanitized strings now
6988 must parse raw data. Hence they have to import knowledge of the
6989 assemblers' comment conventions @emph{etc}.
6991 @section Deprecated Feature(?)s
6992 We have stopped supporting some features:
6995 @code{.org} statements must have @b{defined} expressions.
6997 Vax Bit fields (@kbd{:} operator) are entirely unsupported.
7000 It might be a good idea to not support these features in a future release:
7003 @kbd{#} should begin a comment, even in column 1.
7005 Why support the logical line & file concept any more?
7007 Subsections are a good candidate for flushing.
7008 Depends on which compilers need them I guess.
7011 @section Bugs, Ideas, Further Work
7012 Clearly the major improvement is DON'T USE A TEXT-READING
7013 ASSEMBLER for the back end of a compiler. It is much faster to
7014 interpret binary gobbledygook from a compiler's tables than to
7015 ask the compiler to write out human-readable code just so the
7016 assembler can parse it back to binary.
7018 Assuming you use @code{@value{AS}} for human written programs: here are
7022 Document (here) @code{APP}.
7024 Take advantage of knowing no spaces except after opcode
7025 to speed up @code{@value{AS}}. (Modify @code{app.c} to flush useless spaces:
7026 only keep space/tabs at begin of line or between 2
7029 Put pointers in this documentation to @file{a.out} documentation.
7031 Split the assembler into parts so it can gobble direct binary
7032 from @emph{e.g.} @code{cc}. It is silly for@code{cc} to compose text
7033 just so @code{@value{AS}} can parse it back to binary.
7035 Rewrite hash functions: I want a more modular, faster library.
7037 Clean up LOTS of code.
7039 Include all the non-@file{.c} files in the maintenance chapter.
7043 Implement flonum short literals.
7045 Change all talk of expression operands to expression quantities,
7046 or perhaps to expression arguments.
7050 Whenever a @code{.text} or @code{.data} statement is seen, we close
7051 of the current frag with an imaginary @code{.fill 0}. This is
7052 because we only have one obstack for frags, and we can't grow new
7053 frags for a new subsection, then go back to the old subsection and
7054 append bytes to the old frag. All this nonsense goes away if we
7055 give each subsection its own obstack. It makes code simpler in
7056 about 10 places, but nobody has bothered to do it because C compiler
7057 output rarely changes subsections (compared to ending frags with
7058 relaxable addresses, which is common).
7062 @c The following files in the @file{@value{AS}} directory
7063 @c are symbolic links to other files, of
7064 @c the same name, in a different directory.
7067 @c @file{atof_generic.c}
7069 @c @file{atof_vax.c}
7071 @c @file{flonum_const.c}
7073 @c @file{flonum_copy.c}
7075 @c @file{flonum_get.c}
7077 @c @file{flonum_multip.c}
7079 @c @file{flonum_normal.c}
7081 @c @file{flonum_print.c}
7084 Here is a list of the source files in the @file{@value{AS}} directory.
7088 This contains the pre-processing phase, which deletes comments,
7089 handles whitespace, etc. This was recently re-written, since app
7090 used to be a separate program, but RMS wanted it to be inline.
7093 This is a subroutine to append a string to another string returning a
7094 pointer just after the last @code{char} appended. (JF: All these
7095 little routines should probably all be put in one file.)
7098 Here you will find the main program of the assembler @code{@value{AS}}.
7101 This is a branch office of @file{read.c}. This understands
7102 expressions, arguments. Inside @code{@value{AS}}, arguments are called
7103 (expression) @emph{operands}. This is confusing, because we also talk
7104 (elsewhere) about instruction @emph{operands}. Also, expression
7105 operands are called @emph{quantities} explicitly to avoid confusion
7106 with instruction operands. What a mess.
7109 This implements the @b{frag} concept. Without frags, finding the
7110 right size for branch instructions would be a lot harder.
7113 This contains the symbol table, opcode table @emph{etc.} hashing
7117 This is a table of values of digits, for use in atoi() type
7118 functions. Could probably be flushed by using calls to strtol(), or
7122 This contains Operating system dependent source file reading
7123 routines. Since error messages often say where we are in reading
7124 the source file, they live here too. Since @code{@value{AS}} is intended to
7125 run under GNU and Unix only, this might be worth flushing. Anyway,
7126 almost all C compilers support stdio.
7129 This deals with calling the pre-processor (if needed) and feeding the
7130 chunks back to the rest of the assembler the right way.
7133 This contains operating system independent parts of fatal and
7134 warning message reporting. See @file{append.c} above.
7137 This contains operating system dependent functions that write an
7138 object file for @code{@value{AS}}. See @file{input-file.c} above.
7141 This implements all the directives of @code{@value{AS}}. This also deals
7142 with passing input lines to the machine dependent part of the
7146 This is a C library function that isn't in most C libraries yet.
7147 See @file{append.c} above.
7150 This implements subsections.
7153 This implements symbols.
7156 This contains the code to perform relaxation, and to write out
7157 the object file. It is mostly operating system independent, but
7158 different OSes have different object file formats in any case.
7161 This implements @code{malloc()} or bust. See @file{append.c} above.
7164 This implements @code{realloc()} or bust. See @file{append.c} above.
7166 @item atof-generic.c
7167 The following files were taken from a machine-independent subroutine
7168 library for manipulating floating point numbers and very large
7171 @file{atof-generic.c} turns a string into a flonum internal format
7172 floating-point number.
7174 @item flonum-const.c
7175 This contains some potentially useful floating point numbers in
7179 This copies a flonum.
7181 @item flonum-multip.c
7182 This multiplies two flonums together.
7185 This copies a bignum.
7189 Here is a table of all the machine-specific files (this includes
7190 both source and header files). Typically, there is a
7191 @var{machine}.c file, a @var{machine}-opcode.h file, and an
7192 atof-@var{machine}.c file. The @var{machine}-opcode.h file should
7193 be identical to the one used by GDB (which uses it for disassembly.)
7198 This contains code to turn a flonum into a ieee literal constant.
7199 This is used by tye 680x0, 32x32, sparc, and i386 versions of @code{@value{AS}}.
7202 This is the opcode-table for the i386 version of the assembler.
7205 This contains all the code for the i386 version of the assembler.
7208 This defines constants and macros used by the i386 version of the assembler.
7211 generic 68020 header file. To be linked to m68k.h on a
7212 non-sun3, non-hpux system.
7215 68010 header file for Sun2 workstations. Not well tested. To be linked
7216 to m68k.h on a sun2. (See also @samp{-DSUN_ASM_SYNTAX} in the
7220 68020 header file for Sun3 workstations. To be linked to m68k.h before
7221 compiling on a Sun3 system. (See also @samp{-DSUN_ASM_SYNTAX} in the
7225 68020 header file for a HPUX (system 5?) box. Which box, which
7226 version of HPUX, etc? I don't know.
7229 A hard- or symbolic- link to one of @file{m-generic.h},
7230 @file{m-hpux.h} or @file{m-sun3.h} depending on which kind of
7231 680x0 you are assembling for. (See also @samp{-DSUN_ASM_SYNTAX} in the
7235 Opcode table for 68020. This is now a link to the opcode table
7236 in the @code{GDB} source directory.
7239 All the mc680x0 code, in one huge, slow-to-compile file.
7242 This contains the code for the ns32032/ns32532 version of the
7245 @item ns32k-opcode.h
7246 This contains the opcode table for the ns32032/ns32532 version
7250 Vax specific file for describing Vax operands and other Vax-ish things.
7256 Vax specific parts of @code{@value{AS}}. Also includes the former files
7257 @file{vax-ins-parse.c}, @file{vax-reg-parse.c} and @file{vip-op.c}.
7260 Turns a flonum into a Vax constant.
7263 This file contains the special code needed to put out a VMS
7264 style object file for the Vax.
7268 Here is a list of the header files in the source directory.
7269 (Warning: This section may not be very accurate. I didn't
7270 write the header files; I just report them.) Also note that I
7271 think many of these header files could be cleaned up or
7277 This describes the structures used to create the binary header data
7278 inside the object file. Perhaps we should use the one in
7279 @file{/usr/include}?
7282 This defines all the globally useful things, and pulls in @file{stdio.h}
7283 and @file{assert.h}.
7286 This defines macros useful for dealing with bignums.
7289 Structure and macros for dealing with expression()
7292 This defines the structure for dealing with floating point
7293 numbers. It #includes @file{bignum.h}.
7296 This contains macro for appending a byte to the current frag.
7299 Structures and function definitions for the hashing functions.
7302 Function headers for the input-file.c functions.
7305 structures and function headers for things defined in the
7306 machine dependent part of the assembler.
7309 This is the GNU systemwide include file for manipulating obstacks.
7310 Since nobody is running under real GNU yet, we include this file.
7313 Macros and function headers for reading in source files.
7315 @item struct-symbol.h
7316 Structure definition and macros for dealing with the @value{AS}
7317 internal form of a symbol.
7320 structure definition for dealing with the numbered subsections
7321 of the text and data sections.
7324 Macros and function headers for dealing with symbols.
7327 Structure for doing section fixups.
7330 @c ~subsection Test Directory
7331 @c (Note: The test directory seems to have disappeared somewhere
7332 @c along the line. If you want it, you'll probably have to find a
7333 @c REALLY OLD dump tape~dots{})
7335 @c The ~file{test/} directory is used for regression testing.
7336 @c After you modify ~@code{@value{AS}}, you can get a quick go/nogo
7337 @c confidence test by running the new ~@code{@value{AS}} over the source
7338 @c files in this directory. You use a shell script ~file{test/do}.
7340 @c The tests in this suite are evolving. They are not comprehensive.
7341 @c They have, however, caught hundreds of bugs early in the debugging
7342 @c cycle of ~@code{@value{AS}}. Most test statements in this suite were naturally
7343 @c selected: they were used to demonstrate actual ~@code{@value{AS}} bugs rather
7344 @c than being written ~i{a prioi}.
7346 @c Another testing suggestion: over 30 bugs have been found simply by
7347 @c running examples from this manual through ~@code{@value{AS}}.
7348 @c Some examples in this manual are selected
7349 @c to distinguish boundary conditions; they are good for testing ~@code{@value{AS}}.
7351 @c ~subsubsection Regression Testing
7352 @c Each regression test involves assembling a file and comparing the
7353 @c actual output of ~@code{@value{AS}} to ``known good'' output files. Both
7354 @c the object file and the error/warning message file (stderr) are
7355 @c inspected. Optionally the ~@code{@value{AS}} exit status may be checked.
7356 @c Discrepencies are reported. Each discrepency means either that
7357 @c you broke some part of ~@code{@value{AS}} or that the ``known good'' files
7358 @c are now out of date and should be changed to reflect the new
7359 @c definition of ``good''.
7361 @c Each regression test lives in its own directory, in a tree
7362 @c rooted in the directory ~file{test/}. Each such directory
7363 @c has a name ending in ~file{.ret}, where `ret' stands for
7364 @c REgression Test. The ~file{.ret} ending allows ~code{find
7365 @c (1)} to find all regression tests in the tree, without
7366 @c needing to list them explicitly.
7368 @c Any ~file{.ret} directory must contain a file called
7369 @c ~file{input} which is the source file to assemble. During
7370 @c testing an object file ~file{output} is created, as well as
7371 @c a file ~file{stdouterr} which contains the output to both
7372 @c stderr and stderr. If there is a file ~file{output.good} in
7373 @c the directory, and if ~file{output} contains exactly the
7374 @c same data as ~file{output.good}, the file ~file{output} is
7375 @c deleted. Likewise ~file{stdouterr} is removed if it exactly
7376 @c matches a file ~file{stdouterr.good}. If file
7377 @c ~file{status.good} is present, containing a decimal number
7378 @c before a newline, the exit status of ~@code{@value{AS}} is compared
7379 @c to this number. If the status numbers are not equal, a file
7380 @c ~file{status} is written to the directory, containing the
7381 @c actual status as a decimal number followed by newline.
7383 @c Should any of the ~file{*.good} files fail to match their corresponding
7384 @c actual files, this is noted by a 1-line message on the screen during
7385 @c the regression test, and you can use ~@code{find (1)} to find any
7386 @c files named ~file{status}, ~file {output} or ~file{stdouterr}.
7390 @chapter Teaching the Assembler about a New Machine
7392 This chapter describes the steps required in order to make the
7393 assembler work with another machine's assembly language. This
7394 chapter is not complete, and only describes the steps in the
7395 broadest terms. You should look at the source for the
7396 currently supported machine in order to discover some of the
7397 details that aren't mentioned here.
7399 You should create a new file called @file{@var{machine}.c}, and
7400 add the appropriate lines to the file @file{Makefile} so that
7401 you can compile your new version of the assembler. This should
7402 be straighforward; simply add lines similar to the ones there
7403 for the four current versions of the assembler.
7405 If you want to be compatible with GDB, (and the current
7406 machine-dependent versions of the assembler), you should create
7407 a file called @file{@var{machine}-opcode.h} which should
7408 contain all the information about the names of the machine
7409 instructions, their opcodes, and what addressing modes they
7410 support. If you do this right, the assembler and GDB can share
7411 this file, and you'll only have to write it once. Note that
7412 while you're writing @code{@value{AS}}, you may want to use an
7413 independent program (if you have access to one), to make sure
7414 that @code{@value{AS}} is emitting the correct bytes. Since @code{@value{AS}}
7415 and @code{GDB} share the opcode table, an incorrect opcode
7416 table entry may make invalid bytes look OK when you disassemble
7417 them with @code{GDB}.
7419 @section Functions You will Have to Write
7421 Your file @file{@var{machine}.c} should contain definitions for
7422 the following functions and variables. It will need to include
7423 some header files in order to use some of the structures
7424 defined in the machine-independent part of the assembler. The
7425 needed header files are mentioned in the descriptions of the
7426 functions that will need them.
7431 This long integer holds the value to place at the beginning of
7432 the @file{a.out} file. It is usually @samp{OMAGIC}, except on
7433 machines that store additional information in the magic-number.
7435 @item char comment_chars[];
7436 This character array holds the values of the characters that
7437 start a comment anywhere in a line. Comments are stripped off
7438 automatically by the machine independent part of the
7439 assembler. Note that the @samp{/*} will always start a
7440 comment, and that only @samp{*/} will end a comment started by
7443 @item char line_comment_chars[];
7444 This character array holds the values of the chars that start a
7445 comment only if they are the first (non-whitespace) character
7446 on a line. If the character @samp{#} does not appear in this
7447 list, you may get unexpected results. (Various
7448 machine-independent parts of the assembler treat the comments
7449 @samp{#APP} and @samp{#NO_APP} specially, and assume that lines
7450 that start with @samp{#} are comments.)
7452 @item char EXP_CHARS[];
7453 This character array holds the letters that can separate the
7454 mantissa and the exponent of a floating point number. Typical
7455 values are @samp{e} and @samp{E}.
7457 @item char FLT_CHARS[];
7458 This character array holds the letters that--when they appear
7459 immediately after a leading zero--indicate that a number is a
7460 floating-point number. (Sort of how 0x indicates that a
7461 hexadecimal number follows.)
7463 @item pseudo_typeS md_pseudo_table[];
7464 (@var{pseudo_typeS} is defined in @file{md.h})
7465 This array contains a list of the machine_dependent directives
7466 the assembler must support. It contains the name of each
7467 pseudo op (Without the leading @samp{.}), a pointer to a
7468 function to be called when that directive is encountered, and
7469 an integer argument to be passed to that function.
7471 @item void md_begin(void)
7472 This function is called as part of the assembler's
7473 initialization. It should do any initialization required by
7474 any of your other routines.
7476 @item int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR)
7477 This routine is called once for each option on the command line
7478 that the machine-independent part of @code{@value{AS}} does not
7479 understand. This function should return non-zero if the option
7480 pointed to by @var{optionPTR} is a valid option. If it is not
7481 a valid option, this routine should return zero. The variables
7482 @var{argcPTR} and @var{argvPTR} are provided in case the option
7483 requires a filename or something similar as an argument. If
7484 the option is multi-character, @var{optionPTR} should be
7485 advanced past the end of the option, otherwise every letter in
7486 the option will be treated as a separate single-character
7489 @item void md_assemble(char *string)
7490 This routine is called for every machine-dependent
7491 non-directive line in the source file. It does all the real
7492 work involved in reading the opcode, parsing the operands,
7493 etc. @var{string} is a pointer to a null-terminated string,
7494 that comprises the input line, with all excess whitespace and
7497 @item void md_number_to_chars(char *outputPTR,long value,int nbytes)
7498 This routine is called to turn a C long int, short int, or char
7499 into the series of bytes that represents that number on the
7500 target machine. @var{outputPTR} points to an array where the
7501 result should be stored; @var{value} is the value to store; and
7502 @var{nbytes} is the number of bytes in 'value' that should be
7505 @item void md_number_to_imm(char *outputPTR,long value,int nbytes)
7506 This routine is called to turn a C long int, short int, or char
7507 into the series of bytes that represent an immediate value on
7508 the target machine. It is identical to the function @code{md_number_to_chars},
7509 except on NS32K machines.@refill
7511 @item void md_number_to_disp(char *outputPTR,long value,int nbytes)
7512 This routine is called to turn a C long int, short int, or char
7513 into the series of bytes that represent an displacement value on
7514 the target machine. It is identical to the function @code{md_number_to_chars},
7515 except on NS32K machines.@refill
7517 @item void md_number_to_field(char *outputPTR,long value,int nbytes)
7518 This routine is identical to @code{md_number_to_chars},
7519 except on NS32K machines.
7521 @item void md_ri_to_chars(struct relocation_info *riPTR,ri)
7522 (@code{struct relocation_info} is defined in @file{a.out.h})
7523 This routine emits the relocation info in @var{ri}
7524 in the appropriate bit-pattern for the target machine.
7525 The result should be stored in the location pointed
7526 to by @var{riPTR}. This routine may be a no-op unless you are
7527 attempting to do cross-assembly.
7529 @item char *md_atof(char type,char *outputPTR,int *sizePTR)
7530 This routine turns a series of digits into the appropriate
7531 internal representation for a floating-point number.
7532 @var{type} is a character from @var{FLT_CHARS[]} that describes
7533 what kind of floating point number is wanted; @var{outputPTR}
7534 is a pointer to an array that the result should be stored in;
7535 and @var{sizePTR} is a pointer to an integer where the size (in
7536 bytes) of the result should be stored. This routine should
7537 return an error message, or an empty string (not (char *)0) for
7540 @item int md_short_jump_size;
7541 This variable holds the (maximum) size in bytes of a short (16
7542 bit or so) jump created by @code{md_create_short_jump()}. This
7543 variable is used as part of the broken-word feature, and isn't
7544 needed if the assembler is compiled with
7545 @samp{-DWORKING_DOT_WORD}.
7547 @item int md_long_jump_size;
7548 This variable holds the (maximum) size in bytes of a long (32
7549 bit or so) jump created by @code{md_create_long_jump()}. This
7550 variable is used as part of the broken-word feature, and isn't
7551 needed if the assembler is compiled with
7552 @samp{-DWORKING_DOT_WORD}.
7554 @item void md_create_short_jump(char *resultPTR,long from_addr,
7555 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
7556 This function emits a jump from @var{from_addr} to @var{to_addr} in
7557 the array of bytes pointed to by @var{resultPTR}. If this creates a
7558 type of jump that must be relocated, this function should call
7559 @code{fix_new()} with @var{frag} and @var{to_symbol}. The jump
7560 emitted by this function may be smaller than @var{md_short_jump_size},
7561 but it must never create a larger one.
7562 (If it creates a smaller jump, the extra bytes of memory will not be
7563 used.) This function is used as part of the broken-word feature,
7564 and isn't needed if the assembler is compiled with
7565 @samp{-DWORKING_DOT_WORD}.@refill
7567 @item void md_create_long_jump(char *ptr,long from_addr,
7568 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
7569 This function is similar to the previous function,
7570 @code{md_create_short_jump()}, except that it creates a long
7571 jump instead of a short one. This function is used as part of
7572 the broken-word feature, and isn't needed if the assembler is
7573 compiled with @samp{-DWORKING_DOT_WORD}.
7575 @item int md_estimate_size_before_relax(fragS *fragPTR,int segment_type)
7576 This function does the initial setting up for relaxation. This
7577 includes forcing references to still-undefined symbols to the
7578 appropriate addressing modes.
7580 @item relax_typeS md_relax_table[];
7581 (relax_typeS is defined in md.h)
7582 This array describes the various machine dependent states a
7583 frag may be in before relaxation. You will need one group of
7584 entries for each type of addressing mode you intend to relax.
7586 @item void md_convert_frag(fragS *fragPTR)
7587 (@var{fragS} is defined in @file{as.h})
7588 This routine does the required cleanup after relaxation.
7589 Relaxation has changed the type of the frag to a type that can
7590 reach its destination. This function should adjust the opcode
7591 of the frag to use the appropriate addressing mode.
7592 @var{fragPTR} points to the frag to clean up.
7594 @item void md_end(void)
7595 This function is called just before the assembler exits. It
7596 need not free up memory unless the operating system doesn't do
7597 it automatically on exit. (In which case you'll also have to
7598 track down all the other places where the assembler allocates
7599 space but never frees it.)
7603 @section External Variables You will Need to Use
7605 You will need to refer to or change the following external variables
7606 from within the machine-dependent part of the assembler.
7609 @item extern char flagseen[];
7610 This array holds non-zero values in locations corresponding to
7611 the options that were on the command line. Thus, if the
7612 assembler was called with @samp{-W}, @var{flagseen['W']} would
7615 @item extern fragS *frag_now;
7616 This pointer points to the current frag--the frag that bytes
7617 are currently being added to. If nothing else, you will need
7618 to pass it as an argument to various machine-independent
7619 functions. It is maintained automatically by the
7620 frag-manipulating functions; you should never have to change it
7623 @item extern LITTLENUM_TYPE generic_bignum[];
7624 (@var{LITTLENUM_TYPE} is defined in @file{bignum.h}.
7625 This is where @dfn{bignums}--numbers larger than 32 bits--are
7626 returned when they are encountered in an expression. You will
7627 need to use this if you need to implement directives (or
7628 anything else) that must deal with these large numbers.
7629 @code{Bignums} are of @code{segT} @code{SEG_BIG} (defined in
7630 @file{as.h}, and have a positive @code{X_add_number}. The
7631 @code{X_add_number} of a @code{bignum} is the number of
7632 @code{LITTLENUMS} in @var{generic_bignum} that the number takes
7635 @item extern FLONUM_TYPE generic_floating_point_number;
7636 (@var{FLONUM_TYPE} is defined in @file{flonum.h}.
7637 The is where @dfn{flonums}--floating-point numbers within
7638 expressions--are returned. @code{Flonums} are of @code{segT}
7639 @code{SEG_BIG}, and have a negative @code{X_add_number}.
7640 @code{Flonums} are returned in a generic format. You will have
7641 to write a routine to turn this generic format into the
7642 appropriate floating-point format for your machine.
7644 @item extern int need_pass_2;
7645 If this variable is non-zero, the assembler has encountered an
7646 expression that cannot be assembled in a single pass. Since
7647 the second pass isn't implemented, this flag means that the
7648 assembler is punting, and is only looking for additional syntax
7649 errors. (Or something like that.)
7651 @item extern segT now_seg;
7652 This variable holds the value of the section the assembler is
7653 currently assembling into.
7657 @section External functions will you need
7659 You will find the following external functions useful (or indispensable) when
7660 you're writing the machine-dependent part of the assembler.
7664 @item char *frag_more(int bytes)
7665 This function allocates @var{bytes} more bytes in the current frag (or starts a
7666 new frag, if it can't expand the current frag any more.) for you to store some
7667 object-file bytes in. It returns a pointer to the bytes, ready for you to
7670 @item void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel)
7671 This function stores a relocation fixup to be acted on later.
7672 @var{frag} points to the frag the relocation belongs in;
7673 @var{where} is the location within the frag where the relocation begins;
7674 @var{size} is the size of the relocation, and is usually 1 (a single byte),
7675 2 (sixteen bits), or 4 (a longword). The value @var{add_symbol}
7676 @minus{} @var{sub_symbol} + @var{offset}, is added to the byte(s) at
7677 @var{frag->literal[where]}. If @var{pcrel} is non-zero, the address of
7678 the location is subtracted from the result. A relocation entry is also
7679 added to the @file{a.out} file. @var{add_symbol}, @var{sub_symbol},
7680 and/or @var{offset} may be NULL.@refill
7682 @item char *frag_var(relax_stateT type, int max_chars, int var,
7683 @code{relax_substateT subtype, symbolS *symbol, char *opcode)}
7684 This function creates a machine-dependent frag of type @var{type}
7685 (usually @code{rs_machine_dependent}).
7686 @var{max_chars} is the maximum size in bytes that the frag may grow by;
7687 @var{var} is the current size of the variable end of the frag;
7688 @var{subtype} is the sub-type of the frag. The sub-type is used to index into
7689 @var{md_relax_table[]} during @code{relaxation}.
7690 @var{symbol} is the symbol whose value should be used to when relax-ing this frag.
7691 @var{opcode} points into a byte whose value may have to be modified if the
7692 addressing mode used by this frag changes. It typically points into the
7693 @var{fr_literal[]} of the previous frag, and is used to point to a location
7694 that @code{md_convert_frag()}, may have to change.@refill
7696 @item void frag_wane(fragS *fragPTR)
7697 This function is useful from within @code{md_convert_frag}. It changes a frag
7698 to type rs_fill, and sets the variable-sized piece of the frag to zero. The
7699 frag will never change in size again.
7701 @item segT expression(expressionS *retval)
7702 (@var{segT} is defined in @file{as.h}; @var{expressionS} is defined in
7703 @file{expr.h}) This function parses the string pointed to by the external char
7704 pointer @var{input_line_pointer}, and returns the section-type of the symbol
7705 used in the expression, if any. It stores the results in the @var{expressionS}
7706 pointed to by @var{retval}. @var{input_line_pointer} is advanced to point past
7707 the end of the expression. (@var{input_line_pointer} is used by other parts of
7708 the assembler. If you modify it, be sure to restore it to its original value.)
7710 @item as_warn(char *message,@dots{})
7711 If warning messages are disabled, this function does nothing. Otherwise, it
7712 prints out the current file name, and the current line number, then uses
7713 @code{fprintf} to print the @var{message} and any arguments it was passed.
7715 @item as_bad(char *message,@dots{})
7716 This function should be called when @code{@value{AS}} encounters conditions
7717 that are bad enough that @code{@value{AS}} should not produce an object file,
7718 but should continue reading input and printing warning and bad error messages.
7720 @item as_fatal(char *message,@dots{})
7721 This function prints out the current file name and line number, prints the word
7722 @samp{FATAL:}, then uses @code{fprintf} to print the @var{message} and any
7723 arguments it was passed. Then the assembler exits. This function should only
7724 be used for serious, unrecoverable errors.
7726 @item void float_const(int float_type)
7727 This function reads floating-point constants from the current input line, and
7728 calls @code{md_atof} to assemble them. It is useful as the function to call
7729 for the directives @samp{.single}, @samp{.double}, @samp{.float}, etc.
7730 @var{float_type} must be a character from @var{FLT_CHARS}.
7732 @item void demand_empty_rest_of_line(void);
7733 This function can be used by machine-dependent directives to make sure the rest
7734 of the input line is empty. It prints a warning message if there are
7735 additional characters on the line.
7737 @item long int get_absolute_expression(void)
7738 This function can be used by machine-dependent directives to read an absolute
7739 number from the current input line. It returns the result. If it isn't given
7740 an absolute expression, it prints a warning message and returns zero.
7745 @section The concept of Frags
7747 This assembler works to optimize the size of certain addressing modes.
7748 (e.g. branch instructions) This means the size of many pieces of object code
7749 cannot be determined until after assembly is finished. (This means that the
7750 addresses of symbols cannot be determined until assembly is finished.) In
7751 order to do this, @code{@value{AS}} stores the output bytes as @dfn{frags}.
7753 Here is the definition of a frag (from @file{as.h})
7759 relax_stateT fr_type;
7760 relax_substateT fr_substate;
7761 unsigned long fr_address;
7763 struct symbol *fr_symbol;
7765 struct frag *fr_next;
7772 is the size of the fixed-size piece of the frag.
7775 is the maximum (?) size of the variable-sized piece of the frag.
7778 is the type of the frag.
7783 rs_machine_dependent
7786 This stores the type of machine-dependent frag this is. (what kind of
7787 addressing mode is being used, and what size is being tried/will fit/etc.
7790 @var{fr_address} is only valid after relaxation is finished. Before
7791 relaxation, the only way to store an address is (pointer to frag containing the
7792 address) plus (offset into the frag).
7795 This contains a number, whose meaning depends on the type of the frag. for
7796 machine_dependent frags, this contains the offset from fr_symbol that the frag
7797 wants to go to. Thus, for branch instructions it is usually zero. (unless the
7798 instruction was @samp{jba foo+12} or something like that.)
7801 for machine_dependent frags, this points to the symbol the frag needs to reach.
7804 This points to the location in the frag (or in a previous frag) of the opcode
7805 for the instruction that caused this to be a frag. @var{fr_opcode} is needed
7806 if the actual opcode must be changed in order to use a different form of the
7807 addressing mode. (For example, if a conditional branch only comes in size
7808 tiny, a large-size branch could be implemented by reversing the sense of the
7809 test, and turning it into a tiny branch over a large jump. This would require
7810 changing the opcode.)
7812 @var{fr_literal} is a variable-size array that contains the actual object
7813 bytes. A frag consists of a fixed size piece of object data, (which may be
7814 zero bytes long), followed by a piece of object data whose size may not have
7815 been determined yet. Other information includes the type of the frag (which
7816 controls how it is relaxed),
7819 This is the next frag in the singly-linked list. This is usually only needed
7820 by the machine-independent part of @code{@value{AS}}.
7825 @node Acknowledgements
7826 @chapter Acknowledgements
7828 If you've contributed to @code{@value{AS}} and your name isn't listed here, it
7829 is not meant as a slight. We just don't know about it. Send mail to the
7830 maintainer, and we'll correct the situation. Currently (June 1993), the
7831 maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
7833 Dean Elsner wrote the original GNU assembler for the VAX.@footnote{Any more
7836 Jay Fenlason maintained GAS for a while, adding support for gdb-specific debug
7837 information and the 68k series machines, most of the preprocessing pass, and
7838 extensive changes in messages.c, input-file.c, write.c.
7840 K. Richard Pixley maintained GAS for a while, adding various enhancements and
7841 many bug fixes, including merging support for several processors, breaking GAS
7842 up to handle multiple object file format back end (including heavy rewrite,
7843 testing, an integration of the coff and b.out back end), adding configuration
7844 including heavy testing and verification of cross assemblers and file splits
7845 and renaming, converted GAS to strictly ansi C including full prototypes, added
7846 support for m680[34]0 & cpu32, considerable work on i960 including a COFF port
7847 (including considerable amounts of reverse engineering), a SPARC opcode file
7848 rewrite, DECstation, rs6000, and hp300hpux host ports, updated "know"
7849 assertions and made them work, much other reorganization, cleanup, and lint.
7851 Ken Raeburn wrote the high-level BFD interface code to replace most of the code
7852 in format-specific I/O modules.
7854 The original VMS support was contributed by David L. Kashtan. Eric Youngdale
7855 has done much work with it since.
7857 The Intel 80386 machine description was written by Eliot Dresselhaus.
7859 Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
7861 The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
7862 University and Torbjorn Granlund of the Swedish Institute of Computer Science.
7864 Keith Knowles at the Open Software Foundation wrote the original MIPS back end
7865 (tc-mips.c, tc-mips.h), and contributed Rose format support (which hasn't been
7866 merged in yet). Ralph Campbell worked with the MIPS code to support a.out
7869 Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k,
7870 tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
7871 Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
7872 use BFD for some low-level operations, for use with the H8/300 and AMD 29k
7875 John Gilmore built the AMD 29000 support, added .include support, and
7876 simplified the configuration of which versions accept which pseudo-ops. He
7877 updated the 68k machine description so that Motorola's opcodes always produced
7878 fixed-size instructions (e.g. jsr), while synthetic instructions remained
7879 shrinkable (jbsr). John fixed many bugs, including true tested
7880 cross-compilation support, and one bug in relaxation that took a week and
7881 required the apocryphal one-bit fix.
7883 Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntaxes for the
7884 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
7885 and made a few other minor patches.
7887 Steve Chamberlain made @code{@value{AS}} able to generate listings.
7889 Support for the HP9000/300 was contributed by Hewlett-Packard.
7891 GAS and BFD support for the native HPPA object format (SOM) along with
7892 a fairly extensive HPPA testsuite (for both SOM and ELF object formats)
7893 was written by Jeff Law. This work was supported by both the Center for
7894 Software Science at the University of Utah and Cygnus Support.
7896 Support for ELF format files has been worked on by Mark Eichin of Cygnus
7897 Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
7898 Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
7899 Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
7900 and some initial 64-bit support).
7902 Several engineers at Cygnus Support have also provided many small bug fixes and
7903 configuration enhancements.
7905 Many others have contributed large or small bugfixes and enhancements. If
7906 you've contributed significant work and are not mentioned on this list, and
7907 want to be, let us know. Some of the history has been lost; we aren't
7908 intentionally leaving anyone out.
7913 @include gpl.texinfo