1 \input texinfo @c -*-Texinfo-*-
2 @c Copyright (c) 1991 1992 1993 1994 Free Software Foundation, Inc.
3 @c UPDATE!! On future updates--
4 @c (1) check for new machine-dep cmdline options in
5 @c md_parse_option definitions in config/tc-*.c
6 @c (2) for platform-specific directives, examine md_pseudo_op
8 @c (3) for object-format specific directives, examine obj_pseudo_op
10 @c (4) portable directives in potable[] in read.c
14 @c defaults, config file may override:
17 @include asdoc-config.texi
19 @c common OR combinations of conditions
36 @set abnormal-separator
40 @settitle Using @value{AS}
43 @settitle Using @value{AS} (@value{TARGET})
45 @setchapternewpage odd
50 @c WARE! Some of the machine-dependent sections contain tables of machine
51 @c instructions. Except in multi-column format, these tables look silly.
52 @c Unfortunately, Texinfo doesn't have a general-purpose multi-col format, so
53 @c the multi-col format is faked within @example sections.
55 @c Again unfortunately, the natural size that fits on a page, for these tables,
56 @c is different depending on whether or not smallbook is turned on.
57 @c This matters, because of order: text flow switches columns at each page
60 @c The format faked in this source works reasonably well for smallbook,
61 @c not well for the default large-page format. This manual expects that if you
62 @c turn on @smallbook, you will also uncomment the "@set SMALL" to enable the
63 @c tables in question. You can turn on one without the other at your
64 @c discretion, of course.
67 @c the insn tables look just as silly in info files regardless of smallbook,
68 @c might as well show 'em anyways.
73 START-INFO-DIR-ENTRY As: (as). The GNU assembler. END-INFO-DIR-ENTRY
81 This file documents the GNU Assembler "@value{AS}".
83 Copyright (C) 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
85 Permission is granted to make and distribute verbatim copies of
86 this manual provided the copyright notice and this permission notice
87 are preserved on all copies.
90 Permission is granted to process this file through Tex and print the
91 results, provided the printed document carries copying permission
92 notice identical to this one except for the removal of this paragraph
93 (this paragraph not being relevant to the printed manual).
96 Permission is granted to copy and distribute modified versions of this manual
97 under the conditions for verbatim copying, provided that the entire resulting
98 derived work is distributed under the terms of a permission notice identical to
101 Permission is granted to copy and distribute translations of this manual
102 into another language, under the above conditions for modified versions.
106 @title Using @value{AS}
107 @subtitle The GNU Assembler
109 @subtitle for the @value{TARGET} family
112 @subtitle January 1994
115 The Free Software Foundation Inc. thanks The Nice Computer
116 Company of Australia for loaning Dean Elsner to write the
117 first (Vax) version of @code{as} for Project GNU.
118 The proprietors, management and staff of TNCCA thank FSF for
119 distracting the boss while they got some work
122 @author Dean Elsner, Jay Fenlason & friends
126 \hfill {\it Using {\tt @value{AS}}}\par
127 \hfill Edited by Roland Pesch for Cygnus Support\par
129 %"boxit" macro for figures:
130 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
131 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
132 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
133 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
134 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
137 @vskip 0pt plus 1filll
138 Copyright @copyright{} 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
140 Permission is granted to make and distribute verbatim copies of
141 this manual provided the copyright notice and this permission notice
142 are preserved on all copies.
144 Permission is granted to copy and distribute modified versions of this manual
145 under the conditions for verbatim copying, provided that the entire resulting
146 derived work is distributed under the terms of a permission notice identical to
149 Permission is granted to copy and distribute translations of this manual
150 into another language, under the above conditions for modified versions.
155 @top Using @value{AS}
157 This file is a user guide to the GNU assembler @code{@value{AS}}.
159 This version of the file describes @code{@value{AS}} configured to generate
160 code for @value{TARGET} architectures.
163 * Overview:: Overview
164 * Invoking:: Command-Line Options
166 * Sections:: Sections and Relocation
168 * Expressions:: Expressions
169 * Pseudo Ops:: Assembler Directives
170 * Machine Dependencies:: Machine Dependent Features
171 * Acknowledgements:: Who Did What
179 This manual is a user guide to the GNU assembler @code{@value{AS}}.
181 This version of the manual describes @code{@value{AS}} configured to generate
182 code for @value{TARGET} architectures.
186 @cindex invocation summary
187 @cindex option summary
188 @cindex summary of options
189 Here is a brief summary of how to invoke @code{@value{AS}}. For details,
190 @pxref{Invoking,,Comand-Line Options}.
192 @c We don't use deffn and friends for the following because they seem
193 @c to be limited to one line for the header.
195 @value{AS} [ -a[dhlns] ] [ -D ] [ -f ] [ -I @var{path} ]
196 [ -K ] [ -L ] [ -o @var{objfile} ] [ -R ]
197 [ --statistics] [ -v ] [ -W ] [ -Z ]
199 @c am29k has no machine-dependent assembler options
202 @c Hitachi family chips have no machine-dependent assembler options
205 @c HPPA has no machine-dependent assembler options (yet).
208 [ -Av6 | -Av7 | -Av8 | -Asparclite | -bump ]
211 @c Z8000 has no machine-dependent assembler options
214 @c see md_parse_option in tc-i960.c
215 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
219 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
222 [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ]
224 [ -- | @var{files} @dots{} ]
229 Turn on listings, in any of a variety of ways:
233 omit debugging directives from listing
236 include high-level source
248 You may combine these options; for example, use @samp{-aln} for assembly
249 listing without forms processing. By itself, @samp{-a} defaults to
250 @samp{-ahls}---that is, all listings turned on.
253 This option is accepted only for script compatibility with calls to
254 other assemblers; it has no effect on @code{@value{AS}}.
257 ``fast''---skip whitespace and comment preprocessing (assume source is
261 Add @var{path} to the search list for @code{.include} directives
264 @ifclear DIFF-TBL-KLUGE
265 This option is accepted but has no effect on the @value{TARGET} family.
267 @ifset DIFF-TBL-KLUGE
268 Issue warnings when difference tables altered for long displacements.
272 Keep (in symbol table) local symbols, starting with @samp{L}
274 @item -o @var{objfile}
275 Name the object-file output from @code{@value{AS}}
278 Fold data section into text section
281 Display maximum space (in bytes), and total time (in seconds), taken by
285 Announce @code{as} version
288 Suppress warning messages
291 Generate object file even after errors
293 @item -- | @var{files} @dots{}
294 Standard input, or source files to assemble.
299 The following options are available when @value{AS} is configured for the
300 Intel 80960 processor.
303 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
304 Specify which variant of the 960 architecture is the target.
307 Add code to collect statistics about branches taken.
310 Do not alter compare-and-branch instructions for long displacements;
317 The following options are available when @value{AS} is configured for the
318 Motorola 68000 series.
323 Shorten references to undefined symbols, to one word instead of two.
325 @item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040
326 @itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32
327 Specify what processor in the 68000 family is the target. The default
328 is normally the 68020, but this can be changed at configuration time.
330 @item -m68881 | -m68882 | -mno-68881 | -mno-68882
331 The target machine does (or does not) have a floating-point coprocessor.
332 The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
333 the basic 68000 is not compatible with the 68881, a combination of the
334 two can be specified, since it's possible to do emulation of the
335 coprocessor instructions with the main processor.
337 @item -m68851 | -mno-68851
338 The target machine does (or does not) have a memory-management
339 unit coprocessor. The default is to assume an MMU for 68020 and up.
345 The following options are available when @code{@value{AS}} is configured
346 for the SPARC architecture:
349 @item -Av6 | -Av7 | -Av8 | -Asparclite
350 Explicitly select a variant of the SPARC architecture.
353 Warn when the assembler switches to another architecture.
358 The following options are available when @value{AS} is configured for
359 the MIPS R2000/R3000 processors.
363 This option sets the largest size of an object that can be referenced
364 implicitly with the @code{gp} register. It is only accepted for targets
365 that use ECOFF format, such as a DECstation running Ultrix. The default
368 @cindex MIPS endianness
369 @cindex endianness, MIPS
371 @cindex big endian output, MIPS
372 Generate ``big endian'' format output.
375 @cindex little endian output, MIPS
376 Generate ``little endian'' format output.
379 This option is ignored. It is accepted for compatibility with the native
385 * Manual:: Structure of this Manual
386 * GNU Assembler:: @value{AS}, the GNU Assembler
387 * Object Formats:: Object File Formats
388 * Command Line:: Command Line
389 * Input Files:: Input Files
390 * Object:: Output (Object) File
391 * Errors:: Error and Warning Messages
395 @section Structure of this Manual
397 @cindex manual, structure and purpose
398 This manual is intended to describe what you need to know to use
399 @sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including
400 notation for symbols, constants, and expressions; the directives that
401 @code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}.
404 We also cover special features in the @value{TARGET}
405 configuration of @code{@value{AS}}, including assembler directives.
408 This manual also describes some of the machine-dependent features of
409 various flavors of the assembler.
412 @cindex machine instructions (not covered)
413 On the other hand, this manual is @emph{not} intended as an introduction
414 to programming in assembly language---let alone programming in general!
415 In a similar vein, we make no attempt to introduce the machine
416 architecture; we do @emph{not} describe the instruction set, standard
417 mnemonics, registers or addressing modes that are standard to a
418 particular architecture.
420 You may want to consult the manufacturer's
421 machine architecture manual for this information.
425 For information on the H8/300 machine instruction set, see @cite{H8/300
426 Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H,
427 see @cite{H8/300H Series Programming Manual} (Hitachi).
430 For information on the H8/500 machine instruction set, see @cite{H8/500
431 Series Programming Manual} (Hitachi M21T001).
434 For information on the Hitachi SH machine instruction set, see
435 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
438 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
442 @c I think this is premature---pesch@cygnus.com, 17jan1991
444 Throughout this manual, we assume that you are running @dfn{GNU},
445 the portable operating system from the @dfn{Free Software
446 Foundation, Inc.}. This restricts our attention to certain kinds of
447 computer (in particular, the kinds of computers that GNU can run on);
448 once this assumption is granted examples and definitions need less
451 @code{@value{AS}} is part of a team of programs that turn a high-level
452 human-readable series of instructions into a low-level
453 computer-readable series of instructions. Different versions of
454 @code{@value{AS}} are used for different kinds of computer.
457 @c There used to be a section "Terminology" here, which defined
458 @c "contents", "byte", "word", and "long". Defining "word" to any
459 @c particular size is confusing when the .word directive may generate 16
460 @c bits on one machine and 32 bits on another; in general, for the user
461 @c version of this manual, none of these terms seem essential to define.
462 @c They were used very little even in the former draft of the manual;
463 @c this draft makes an effort to avoid them (except in names of
467 @section @value{AS}, the GNU Assembler
469 GNU @code{as} is really a family of assemblers.
471 This manual describes @code{@value{AS}}, a member of that family which is
472 configured for the @value{TARGET} architectures.
474 If you use (or have used) the GNU assembler on one architecture, you
475 should find a fairly similar environment when you use it on another
476 architecture. Each version has much in common with the others,
477 including object file formats, most assembler directives (often called
478 @dfn{pseudo-ops}) and assembler syntax.@refill
480 @cindex purpose of @sc{gnu} @code{@value{AS}}
481 @code{@value{AS}} is primarily intended to assemble the output of the
482 GNU C compiler @code{@value{GCC}} for use by the linker
483 @code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}}
484 assemble correctly everything that other assemblers for the same
485 machine would assemble.
487 Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
490 @c This remark should appear in generic version of manual; assumption
491 @c here is that generic version sets M680x0.
492 This doesn't mean @code{@value{AS}} always uses the same syntax as another
493 assembler for the same architecture; for example, we know of several
494 incompatible versions of 680x0 assembly language syntax.
497 Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
498 program in one pass of the source file. This has a subtle impact on the
499 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
502 @section Object File Formats
504 @cindex object file format
505 The GNU assembler can be configured to produce several alternative
506 object file formats. For the most part, this does not affect how you
507 write assembly language programs; but directives for debugging symbols
508 are typically different in different file formats. @xref{Symbol
509 Attributes,,Symbol Attributes}.
512 On the @value{TARGET}, @code{@value{AS}} is configured to produce
513 @value{OBJ-NAME} format object files.
515 @c The following should exhaust all configs that set MULTI-OBJ, ideally
517 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
518 @code{a.out} or COFF format object files.
521 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
522 @code{b.out} or COFF format object files.
525 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
526 SOM or ELF format object files.
531 @section Command Line
533 @cindex command line conventions
534 After the program name @code{@value{AS}}, the command line may contain
535 options and file names. Options may appear in any order, and may be
536 before, after, or between file names. The order of file names is
539 @cindex standard input, as input file
541 @file{--} (two hyphens) by itself names the standard input file
542 explicitly, as one of the files for @code{@value{AS}} to assemble.
544 @cindex options, command line
545 Except for @samp{--} any command line argument that begins with a
546 hyphen (@samp{-}) is an option. Each option changes the behavior of
547 @code{@value{AS}}. No option changes the way another option works. An
548 option is a @samp{-} followed by one or more letters; the case of
549 the letter is important. All options are optional.
551 Some options expect exactly one file name to follow them. The file
552 name may either immediately follow the option's letter (compatible
553 with older assemblers) or it may be the next command argument (GNU
554 standard). These two command lines are equivalent:
557 @value{AS} -o my-object-file.o mumble.s
558 @value{AS} -omy-object-file.o mumble.s
565 @cindex source program
567 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
568 describe the program input to one run of @code{@value{AS}}. The program may
569 be in one or more files; how the source is partitioned into files
570 doesn't change the meaning of the source.
572 @c I added "con" prefix to "catenation" just to prove I can overcome my
573 @c APL training... pesch@cygnus.com
574 The source program is a concatenation of the text in all the files, in the
577 Each time you run @code{@value{AS}} it assembles exactly one source
578 program. The source program is made up of one or more files.
579 (The standard input is also a file.)
581 You give @code{@value{AS}} a command line that has zero or more input file
582 names. The input files are read (from left file name to right). A
583 command line argument (in any position) that has no special meaning
584 is taken to be an input file name.
586 If you give @code{@value{AS}} no file names it attempts to read one input file
587 from the @code{@value{AS}} standard input, which is normally your terminal. You
588 may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program
591 Use @samp{--} if you need to explicitly name the standard input file
592 in your command line.
594 If the source is empty, @code{@value{AS}} produces a small, empty object
597 @subheading Filenames and Line-numbers
599 @cindex input file linenumbers
600 @cindex line numbers, in input files
601 There are two ways of locating a line in the input file (or files) and
602 either may be used in reporting error messages. One way refers to a line
603 number in a physical file; the other refers to a line number in a
604 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
606 @dfn{Physical files} are those files named in the command line given
607 to @code{@value{AS}}.
609 @dfn{Logical files} are simply names declared explicitly by assembler
610 directives; they bear no relation to physical files. Logical file names
611 help error messages reflect the original source file, when @code{@value{AS}}
612 source is itself synthesized from other files.
613 @xref{App-File,,@code{.app-file}}.
616 @section Output (Object) File
622 Every time you run @code{@value{AS}} it produces an output file, which is
623 your assembly language program translated into numbers. This file
624 is the object file. Its default name is
632 @code{b.out} when @code{@value{AS}} is configured for the Intel 80960.
634 You can give it another name by using the @code{-o} option. Conventionally,
635 object file names end with @file{.o}. The default name is used for historical
636 reasons: older assemblers were capable of assembling self-contained programs
637 directly into a runnable program. (For some formats, this isn't currently
638 possible, but it can be done for the @code{a.out} format.)
642 The object file is meant for input to the linker @code{@value{LD}}. It contains
643 assembled program code, information to help @code{@value{LD}} integrate
644 the assembled program into a runnable file, and (optionally) symbolic
645 information for the debugger.
647 @c link above to some info file(s) like the description of a.out.
648 @c don't forget to describe GNU info as well as Unix lossage.
651 @section Error and Warning Messages
653 @cindex error messsages
654 @cindex warning messages
655 @cindex messages from @code{@value{AS}}
656 @code{@value{AS}} may write warnings and error messages to the standard error
657 file (usually your terminal). This should not happen when a compiler
658 runs @code{@value{AS}} automatically. Warnings report an assumption made so
659 that @code{@value{AS}} could keep assembling a flawed program; errors report a
660 grave problem that stops the assembly.
662 @cindex format of warning messages
663 Warning messages have the format
666 file_name:@b{NNN}:Warning Message Text
670 @cindex line numbers, in warnings/errors
671 (where @b{NNN} is a line number). If a logical file name has been given
672 (@pxref{App-File,,@code{.app-file}}) it is used for the filename,
673 otherwise the name of the current input file is used. If a logical line
676 (@pxref{Line,,@code{.line}})
680 (@pxref{Line,,@code{.line}})
683 (@pxref{Ln,,@code{.ln}})
686 then it is used to calculate the number printed,
687 otherwise the actual line in the current source file is printed. The
688 message text is intended to be self explanatory (in the grand Unix
691 @cindex format of error messages
692 Error messages have the format
694 file_name:@b{NNN}:FATAL:Error Message Text
696 The file name and line number are derived as for warning
697 messages. The actual message text may be rather less explanatory
698 because many of them aren't supposed to happen.
701 @chapter Command-Line Options
703 @cindex options, all versions of @code{@value{AS}}
704 This chapter describes command-line options available in @emph{all}
705 versions of the GNU assembler; @pxref{Machine Dependencies}, for options specific
707 to the @value{TARGET}.
710 to particular machine architectures.
713 If you are invoking @code{@value{AS}} via the GNU C compiler (version 2), you
714 can use the @samp{-Wa} option to pass arguments through to the
715 assembler. The assembler arguments must be separated from each other
716 (and the @samp{-Wa}) by commas. For example:
719 gcc -c -g -O -Wa,-alh,-L file.c
723 emits a listing to standard output with high-level
726 Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
727 command-line options are automatically passed to the assembler by the compiler.
728 (You can call the GNU compiler driver with the @samp{-v} option to see
729 precisely what options it passes to each compilation pass, including the
733 * a:: -a[dhlns] enable listings
734 * D:: -D for compatibility
735 * f:: -f to work faster
736 * I:: -I for .include search path
737 @ifclear DIFF-TBL-KLUGE
738 * K:: -K for compatibility
740 @ifset DIFF-TBL-KLUGE
741 * K:: -K for difference tables
744 * L:: -L to retain local labels
745 * o:: -o to name the object file
746 * R:: -R to join data and text sections
747 * statistics:: --statistics to see statistics about assembly
748 * v:: -v to announce version
749 * W:: -W to suppress warnings
750 * Z:: -Z to make object file even after errors
754 @section Enable Listings: @code{-a[dhlns]}
762 @cindex listings, enabling
763 @cindex assembly listings, enabling
765 These options enable listing output from the assembler. By itself,
766 @samp{-a} requests high-level, assembly, and symbols listing.
767 Other letters may be used to select specific options for the list:
768 @samp{-ah} requests a high-level language listing,
769 @samp{-al} requests an output-program assembly listing, and
770 @samp{-as} requests a symbol table listing.
771 High-level listings require that a compiler debugging option like
772 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
775 The @samp{-ad} option may be used to omit debugging directives from the
778 Once you have specified one of these options, you can further control
779 listing output and its appearance using the directives @code{.list},
780 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
782 The @samp{-an} option turns off all forms processing.
783 If you do not request listing output with one of the @samp{-a} options, the
784 listing-control directives have no effect.
786 The letters after @samp{-a} may be combined into one option,
787 @emph{e.g.}, @samp{-aln}.
793 This option has no effect whatsoever, but it is accepted to make it more
794 likely that scripts written for other assemblers also work with
798 @section Work Faster: @code{-f}
801 @cindex trusted compiler
802 @cindex faster processing (@code{-f})
803 @samp{-f} should only be used when assembling programs written by a
804 (trusted) compiler. @samp{-f} stops the assembler from doing whitespace
805 and comment preprocessing on
806 the input file(s) before assembling them. @xref{Preprocessing,
810 @emph{Warning:} if you use @samp{-f} when the files actually need to be
811 preprocessed (if they contain comments, for example), @code{@value{AS}} does
816 @section @code{.include} search path: @code{-I} @var{path}
818 @kindex -I @var{path}
819 @cindex paths for @code{.include}
820 @cindex search path for @code{.include}
821 @cindex @code{include} directive search path
822 Use this option to add a @var{path} to the list of directories
823 @code{@value{AS}} searches for files specified in @code{.include}
824 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
825 many times as necessary to include a variety of paths. The current
826 working directory is always searched first; after that, @code{@value{AS}}
827 searches any @samp{-I} directories in the same order as they were
828 specified (left to right) on the command line.
831 @section Difference Tables: @code{-K}
834 @ifclear DIFF-TBL-KLUGE
835 On the @value{TARGET} family, this option is allowed, but has no effect. It is
836 permitted for compatibility with the GNU assembler on other platforms,
837 where it can be used to warn when the assembler alters the machine code
838 generated for @samp{.word} directives in difference tables. The @value{TARGET}
839 family does not have the addressing limitations that sometimes lead to this
840 alteration on other platforms.
843 @ifset DIFF-TBL-KLUGE
844 @cindex difference tables, warning
845 @cindex warning for altered difference tables
846 @code{@value{AS}} sometimes alters the code emitted for directives of the form
847 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
848 You can use the @samp{-K} option if you want a warning issued when this
853 @section Include Local Labels: @code{-L}
856 @cindex local labels, retaining in output
857 Labels beginning with @samp{L} (upper case only) are called @dfn{local
858 labels}. @xref{Symbol Names}. Normally you do not see such labels when
859 debugging, because they are intended for the use of programs (like
860 compilers) that compose assembler programs, not for your notice.
861 Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not
862 normally debug with them.
864 This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols
865 in the object file. Usually if you do this you also tell the linker
866 @code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
868 By default, a local label is any label beginning with @samp{L}, but each
869 target is allowed to redefine the local label prefix.
871 On the HPPA local labels begin with @samp{L$}.
875 @section Name the Object File: @code{-o}
878 @cindex naming object file
879 @cindex object file name
880 There is always one object file output when you run @code{@value{AS}}. By
881 default it has the name
884 @file{a.out} (or @file{b.out}, for Intel 960 targets only).
898 You use this option (which takes exactly one filename) to give the
899 object file a different name.
901 Whatever the object file is called, @code{@value{AS}} overwrites any
902 existing file of the same name.
905 @section Join Data and Text Sections: @code{-R}
908 @cindex data and text sections, joining
909 @cindex text and data sections, joining
910 @cindex joining text and data sections
911 @cindex merging text and data sections
912 @code{-R} tells @code{@value{AS}} to write the object file as if all
913 data-section data lives in the text section. This is only done at
914 the very last moment: your binary data are the same, but data
915 section parts are relocated differently. The data section part of
916 your object file is zero bytes long because all its bytes are
917 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
919 When you specify @code{-R} it would be possible to generate shorter
920 address displacements (because we do not have to cross between text and
921 data section). We refrain from doing this simply for compatibility with
922 older versions of @code{@value{AS}}. In future, @code{-R} may work this way.
925 When @code{@value{AS}} is configured for COFF output,
926 this option is only useful if you use sections named @samp{.text} and
931 @code{-R} is not supported for any of the HPPA targets. Using
932 @code{-R} generates a warning from @code{@value{AS}}.
936 @section Display Assembly Statistics: @code{--statistics}
939 @cindex statistics, about assembly
940 @cindex time, total for assembly
941 @cindex space used, maximum for assembly
942 Use @samp{--statistics} to display two statistics about the resources used by
943 @code{@value{AS}}: the maximum amount of space allocated during the assembly
944 (in bytes), and the total execution time taken for the assembly (in @sc{cpu}
948 @section Announce Version: @code{-v}
952 @cindex @code{@value{AS}} version
953 @cindex version of @code{@value{AS}}
954 You can find out what version of as is running by including the
955 option @samp{-v} (which you can also spell as @samp{-version}) on the
959 @section Suppress Warnings: @code{-W}
962 @cindex suppressing warnings
963 @cindex warnings, suppressing
964 @code{@value{AS}} should never give a warning or error message when
965 assembling compiler output. But programs written by people often
966 cause @code{@value{AS}} to give a warning that a particular assumption was
967 made. All such warnings are directed to the standard error file.
968 If you use this option, no warnings are issued. This option only
969 affects the warning messages: it does not change any particular of how
970 @code{@value{AS}} assembles your file. Errors, which stop the assembly, are
974 @section Generate Object File in Spite of Errors: @code{-Z}
975 @cindex object file, after errors
976 @cindex errors, continuing after
977 After an error message, @code{@value{AS}} normally produces no output. If for
978 some reason you are interested in object file output even after
979 @code{@value{AS}} gives an error message on your program, use the @samp{-Z}
980 option. If there are any errors, @code{@value{AS}} continues anyways, and
981 writes an object file after a final warning message of the form @samp{@var{n}
982 errors, @var{m} warnings, generating bad object file.}
987 @cindex machine-independent syntax
988 @cindex syntax, machine-independent
989 This chapter describes the machine-independent syntax allowed in a
990 source file. @code{@value{AS}} syntax is similar to what many other
991 assemblers use; it is inspired by the BSD 4.2
996 assembler, except that @code{@value{AS}} does not assemble Vax bit-fields.
1000 * Preprocessing:: Preprocessing
1001 * Whitespace:: Whitespace
1002 * Comments:: Comments
1003 * Symbol Intro:: Symbols
1004 * Statements:: Statements
1005 * Constants:: Constants
1009 @section Preprocessing
1011 @cindex preprocessing
1012 The @code{@value{AS}} internal preprocessor:
1014 @cindex whitespace, removed by preprocessor
1016 adjusts and removes extra whitespace. It leaves one space or tab before
1017 the keywords on a line, and turns any other whitespace on the line into
1020 @cindex comments, removed by preprocessor
1022 removes all comments, replacing them with a single space, or an
1023 appropriate number of newlines.
1025 @cindex constants, converted by preprocessor
1027 converts character constants into the appropriate numeric values.
1030 Note that it does not do macro processing, include file handling, or
1031 anything else you may get from your C compiler's preprocessor. You can
1032 do include file processing with the @code{.include} directive
1033 (@pxref{Include,,@code{.include}}). Other ``CPP'' style preprocessing
1034 can be done with the @sc{GNU} C compiler, by giving the input file a
1035 @samp{.S} suffix; see the compiler documentation for details.
1037 Excess whitespace, comments, and character constants
1038 cannot be used in the portions of the input text that are not
1041 @cindex turning preprocessing on and off
1042 @cindex preprocessing, turning on and off
1045 If the first line of an input file is @code{#NO_APP} or if you use the
1046 @samp{-f} option, whitespace and comments are not removed from the input file.
1047 Within an input file, you can ask for whitespace and comment removal in
1048 specific portions of the by putting a line that says @code{#APP} before the
1049 text that may contain whitespace or comments, and putting a line that says
1050 @code{#NO_APP} after this text. This feature is mainly intend to support
1051 @code{asm} statements in compilers whose output is otherwise free of comments
1058 @dfn{Whitespace} is one or more blanks or tabs, in any order.
1059 Whitespace is used to separate symbols, and to make programs neater for
1060 people to read. Unless within character constants
1061 (@pxref{Characters,,Character Constants}), any whitespace means the same
1062 as exactly one space.
1068 There are two ways of rendering comments to @code{@value{AS}}. In both
1069 cases the comment is equivalent to one space.
1071 Anything from @samp{/*} through the next @samp{*/} is a comment.
1072 This means you may not nest these comments.
1076 The only way to include a newline ('\n') in a comment
1077 is to use this sort of comment.
1080 /* This sort of comment does not nest. */
1083 @cindex line comment character
1084 Anything from the @dfn{line comment} character to the next newline
1085 is considered a comment and is ignored. The line comment character is
1087 @samp{#} on the Vax;
1090 @samp{#} on the i960;
1093 @samp{!} on the SPARC;
1096 @samp{|} on the 680x0;
1099 @samp{;} for the AMD 29K family;
1102 @samp{;} for the H8/300 family;
1105 @samp{!} for the H8/500 family;
1108 @samp{;} for the HPPA;
1111 @samp{!} for the Hitachi SH;
1114 @samp{!} for the Z8000;
1116 see @ref{Machine Dependencies}. @refill
1117 @c FIXME What about i386, m88k, i860?
1120 On some machines there are two different line comment characters. One
1121 character only begins a comment if it is the first non-whitespace character on
1122 a line, while the other always begins a comment.
1126 @cindex lines starting with @code{#}
1127 @cindex logical line numbers
1128 To be compatible with past assemblers, a special interpretation is given to
1129 lines that begin with @samp{#}. Following the @samp{#} should be an absolute
1130 expression (@pxref{Expressions}): the logical line number of the @emph{next}
1131 line. Then a string (@xref{Strings}.) is allowed: if present it is a new
1132 logical file name. The rest of the line, if any, should be whitespace.
1134 If the first non-whitespace characters on the line are not numeric,
1135 the line is ignored. (Just like a comment.)
1137 # This is an ordinary comment.
1138 # 42-6 "new_file_name" # New logical file name
1139 # This is logical line # 36.
1141 This feature is deprecated, and may disappear from future versions
1142 of @code{@value{AS}}.
1147 @cindex characters used in symbols
1148 @ifclear SPECIAL-SYMS
1149 A @dfn{symbol} is one or more characters chosen from the set of all
1150 letters (both upper and lower case), digits and the three characters
1156 A @dfn{symbol} is one or more characters chosen from the set of all
1157 letters (both upper and lower case), digits and the three characters
1158 @samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in
1164 On most machines, you can also use @code{$} in symbol names; exceptions
1165 are noted in @ref{Machine Dependencies}.
1167 No symbol may begin with a digit. Case is significant.
1168 There is no length limit: all characters are significant. Symbols are
1169 delimited by characters not in that set, or by the beginning of a file
1170 (since the source program must end with a newline, the end of a file is
1171 not a possible symbol delimiter). @xref{Symbols}.
1172 @cindex length of symbols
1177 @cindex statements, structure of
1178 @cindex line separator character
1179 @cindex statement separator character
1181 @ifclear abnormal-separator
1182 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
1183 semicolon (@samp{;}). The newline or semicolon is considered part of
1184 the preceding statement. Newlines and semicolons within character
1185 constants are an exception: they do not end statements.
1187 @ifset abnormal-separator
1189 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
1190 sign (@samp{@@}). The newline or at sign is considered part of the
1191 preceding statement. Newlines and at signs within character constants
1192 are an exception: they do not end statements.
1195 A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation
1196 point (@samp{!}). The newline or exclamation point is considered part of the
1197 preceding statement. Newlines and exclamation points within character
1198 constants are an exception: they do not end statements.
1201 A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
1202 H8/300) a dollar sign (@samp{$}); or (for the
1205 (@samp{;}). The newline or separator character is considered part of
1206 the preceding statement. Newlines and separators within character
1207 constants are an exception: they do not end statements.
1212 A @dfn{statement} ends at a newline character (@samp{\n}) or line
1213 separator character. (The line separator is usually @samp{;}, unless
1214 this conflicts with the comment character; @pxref{Machine Dependencies}.) The
1215 newline or separator character is considered part of the preceding
1216 statement. Newlines and separators within character constants are an
1217 exception: they do not end statements.
1220 @cindex newline, required at file end
1221 @cindex EOF, newline must precede
1222 It is an error to end any statement with end-of-file: the last
1223 character of any input file should be a newline.@refill
1225 @cindex continuing statements
1226 @cindex multi-line statements
1227 @cindex statement on multiple lines
1228 You may write a statement on more than one line if you put a
1229 backslash (@kbd{\}) immediately in front of any newlines within the
1230 statement. When @code{@value{AS}} reads a backslashed newline both
1231 characters are ignored. You can even put backslashed newlines in
1232 the middle of symbol names without changing the meaning of your
1235 An empty statement is allowed, and may include whitespace. It is ignored.
1237 @cindex instructions and directives
1238 @cindex directives and instructions
1239 @c "key symbol" is not used elsewhere in the document; seems pedantic to
1240 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
1242 A statement begins with zero or more labels, optionally followed by a
1243 key symbol which determines what kind of statement it is. The key
1244 symbol determines the syntax of the rest of the statement. If the
1245 symbol begins with a dot @samp{.} then the statement is an assembler
1246 directive: typically valid for any computer. If the symbol begins with
1247 a letter the statement is an assembly language @dfn{instruction}: it
1248 assembles into a machine language instruction.
1250 Different versions of @code{@value{AS}} for different computers
1251 recognize different instructions. In fact, the same symbol may
1252 represent a different instruction in a different computer's assembly
1256 @cindex @code{:} (label)
1257 @cindex label (@code{:})
1258 A label is a symbol immediately followed by a colon (@code{:}).
1259 Whitespace before a label or after a colon is permitted, but you may not
1260 have whitespace between a label's symbol and its colon. @xref{Labels}.
1263 For HPPA targets, labels need not be immediately followed by a colon, but
1264 the definition of a label must begin in column zero. This also implies that
1265 only one label may be defined on each line.
1269 label: .directive followed by something
1270 another_label: # This is an empty statement.
1271 instruction operand_1, operand_2, @dots{}
1278 A constant is a number, written so that its value is known by
1279 inspection, without knowing any context. Like this:
1282 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
1283 .ascii "Ring the bell\7" # A string constant.
1284 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
1285 .float 0f-314159265358979323846264338327\
1286 95028841971.693993751E-40 # - pi, a flonum.
1291 * Characters:: Character Constants
1292 * Numbers:: Number Constants
1296 @subsection Character Constants
1298 @cindex character constants
1299 @cindex constants, character
1300 There are two kinds of character constants. A @dfn{character} stands
1301 for one character in one byte and its value may be used in
1302 numeric expressions. String constants (properly called string
1303 @emph{literals}) are potentially many bytes and their values may not be
1304 used in arithmetic expressions.
1308 * Chars:: Characters
1312 @subsubsection Strings
1314 @cindex string constants
1315 @cindex constants, string
1316 A @dfn{string} is written between double-quotes. It may contain
1317 double-quotes or null characters. The way to get special characters
1318 into a string is to @dfn{escape} these characters: precede them with
1319 a backslash @samp{\} character. For example @samp{\\} represents
1320 one backslash: the first @code{\} is an escape which tells
1321 @code{@value{AS}} to interpret the second character literally as a backslash
1322 (which prevents @code{@value{AS}} from recognizing the second @code{\} as an
1323 escape character). The complete list of escapes follows.
1325 @cindex escape codes, character
1326 @cindex character escape codes
1329 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1332 @cindex @code{\b} (backspace character)
1333 @cindex backspace (@code{\b})
1334 Mnemonic for backspace; for ASCII this is octal code 010.
1337 @c Mnemonic for EOText; for ASCII this is octal code 004.
1340 @cindex @code{\f} (formfeed character)
1341 @cindex formfeed (@code{\f})
1342 Mnemonic for FormFeed; for ASCII this is octal code 014.
1345 @cindex @code{\n} (newline character)
1346 @cindex newline (@code{\n})
1347 Mnemonic for newline; for ASCII this is octal code 012.
1350 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1353 @cindex @code{\r} (carriage return character)
1354 @cindex carriage return (@code{\r})
1355 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1358 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1359 @c other assemblers.
1362 @cindex @code{\t} (tab)
1363 @cindex tab (@code{\t})
1364 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1367 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1368 @c @item \x @var{digit} @var{digit} @var{digit}
1369 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1371 @item \ @var{digit} @var{digit} @var{digit}
1372 @cindex @code{\@var{ddd}} (octal character code)
1373 @cindex octal character code (@code{\@var{ddd}})
1374 An octal character code. The numeric code is 3 octal digits.
1375 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1376 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1379 @item \@code{x} @var{hex-digit} @var{hex-digit}
1380 @cindex @code{\@var{xdd}} (hex character code)
1381 @cindex hex character code (@code{\@var{xdd}})
1382 A hex character code. The numeric code is 2 hexadecimal digits. Either
1383 upper or lower case @code{x} works.
1387 @cindex @code{\\} (@samp{\} character)
1388 @cindex backslash (@code{\\})
1389 Represents one @samp{\} character.
1392 @c Represents one @samp{'} (accent acute) character.
1393 @c This is needed in single character literals
1394 @c (@xref{Characters,,Character Constants}.) to represent
1398 @cindex @code{\"} (doublequote character)
1399 @cindex doublequote (@code{\"})
1400 Represents one @samp{"} character. Needed in strings to represent
1401 this character, because an unescaped @samp{"} would end the string.
1403 @item \ @var{anything-else}
1404 Any other character when escaped by @kbd{\} gives a warning, but
1405 assemble as if the @samp{\} was not present. The idea is that if
1406 you used an escape sequence you clearly didn't want the literal
1407 interpretation of the following character. However @code{@value{AS}} has no
1408 other interpretation, so @code{@value{AS}} knows it is giving you the wrong
1409 code and warns you of the fact.
1412 Which characters are escapable, and what those escapes represent,
1413 varies widely among assemblers. The current set is what we think
1414 the BSD 4.2 assembler recognizes, and is a subset of what most C
1415 compilers recognize. If you are in doubt, do not use an escape
1419 @subsubsection Characters
1421 @cindex single character constant
1422 @cindex character, single
1423 @cindex constant, single character
1424 A single character may be written as a single quote immediately
1425 followed by that character. The same escapes apply to characters as
1426 to strings. So if you want to write the character backslash, you
1427 must write @kbd{'\\} where the first @code{\} escapes the second
1428 @code{\}. As you can see, the quote is an acute accent, not a
1429 grave accent. A newline
1431 @ifclear abnormal-separator
1432 (or semicolon @samp{;})
1434 @ifset abnormal-separator
1436 (or at sign @samp{@@})
1439 (or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
1445 immediately following an acute accent is taken as a literal character
1446 and does not count as the end of a statement. The value of a character
1447 constant in a numeric expression is the machine's byte-wide code for
1448 that character. @code{@value{AS}} assumes your character code is ASCII:
1449 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1452 @subsection Number Constants
1454 @cindex constants, number
1455 @cindex number constants
1456 @code{@value{AS}} distinguishes three kinds of numbers according to how they
1457 are stored in the target machine. @emph{Integers} are numbers that
1458 would fit into an @code{int} in the C language. @emph{Bignums} are
1459 integers, but they are stored in more than 32 bits. @emph{Flonums}
1460 are floating point numbers, described below.
1463 * Integers:: Integers
1468 * Bit Fields:: Bit Fields
1474 @subsubsection Integers
1476 @cindex constants, integer
1478 @cindex binary integers
1479 @cindex integers, binary
1480 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1481 the binary digits @samp{01}.
1483 @cindex octal integers
1484 @cindex integers, octal
1485 An octal integer is @samp{0} followed by zero or more of the octal
1486 digits (@samp{01234567}).
1488 @cindex decimal integers
1489 @cindex integers, decimal
1490 A decimal integer starts with a non-zero digit followed by zero or
1491 more digits (@samp{0123456789}).
1493 @cindex hexadecimal integers
1494 @cindex integers, hexadecimal
1495 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1496 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1498 Integers have the usual values. To denote a negative integer, use
1499 the prefix operator @samp{-} discussed under expressions
1500 (@pxref{Prefix Ops,,Prefix Operators}).
1503 @subsubsection Bignums
1506 @cindex constants, bignum
1507 A @dfn{bignum} has the same syntax and semantics as an integer
1508 except that the number (or its negative) takes more than 32 bits to
1509 represent in binary. The distinction is made because in some places
1510 integers are permitted while bignums are not.
1513 @subsubsection Flonums
1515 @cindex floating point numbers
1516 @cindex constants, floating point
1518 @cindex precision, floating point
1519 A @dfn{flonum} represents a floating point number. The translation is
1520 indirect: a decimal floating point number from the text is converted by
1521 @code{@value{AS}} to a generic binary floating point number of more than
1522 sufficient precision. This generic floating point number is converted
1523 to a particular computer's floating point format (or formats) by a
1524 portion of @code{@value{AS}} specialized to that computer.
1526 A flonum is written by writing (in order)
1531 (@samp{0} is optional on the HPPA.)
1535 A letter, to tell @code{@value{AS}} the rest of the number is a flonum.
1537 @kbd{e} is recommended. Case is not important.
1539 @c FIXME: verify if flonum syntax really this vague for most cases
1540 (Any otherwise illegal letter works here, but that might be changed. Vax BSD
1541 4.2 assembler seems to allow any of @samp{defghDEFGH}.)
1544 On the H8/300, H8/500,
1546 and AMD 29K architectures, the letter must be
1547 one of the letters @samp{DFPRSX} (in upper or lower case).
1549 On the Intel 960 architecture, the letter must be
1550 one of the letters @samp{DFT} (in upper or lower case).
1552 On the HPPA architecture, the letter must be @samp{E} (upper case only).
1556 One of the letters @samp{DFPRSX} (in upper or lower case).
1559 One of the letters @samp{DFPRSX} (in upper or lower case).
1562 One of the letters @samp{DFT} (in upper or lower case).
1565 The letter @samp{E} (upper case only).
1570 An optional sign: either @samp{+} or @samp{-}.
1573 An optional @dfn{integer part}: zero or more decimal digits.
1576 An optional @dfn{fractional part}: @samp{.} followed by zero
1577 or more decimal digits.
1580 An optional exponent, consisting of:
1584 An @samp{E} or @samp{e}.
1585 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1586 @c principle this can perfectly well be different on different targets.
1588 Optional sign: either @samp{+} or @samp{-}.
1590 One or more decimal digits.
1595 At least one of the integer part or the fractional part must be
1596 present. The floating point number has the usual base-10 value.
1598 @code{@value{AS}} does all processing using integers. Flonums are computed
1599 independently of any floating point hardware in the computer running
1604 @c Bit fields are written as a general facility but are also controlled
1605 @c by a conditional-compilation flag---which is as of now (21mar91)
1606 @c turned on only by the i960 config of GAS.
1608 @subsubsection Bit Fields
1611 @cindex constants, bit field
1612 You can also define numeric constants as @dfn{bit fields}.
1613 specify two numbers separated by a colon---
1615 @var{mask}:@var{value}
1618 @code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
1621 The resulting number is then packed
1623 @c this conditional paren in case bit fields turned on elsewhere than 960
1624 (in host-dependent byte order)
1626 into a field whose width depends on which assembler directive has the
1627 bit-field as its argument. Overflow (a result from the bitwise and
1628 requiring more binary digits to represent) is not an error; instead,
1629 more constants are generated, of the specified width, beginning with the
1630 least significant digits.@refill
1632 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1633 @code{.short}, and @code{.word} accept bit-field arguments.
1638 @chapter Sections and Relocation
1643 * Secs Background:: Background
1644 * Ld Sections:: @value{LD} Sections
1645 * As Sections:: @value{AS} Internal Sections
1646 * Sub-Sections:: Sub-Sections
1650 @node Secs Background
1653 Roughly, a section is a range of addresses, with no gaps; all data
1654 ``in'' those addresses is treated the same for some particular purpose.
1655 For example there may be a ``read only'' section.
1657 @cindex linker, and assembler
1658 @cindex assembler, and linker
1659 The linker @code{@value{LD}} reads many object files (partial programs) and
1660 combines their contents to form a runnable program. When @code{@value{AS}}
1661 emits an object file, the partial program is assumed to start at address 0.
1662 @code{@value{LD}} assigns the final addresses for the partial program, so that
1663 different partial programs do not overlap. This is actually an
1664 oversimplification, but it suffices to explain how @code{@value{AS}} uses
1667 @code{@value{LD}} moves blocks of bytes of your program to their run-time
1668 addresses. These blocks slide to their run-time addresses as rigid
1669 units; their length does not change and neither does the order of bytes
1670 within them. Such a rigid unit is called a @emph{section}. Assigning
1671 run-time addresses to sections is called @dfn{relocation}. It includes
1672 the task of adjusting mentions of object-file addresses so they refer to
1673 the proper run-time addresses.
1675 For the H8/300 and H8/500,
1676 and for the Hitachi SH,
1677 @code{@value{AS}} pads sections if needed to
1678 ensure they end on a word (sixteen bit) boundary.
1681 @cindex standard @code{@value{AS}} sections
1682 An object file written by @code{@value{AS}} has at least three sections, any
1683 of which may be empty. These are named @dfn{text}, @dfn{data} and
1688 When it generates COFF output,
1690 @code{@value{AS}} can also generate whatever other named sections you specify
1691 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1692 If you do not use any directives that place output in the @samp{.text}
1693 or @samp{.data} sections, these sections still exist, but are empty.
1698 When @code{@value{AS}} generates SOM or ELF output for the HPPA,
1700 @code{@value{AS}} can also generate whatever other named sections you
1701 specify using the @samp{.space} and @samp{.subspace} directives. See
1702 @cite{HP9000 Series 800 Assembly Language Reference Manual}
1703 (HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
1704 assembler directives.
1707 Additionally, @code{@value{AS}} uses different names for the standard
1708 text, data, and bss sections when generating SOM output. Program text
1709 is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
1710 BSS into @samp{$BSS$}.
1714 Within the object file, the text section starts at address @code{0}, the
1715 data section follows, and the bss section follows the data section.
1718 When generating either SOM or ELF output files on the HPPA, the text
1719 section starts at address @code{0}, the data section at address
1720 @code{0x4000000}, and the bss section follows the data section.
1723 To let @code{@value{LD}} know which data changes when the sections are
1724 relocated, and how to change that data, @code{@value{AS}} also writes to the
1725 object file details of the relocation needed. To perform relocation
1726 @code{@value{LD}} must know, each time an address in the object
1730 Where in the object file is the beginning of this reference to
1733 How long (in bytes) is this reference?
1735 Which section does the address refer to? What is the numeric value of
1737 (@var{address}) @minus{} (@var{start-address of section})?
1740 Is the reference to an address ``Program-Counter relative''?
1743 @cindex addresses, format of
1744 @cindex section-relative addressing
1745 In fact, every address @code{@value{AS}} ever uses is expressed as
1747 (@var{section}) + (@var{offset into section})
1750 Further, most expressions @code{@value{AS}} computes have this section-relative
1753 (For some object formats, such as SOM for the HPPA, some expressions are
1754 symbol-relative instead.)
1756 @dfn{Absolute expression} means an expression with section
1757 ``absolute'' (@pxref{Ld Sections}). A @dfn{pass1 expression} means
1758 an expression with section ``pass1'' (@pxref{As Sections,,@value{AS}
1759 Internal Sections}). In this manual we use the notation @{@var{secname}
1760 @var{N}@} to mean ``offset @var{N} into section @var{secname}''.
1762 Apart from text, data and bss sections you need to know about the
1763 @dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
1764 addresses in the absolute section remain unchanged. For example, address
1765 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
1766 @code{@value{LD}}. Although the linker never arranges two partial programs'
1767 data sections with overlapping addresses after linking, @emph{by definition}
1768 their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one
1769 part of a program is always the same address when the program is running as
1770 address @code{@{absolute@ 239@}} in any other part of the program.
1772 The idea of sections is extended to the @dfn{undefined} section. Any
1773 address whose section is unknown at assembly time is by definition
1774 rendered @{undefined @var{U}@}---where @var{U} is filled in later.
1775 Since numbers are always defined, the only way to generate an undefined
1776 address is to mention an undefined symbol. A reference to a named
1777 common block would be such a symbol: its value is unknown at assembly
1778 time so it has section @emph{undefined}.
1780 By analogy the word @emph{section} is used to describe groups of sections in
1781 the linked program. @code{@value{LD}} puts all partial programs' text
1782 sections in contiguous addresses in the linked program. It is
1783 customary to refer to the @emph{text section} of a program, meaning all
1784 the addresses of all partial programs' text sections. Likewise for
1785 data and bss sections.
1787 Some sections are manipulated by @code{@value{LD}}; others are invented for
1788 use of @code{@value{AS}} and have no meaning except during assembly.
1791 @section @value{LD} Sections
1792 @code{@value{LD}} deals with just four kinds of sections, summarized below.
1797 @cindex named sections
1798 @cindex sections, named
1799 @item named sections
1802 @cindex text section
1803 @cindex data section
1807 These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as
1808 separate but equal sections. Anything you can say of one section is
1811 When the program is running, however, it is
1812 customary for the text section to be unalterable. The
1813 text section is often shared among processes: it contains
1814 instructions, constants and the like. The data section of a running
1815 program is usually alterable: for example, C variables would be stored
1816 in the data section.
1821 This section contains zeroed bytes when your program begins running. It
1822 is used to hold unitialized variables or common storage. The length of
1823 each partial program's bss section is important, but because it starts
1824 out containing zeroed bytes there is no need to store explicit zero
1825 bytes in the object file. The bss section was invented to eliminate
1826 those explicit zeros from object files.
1828 @cindex absolute section
1829 @item absolute section
1830 Address 0 of this section is always ``relocated'' to runtime address 0.
1831 This is useful if you want to refer to an address that @code{@value{LD}} must
1832 not change when relocating. In this sense we speak of absolute
1833 addresses being ``unrelocatable'': they do not change during relocation.
1835 @cindex undefined section
1836 @item undefined section
1837 This ``section'' is a catch-all for address references to objects not in
1838 the preceding sections.
1839 @c FIXME: ref to some other doc on obj-file formats could go here.
1842 @cindex relocation example
1843 An idealized example of three relocatable sections follows.
1845 The example uses the traditional section names @samp{.text} and @samp{.data}.
1847 Memory addresses are on the horizontal axis.
1851 @c END TEXI2ROFF-KILL
1854 partial program # 1: |ttttt|dddd|00|
1861 partial program # 2: |TTT|DDD|000|
1864 +--+---+-----+--+----+---+-----+~~
1865 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1866 +--+---+-----+--+----+---+-----+~~
1868 addresses: 0 @dots{}
1872 @c FIXME make sure no page breaks inside figure!!
1875 \line{\it Partial program \#1: \hfil}
1876 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1877 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1879 \line{\it Partial program \#2: \hfil}
1880 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1881 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1883 \line{\it linked program: \hfil}
1884 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1885 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1886 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1887 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1889 \line{\it addresses: \hfil}
1893 @c END TEXI2ROFF-KILL
1896 @section @value{AS} Internal Sections
1898 @cindex internal @code{@value{AS}} sections
1899 @cindex sections in messages, internal
1900 These sections are meant only for the internal use of @code{@value{AS}}. They
1901 have no meaning at run-time. You do not really need to know about these
1902 sections for most purposes; but they can be mentioned in @code{@value{AS}}
1903 warning messages, so it might be helpful to have an idea of their
1904 meanings to @code{@value{AS}}. These sections are used to permit the
1905 value of every expression in your assembly language program to be a
1906 section-relative address.
1909 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
1910 @cindex assembler internal logic error
1911 An internal assembler logic error has been found. This means there is a
1912 bug in the assembler.
1915 @cindex expr (internal section)
1916 The assembler stores complex expression internally as combinations of
1917 symbols. When it needs to represent an expression as a symbol, it puts
1918 it in the expr section.
1920 @c FIXME item transfer[t] vector preload
1921 @c FIXME item transfer[t] vector postload
1922 @c FIXME item register
1926 @section Sub-Sections
1928 @cindex numbered subsections
1929 @cindex grouping data
1935 fall into two sections: text and data.
1937 You may have separate groups of
1939 data in named sections
1943 data in named sections
1949 that you want to end up near to each other in the object file, even though they
1950 are not contiguous in the assembler source. @code{@value{AS}} allows you to
1951 use @dfn{subsections} for this purpose. Within each section, there can be
1952 numbered subsections with values from 0 to 8192. Objects assembled into the
1953 same subsection go into the object file together with other objects in the same
1954 subsection. For example, a compiler might want to store constants in the text
1955 section, but might not want to have them interspersed with the program being
1956 assembled. In this case, the compiler could issue a @samp{.text 0} before each
1957 section of code being output, and a @samp{.text 1} before each group of
1958 constants being output.
1960 Subsections are optional. If you do not use subsections, everything
1961 goes in subsection number zero.
1964 Each subsection is zero-padded up to a multiple of four bytes.
1965 (Subsections may be padded a different amount on different flavors
1966 of @code{@value{AS}}.)
1970 On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
1971 boundary (two bytes).
1972 The same is true on the Hitachi SH.
1975 @c FIXME section padding (alignment)?
1976 @c Rich Pixley says padding here depends on target obj code format; that
1977 @c doesn't seem particularly useful to say without further elaboration,
1978 @c so for now I say nothing about it. If this is a generic BFD issue,
1979 @c these paragraphs might need to vanish from this manual, and be
1980 @c discussed in BFD chapter of binutils (or some such).
1983 On the AMD 29K family, no particular padding is added to section or
1984 subsection sizes; @value{AS} forces no alignment on this platform.
1988 Subsections appear in your object file in numeric order, lowest numbered
1989 to highest. (All this to be compatible with other people's assemblers.)
1990 The object file contains no representation of subsections; @code{@value{LD}} and
1991 other programs that manipulate object files see no trace of them.
1992 They just see all your text subsections as a text section, and all your
1993 data subsections as a data section.
1995 To specify which subsection you want subsequent statements assembled
1996 into, use a numeric argument to specify it, in a @samp{.text
1997 @var{expression}} or a @samp{.data @var{expression}} statement.
2000 When generating COFF output, you
2005 can also use an extra subsection
2006 argument with arbitrary named sections: @samp{.section @var{name},
2009 @var{Expression} should be an absolute expression.
2010 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
2011 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
2012 begins in @code{text 0}. For instance:
2014 .text 0 # The default subsection is text 0 anyway.
2015 .ascii "This lives in the first text subsection. *"
2017 .ascii "But this lives in the second text subsection."
2019 .ascii "This lives in the data section,"
2020 .ascii "in the first data subsection."
2022 .ascii "This lives in the first text section,"
2023 .ascii "immediately following the asterisk (*)."
2026 Each section has a @dfn{location counter} incremented by one for every byte
2027 assembled into that section. Because subsections are merely a convenience
2028 restricted to @code{@value{AS}} there is no concept of a subsection location
2029 counter. There is no way to directly manipulate a location counter---but the
2030 @code{.align} directive changes it, and any label definition captures its
2031 current value. The location counter of the section where statements are being
2032 assembled is said to be the @dfn{active} location counter.
2035 @section bss Section
2038 @cindex common variable storage
2039 The bss section is used for local common variable storage.
2040 You may allocate address space in the bss section, but you may
2041 not dictate data to load into it before your program executes. When
2042 your program starts running, all the contents of the bss
2043 section are zeroed bytes.
2045 Addresses in the bss section are allocated with special directives; you
2046 may not assemble anything directly into the bss section. Hence there
2047 are no bss subsections. @xref{Comm,,@code{.comm}},
2048 @pxref{Lcomm,,@code{.lcomm}}.
2054 Symbols are a central concept: the programmer uses symbols to name
2055 things, the linker uses symbols to link, and the debugger uses symbols
2059 @cindex debuggers, and symbol order
2060 @emph{Warning:} @code{@value{AS}} does not place symbols in the object file in
2061 the same order they were declared. This may break some debuggers.
2066 * Setting Symbols:: Giving Symbols Other Values
2067 * Symbol Names:: Symbol Names
2068 * Dot:: The Special Dot Symbol
2069 * Symbol Attributes:: Symbol Attributes
2076 A @dfn{label} is written as a symbol immediately followed by a colon
2077 @samp{:}. The symbol then represents the current value of the
2078 active location counter, and is, for example, a suitable instruction
2079 operand. You are warned if you use the same symbol to represent two
2080 different locations: the first definition overrides any other
2084 On the HPPA, the usual form for a label need not be immediately followed by a
2085 colon, but instead must start in column zero. Only one label may be defined on
2086 a single line. To work around this, the HPPA version of @code{@value{AS}} also
2087 provides a special directive @code{.label} for defining labels more flexibly.
2090 @node Setting Symbols
2091 @section Giving Symbols Other Values
2093 @cindex assigning values to symbols
2094 @cindex symbol values, assigning
2095 A symbol can be given an arbitrary value by writing a symbol, followed
2096 by an equals sign @samp{=}, followed by an expression
2097 (@pxref{Expressions}). This is equivalent to using the @code{.set}
2098 directive. @xref{Set,,@code{.set}}.
2101 @section Symbol Names
2103 @cindex symbol names
2104 @cindex names, symbol
2105 @ifclear SPECIAL-SYMS
2106 Symbol names begin with a letter or with one of @samp{._}. On most
2107 machines, you can also use @code{$} in symbol names; exceptions are
2108 noted in @ref{Machine Dependencies}. That character may be followed by any
2109 string of digits, letters, dollar signs (unless otherwise noted in
2110 @ref{Machine Dependencies}), and underscores.
2113 For the AMD 29K family, @samp{?} is also allowed in the
2114 body of a symbol name, though not at its beginning.
2119 Symbol names begin with a letter or with one of @samp{._}. On the
2121 H8/500, you can also use @code{$} in symbol names. That character may
2122 be followed by any string of digits, letters, dollar signs (save on the
2123 H8/300), and underscores.
2127 Case of letters is significant: @code{foo} is a different symbol name
2130 Each symbol has exactly one name. Each name in an assembly language program
2131 refers to exactly one symbol. You may use that symbol name any number of times
2134 @subheading Local Symbol Names
2136 @cindex local symbol names
2137 @cindex symbol names, local
2138 @cindex temporary symbol names
2139 @cindex symbol names, temporary
2140 Local symbols help compilers and programmers use names temporarily.
2141 There are ten local symbol names, which are re-used throughout the
2142 program. You may refer to them using the names @samp{0} @samp{1}
2143 @dots{} @samp{9}. To define a local symbol, write a label of the form
2144 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
2145 recent previous definition of that symbol write @samp{@b{N}b}, using the
2146 same digit as when you defined the label. To refer to the next
2147 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
2148 a choice of 10 forward references. The @samp{b} stands for
2149 ``backwards'' and the @samp{f} stands for ``forwards''.
2151 Local symbols are not emitted by the current GNU C compiler.
2153 There is no restriction on how you can use these labels, but
2154 remember that at any point in the assembly you can refer to at most
2155 10 prior local labels and to at most 10 forward local labels.
2157 Local symbol names are only a notation device. They are immediately
2158 transformed into more conventional symbol names before the assembler
2159 uses them. The symbol names stored in the symbol table, appearing in
2160 error messages and optionally emitted to the object file have these
2165 All local labels begin with @samp{L}. Normally both @code{@value{AS}} and
2166 @code{@value{LD}} forget symbols that start with @samp{L}. These labels are
2167 used for symbols you are never intended to see. If you use the
2168 @samp{-L} option then @code{@value{AS}} retains these symbols in the
2169 object file. If you also instruct @code{@value{LD}} to retain these symbols,
2170 you may use them in debugging.
2173 If the label is written @samp{0:} then the digit is @samp{0}.
2174 If the label is written @samp{1:} then the digit is @samp{1}.
2175 And so on up through @samp{9:}.
2178 This unusual character is included so you do not accidentally invent
2179 a symbol of the same name. The character has ASCII value
2182 @item @emph{ordinal number}
2183 This is a serial number to keep the labels distinct. The first
2184 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
2185 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
2189 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
2190 @code{3:} is named @code{L3@ctrl{A}44}.
2193 @section The Special Dot Symbol
2195 @cindex dot (symbol)
2196 @cindex @code{.} (symbol)
2197 @cindex current address
2198 @cindex location counter
2199 The special symbol @samp{.} refers to the current address that
2200 @code{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
2201 .long .} defines @code{melvin} to contain its own address.
2202 Assigning a value to @code{.} is treated the same as a @code{.org}
2203 directive. Thus, the expression @samp{.=.+4} is the same as saying
2204 @ifclear no-space-dir
2213 @node Symbol Attributes
2214 @section Symbol Attributes
2216 @cindex symbol attributes
2217 @cindex attributes, symbol
2218 Every symbol has, as well as its name, the attributes ``Value'' and
2219 ``Type''. Depending on output format, symbols can also have auxiliary
2222 The detailed definitions are in @file{a.out.h}.
2225 If you use a symbol without defining it, @code{@value{AS}} assumes zero for
2226 all these attributes, and probably won't warn you. This makes the
2227 symbol an externally defined symbol, which is generally what you
2231 * Symbol Value:: Value
2232 * Symbol Type:: Type
2235 * a.out Symbols:: Symbol Attributes: @code{a.out}
2239 * a.out Symbols:: Symbol Attributes: @code{a.out}
2242 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
2247 * COFF Symbols:: Symbol Attributes for COFF
2250 * SOM Symbols:: Symbol Attributes for SOM
2257 @cindex value of a symbol
2258 @cindex symbol value
2259 The value of a symbol is (usually) 32 bits. For a symbol which labels a
2260 location in the text, data, bss or absolute sections the value is the
2261 number of addresses from the start of that section to the label.
2262 Naturally for text, data and bss sections the value of a symbol changes
2263 as @code{@value{LD}} changes section base addresses during linking. Absolute
2264 symbols' values do not change during linking: that is why they are
2267 The value of an undefined symbol is treated in a special way. If it is
2268 0 then the symbol is not defined in this assembler source file, and
2269 @code{@value{LD}} tries to determine its value from other files linked into the
2270 same program. You make this kind of symbol simply by mentioning a symbol
2271 name without defining it. A non-zero value represents a @code{.comm}
2272 common declaration. The value is how much common storage to reserve, in
2273 bytes (addresses). The symbol refers to the first address of the
2279 @cindex type of a symbol
2281 The type attribute of a symbol contains relocation (section)
2282 information, any flag settings indicating that a symbol is external, and
2283 (optionally), other information for linkers and debuggers. The exact
2284 format depends on the object-code output format in use.
2289 @c The following avoids a "widow" subsection title. @group would be
2290 @c better if it were available outside examples.
2293 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
2295 @cindex @code{b.out} symbol attributes
2296 @cindex symbol attributes, @code{b.out}
2297 These symbol attributes appear only when @code{@value{AS}} is configured for
2298 one of the Berkeley-descended object output formats---@code{a.out} or
2304 @subsection Symbol Attributes: @code{a.out}
2306 @cindex @code{a.out} symbol attributes
2307 @cindex symbol attributes, @code{a.out}
2313 @subsection Symbol Attributes: @code{a.out}
2315 @cindex @code{a.out} symbol attributes
2316 @cindex symbol attributes, @code{a.out}
2320 * Symbol Desc:: Descriptor
2321 * Symbol Other:: Other
2325 @subsubsection Descriptor
2327 @cindex descriptor, of @code{a.out} symbol
2328 This is an arbitrary 16-bit value. You may establish a symbol's
2329 descriptor value by using a @code{.desc} statement
2330 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
2334 @subsubsection Other
2336 @cindex other attribute, of @code{a.out} symbol
2337 This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}.
2342 @subsection Symbol Attributes for COFF
2344 @cindex COFF symbol attributes
2345 @cindex symbol attributes, COFF
2347 The COFF format supports a multitude of auxiliary symbol attributes;
2348 like the primary symbol attributes, they are set between @code{.def} and
2349 @code{.endef} directives.
2351 @subsubsection Primary Attributes
2353 @cindex primary attributes, COFF symbols
2354 The symbol name is set with @code{.def}; the value and type,
2355 respectively, with @code{.val} and @code{.type}.
2357 @subsubsection Auxiliary Attributes
2359 @cindex auxiliary attributes, COFF symbols
2360 The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
2361 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2362 information for COFF.
2367 @subsection Symbol Attributes for SOM
2369 @cindex SOM symbol attributes
2370 @cindex symbol attributes, SOM
2372 The SOM format for the HPPA supports a multitude of symbol attributes set with
2373 the @code{.EXPORT} and @code{.IMPORT} directives.
2375 The attributes are described in @cite{HP9000 Series 800 Assembly
2376 Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
2377 @code{EXPORT} assembler directive documentation.
2381 @chapter Expressions
2385 @cindex numeric values
2386 An @dfn{expression} specifies an address or numeric value.
2387 Whitespace may precede and/or follow an expression.
2390 * Empty Exprs:: Empty Expressions
2391 * Integer Exprs:: Integer Expressions
2395 @section Empty Expressions
2397 @cindex empty expressions
2398 @cindex expressions, empty
2399 An empty expression has no value: it is just whitespace or null.
2400 Wherever an absolute expression is required, you may omit the
2401 expression, and @code{@value{AS}} assumes a value of (absolute) 0. This
2402 is compatible with other assemblers.
2405 @section Integer Expressions
2407 @cindex integer expressions
2408 @cindex expressions, integer
2409 An @dfn{integer expression} is one or more @emph{arguments} delimited
2410 by @emph{operators}.
2413 * Arguments:: Arguments
2414 * Operators:: Operators
2415 * Prefix Ops:: Prefix Operators
2416 * Infix Ops:: Infix Operators
2420 @subsection Arguments
2422 @cindex expression arguments
2423 @cindex arguments in expressions
2424 @cindex operands in expressions
2425 @cindex arithmetic operands
2426 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2427 contexts arguments are sometimes called ``arithmetic operands''. In
2428 this manual, to avoid confusing them with the ``instruction operands'' of
2429 the machine language, we use the term ``argument'' to refer to parts of
2430 expressions only, reserving the word ``operand'' to refer only to machine
2431 instruction operands.
2433 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2434 @var{section} is one of text, data, bss, absolute,
2435 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2438 Numbers are usually integers.
2440 A number can be a flonum or bignum. In this case, you are warned
2441 that only the low order 32 bits are used, and @code{@value{AS}} pretends
2442 these 32 bits are an integer. You may write integer-manipulating
2443 instructions that act on exotic constants, compatible with other
2446 @cindex subexpressions
2447 Subexpressions are a left parenthesis @samp{(} followed by an integer
2448 expression, followed by a right parenthesis @samp{)}; or a prefix
2449 operator followed by an argument.
2452 @subsection Operators
2454 @cindex operators, in expressions
2455 @cindex arithmetic functions
2456 @cindex functions, in expressions
2457 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2458 operators are followed by an argument. Infix operators appear
2459 between their arguments. Operators may be preceded and/or followed by
2463 @subsection Prefix Operator
2465 @cindex prefix operators
2466 @code{@value{AS}} has the following @dfn{prefix operators}. They each take
2467 one argument, which must be absolute.
2469 @c the tex/end tex stuff surrounding this small table is meant to make
2470 @c it align, on the printed page, with the similar table in the next
2471 @c section (which is inside an enumerate).
2473 \global\advance\leftskip by \itemindent
2478 @dfn{Negation}. Two's complement negation.
2480 @dfn{Complementation}. Bitwise not.
2484 \global\advance\leftskip by -\itemindent
2488 @subsection Infix Operators
2490 @cindex infix operators
2491 @cindex operators, permitted arguments
2492 @dfn{Infix operators} take two arguments, one on either side. Operators
2493 have precedence, but operations with equal precedence are performed left
2494 to right. Apart from @code{+} or @code{-}, both arguments must be
2495 absolute, and the result is absolute.
2498 @cindex operator precedence
2499 @cindex precedence of operators
2506 @dfn{Multiplication}.
2509 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2516 @dfn{Shift Left}. Same as the C operator @samp{<<}.
2520 @dfn{Shift Right}. Same as the C operator @samp{>>}.
2524 Intermediate precedence
2529 @dfn{Bitwise Inclusive Or}.
2535 @dfn{Bitwise Exclusive Or}.
2538 @dfn{Bitwise Or Not}.
2546 @cindex addition, permitted arguments
2547 @cindex plus, permitted arguments
2548 @cindex arguments for addition
2549 @dfn{Addition}. If either argument is absolute, the result
2550 has the section of the other argument.
2551 If either argument is pass1 or undefined, the result is pass1.
2552 Otherwise @code{+} is illegal.
2555 @cindex subtraction, permitted arguments
2556 @cindex minus, permitted arguments
2557 @cindex arguments for subtraction
2558 @dfn{Subtraction}. If the right argument is absolute, the
2559 result has the section of the left argument.
2560 If either argument is pass1 the result is pass1.
2561 If either argument is undefined the result is difference section.
2562 If both arguments are in the same section, the result is absolute---provided
2563 that section is one of text, data or bss.
2564 Otherwise subtraction is illegal.
2568 The sense of the rule for addition is that it's only meaningful to add
2569 the @emph{offsets} in an address; you can only have a defined section in
2570 one of the two arguments.
2572 Similarly, you can't subtract quantities from two different sections.
2575 @chapter Assembler Directives
2577 @cindex directives, machine independent
2578 @cindex pseudo-ops, machine independent
2579 @cindex machine independent directives
2580 All assembler directives have names that begin with a period (@samp{.}).
2581 The rest of the name is letters, usually in lower case.
2583 This chapter discusses directives that are available regardless of the
2584 target machine configuration for the GNU assembler.
2586 Some machine configurations provide additional directives.
2587 @xref{Machine Dependencies}.
2590 @ifset machine-directives
2591 @xref{Machine Dependencies} for additional directives.
2596 * Abort:: @code{.abort}
2598 * ABORT:: @code{.ABORT}
2601 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2602 * App-File:: @code{.app-file @var{string}}
2603 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2604 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2605 * Byte:: @code{.byte @var{expressions}}
2606 * Comm:: @code{.comm @var{symbol} , @var{length} }
2607 * Data:: @code{.data @var{subsection}}
2609 * Def:: @code{.def @var{name}}
2612 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2618 * Double:: @code{.double @var{flonums}}
2619 * Eject:: @code{.eject}
2620 * Else:: @code{.else}
2622 * Endef:: @code{.endef}
2625 * Endif:: @code{.endif}
2626 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2627 * Extern:: @code{.extern}
2628 @ifclear no-file-dir
2629 * File:: @code{.file @var{string}}
2632 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2633 * Float:: @code{.float @var{flonums}}
2634 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2635 * hword:: @code{.hword @var{expressions}}
2636 * Ident:: @code{.ident}
2637 * If:: @code{.if @var{absolute expression}}
2638 * Include:: @code{.include "@var{file}"}
2639 * Int:: @code{.int @var{expressions}}
2640 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2641 * Lflags:: @code{.lflags}
2642 @ifclear no-line-dir
2643 * Line:: @code{.line @var{line-number}}
2646 * Ln:: @code{.ln @var{line-number}}
2647 * List:: @code{.list}
2648 * Long:: @code{.long @var{expressions}}
2650 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2653 * Nolist:: @code{.nolist}
2654 * Octa:: @code{.octa @var{bignums}}
2655 * Org:: @code{.org @var{new-lc} , @var{fill}}
2656 * Psize:: @code{.psize @var{lines}, @var{columns}}
2657 * Quad:: @code{.quad @var{bignums}}
2658 * Sbttl:: @code{.sbttl "@var{subheading}"}
2660 * Scl:: @code{.scl @var{class}}
2663 * Section:: @code{.section @var{name}, @var{subsection}}
2666 * Set:: @code{.set @var{symbol}, @var{expression}}
2667 * Short:: @code{.short @var{expressions}}
2668 * Single:: @code{.single @var{flonums}}
2670 * Size:: @code{.size}
2673 * Space:: @code{.space @var{size} , @var{fill}}
2675 * Stab:: @code{.stabd, .stabn, .stabs}
2678 * String:: @code{.string "@var{str}"}
2680 * Tag:: @code{.tag @var{structname}}
2683 * Text:: @code{.text @var{subsection}}
2684 * Title:: @code{.title "@var{heading}"}
2686 * Type:: @code{.type @var{int}}
2687 * Val:: @code{.val @var{addr}}
2690 * Word:: @code{.word @var{expressions}}
2691 * Deprecated:: Deprecated Directives
2695 @section @code{.abort}
2697 @cindex @code{abort} directive
2698 @cindex stopping the assembly
2699 This directive stops the assembly immediately. It is for
2700 compatibility with other assemblers. The original idea was that the
2701 assembly language source would be piped into the assembler. If the sender
2702 of the source quit, it could use this directive tells @code{@value{AS}} to
2703 quit also. One day @code{.abort} will not be supported.
2707 @section @code{.ABORT}
2709 @cindex @code{ABORT} directive
2710 When producing COFF output, @code{@value{AS}} accepts this directive as a
2711 synonym for @samp{.abort}.
2714 When producing @code{b.out} output, @code{@value{AS}} accepts this directive,
2720 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2722 @cindex padding the location counter
2723 @cindex @code{align} directive
2724 Pad the location counter (in the current subsection) to a particular
2725 storage boundary. The first expression (which must be absolute) is the
2726 number of low-order zero bits the location counter must have after
2727 advancement. For example @samp{.align 3} advances the location
2728 counter until it a multiple of 8. If the location counter is already a
2729 multiple of 8, no change is needed.
2732 For the HPPA, the first expression (which must be absolute) is the
2733 alignment request in bytes. For example @samp{.align 8} advances
2734 the location counter until it is a multiple of 8. If the location counter
2735 is already a multiple of 8, no change is needed.
2738 The second expression (also absolute) gives the value to be stored in
2739 the padding bytes. It (and the comma) may be omitted. If it is
2740 omitted, the padding bytes are zero.
2743 @section @code{.app-file @var{string}}
2745 @cindex logical file name
2746 @cindex file name, logical
2747 @cindex @code{app-file} directive
2749 @ifclear no-file-dir
2750 (which may also be spelled @samp{.file})
2752 tells @code{@value{AS}} that we are about to start a new
2753 logical file. @var{string} is the new file name. In general, the
2754 filename is recognized whether or not it is surrounded by quotes @samp{"};
2755 but if you wish to specify an empty file name is permitted,
2756 you must give the quotes--@code{""}. This statement may go away in
2757 future: it is only recognized to be compatible with old @code{@value{AS}}
2761 @section @code{.ascii "@var{string}"}@dots{}
2763 @cindex @code{ascii} directive
2764 @cindex string literals
2765 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2766 separated by commas. It assembles each string (with no automatic
2767 trailing zero byte) into consecutive addresses.
2770 @section @code{.asciz "@var{string}"}@dots{}
2772 @cindex @code{asciz} directive
2773 @cindex zero-terminated strings
2774 @cindex null-terminated strings
2775 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2776 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2779 @section @code{.byte @var{expressions}}
2781 @cindex @code{byte} directive
2782 @cindex integers, one byte
2783 @code{.byte} expects zero or more expressions, separated by commas.
2784 Each expression is assembled into the next byte.
2787 @section @code{.comm @var{symbol} , @var{length} }
2789 @cindex @code{comm} directive
2790 @cindex symbol, common
2791 @code{.comm} declares a named common area in the bss section. Normally
2792 @code{@value{LD}} reserves memory addresses for it during linking, so no partial
2793 program defines the location of the symbol. Use @code{.comm} to tell
2794 @code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}}
2795 allocates space for each @code{.comm} symbol that is at least as
2796 long as the longest @code{.comm} request in any of the partial programs
2797 linked. @var{length} is an absolute expression.
2800 The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
2801 @samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
2805 @section @code{.data @var{subsection}}
2807 @cindex @code{data} directive
2808 @code{.data} tells @code{@value{AS}} to assemble the following statements onto the
2809 end of the data subsection numbered @var{subsection} (which is an
2810 absolute expression). If @var{subsection} is omitted, it defaults
2815 @section @code{.def @var{name}}
2817 @cindex @code{def} directive
2818 @cindex COFF symbols, debugging
2819 @cindex debugging COFF symbols
2820 Begin defining debugging information for a symbol @var{name}; the
2821 definition extends until the @code{.endef} directive is encountered.
2824 This directive is only observed when @code{@value{AS}} is configured for COFF
2825 format output; when producing @code{b.out}, @samp{.def} is recognized,
2832 @section @code{.desc @var{symbol}, @var{abs-expression}}
2834 @cindex @code{desc} directive
2835 @cindex COFF symbol descriptor
2836 @cindex symbol descriptor, COFF
2837 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2838 to the low 16 bits of an absolute expression.
2841 The @samp{.desc} directive is not available when @code{@value{AS}} is
2842 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2843 object format. For the sake of compatibility, @code{@value{AS}} accepts
2844 it, but produces no output, when configured for COFF.
2850 @section @code{.dim}
2852 @cindex @code{dim} directive
2853 @cindex COFF auxiliary symbol information
2854 @cindex auxiliary symbol information, COFF
2855 This directive is generated by compilers to include auxiliary debugging
2856 information in the symbol table. It is only permitted inside
2857 @code{.def}/@code{.endef} pairs.
2860 @samp{.dim} is only meaningful when generating COFF format output; when
2861 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
2867 @section @code{.double @var{flonums}}
2869 @cindex @code{double} directive
2870 @cindex floating point numbers (double)
2871 @code{.double} expects zero or more flonums, separated by commas. It
2872 assembles floating point numbers.
2874 The exact kind of floating point numbers emitted depends on how
2875 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
2879 On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
2880 in @sc{ieee} format.
2885 @section @code{.eject}
2887 @cindex @code{eject} directive
2888 @cindex new page, in listings
2889 @cindex page, in listings
2890 @cindex listing control: new page
2891 Force a page break at this point, when generating assembly listings.
2894 @section @code{.else}
2896 @cindex @code{else} directive
2897 @code{.else} is part of the @code{@value{AS}} support for conditional
2898 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2899 of code to be assembled if the condition for the preceding @code{.if}
2903 @node End, Endef, Else, Pseudo Ops
2904 @section @code{.end}
2906 @cindex @code{end} directive
2907 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2908 meant to do something eventually (which is why it isn't documented here
2909 as "for compatibility with blah").
2914 @section @code{.endef}
2916 @cindex @code{endef} directive
2917 This directive flags the end of a symbol definition begun with
2921 @samp{.endef} is only meaningful when generating COFF format output; if
2922 @code{@value{AS}} is configured to generate @code{b.out}, it accepts this
2923 directive but ignores it.
2928 @section @code{.endif}
2930 @cindex @code{endif} directive
2931 @code{.endif} is part of the @code{@value{AS}} support for conditional assembly;
2932 it marks the end of a block of code that is only assembled
2933 conditionally. @xref{If,,@code{.if}}.
2936 @section @code{.equ @var{symbol}, @var{expression}}
2938 @cindex @code{equ} directive
2939 @cindex assigning values to symbols
2940 @cindex symbols, assigning values to
2941 This directive sets the value of @var{symbol} to @var{expression}.
2942 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
2945 The syntax for @code{equ} on the HPPA is
2946 @samp{@var{symbol} .equ @var{expression}}.
2950 @section @code{.extern}
2952 @cindex @code{extern} directive
2953 @code{.extern} is accepted in the source program---for compatibility
2954 with other assemblers---but it is ignored. @code{@value{AS}} treats
2955 all undefined symbols as external.
2957 @ifclear no-file-dir
2959 @section @code{.file @var{string}}
2961 @cindex @code{file} directive
2962 @cindex logical file name
2963 @cindex file name, logical
2964 @code{.file} (which may also be spelled @samp{.app-file}) tells
2965 @code{@value{AS}} that we are about to start a new logical file.
2966 @var{string} is the new file name. In general, the filename is
2967 recognized whether or not it is surrounded by quotes @samp{"}; but if
2968 you wish to specify an empty file name, you must give the
2969 quotes--@code{""}. This statement may go away in future: it is only
2970 recognized to be compatible with old @code{@value{AS}} programs.
2972 In some configurations of @code{@value{AS}}, @code{.file} has already been
2973 removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}.
2978 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
2980 @cindex @code{fill} directive
2981 @cindex writing patterns in memory
2982 @cindex patterns, writing in memory
2983 @var{result}, @var{size} and @var{value} are absolute expressions.
2984 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
2985 may be zero or more. @var{Size} may be zero or more, but if it is
2986 more than 8, then it is deemed to have the value 8, compatible with
2987 other people's assemblers. The contents of each @var{repeat} bytes
2988 is taken from an 8-byte number. The highest order 4 bytes are
2989 zero. The lowest order 4 bytes are @var{value} rendered in the
2990 byte-order of an integer on the computer @code{@value{AS}} is assembling for.
2991 Each @var{size} bytes in a repetition is taken from the lowest order
2992 @var{size} bytes of this number. Again, this bizarre behavior is
2993 compatible with other people's assemblers.
2995 @var{size} and @var{value} are optional.
2996 If the second comma and @var{value} are absent, @var{value} is
2997 assumed zero. If the first comma and following tokens are absent,
2998 @var{size} is assumed to be 1.
3001 @section @code{.float @var{flonums}}
3003 @cindex floating point numbers (single)
3004 @cindex @code{float} directive
3005 This directive assembles zero or more flonums, separated by commas. It
3006 has the same effect as @code{.single}.
3008 The exact kind of floating point numbers emitted depends on how
3009 @code{@value{AS}} is configured.
3010 @xref{Machine Dependencies}.
3014 On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
3015 in @sc{ieee} format.
3020 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
3022 @cindex @code{global} directive
3023 @cindex symbol, making visible to linker
3024 @code{.global} makes the symbol visible to @code{@value{LD}}. If you define
3025 @var{symbol} in your partial program, its value is made available to
3026 other partial programs that are linked with it. Otherwise,
3027 @var{symbol} takes its attributes from a symbol of the same name
3028 from another file linked into the same program.
3030 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
3031 compatibility with other assemblers.
3034 On the HPPA, @code{.global} is not always enough to make it accessible to other
3035 partial programs. You may need the HPPA-only @code{.EXPORT} directive as well.
3036 @xref{HPPA Directives,, HPPA Assembler Directives}.
3040 @section @code{.hword @var{expressions}}
3042 @cindex @code{hword} directive
3043 @cindex integers, 16-bit
3044 @cindex numbers, 16-bit
3045 @cindex sixteen bit integers
3046 This expects zero or more @var{expressions}, and emits
3047 a 16 bit number for each.
3050 This directive is a synonym for @samp{.short}; depending on the target
3051 architecture, it may also be a synonym for @samp{.word}.
3055 This directive is a synonym for @samp{.short}.
3058 This directive is a synonym for both @samp{.short} and @samp{.word}.
3063 @section @code{.ident}
3065 @cindex @code{ident} directive
3066 This directive is used by some assemblers to place tags in object files.
3067 @code{@value{AS}} simply accepts the directive for source-file
3068 compatibility with such assemblers, but does not actually emit anything
3072 @section @code{.if @var{absolute expression}}
3074 @cindex conditional assembly
3075 @cindex @code{if} directive
3076 @code{.if} marks the beginning of a section of code which is only
3077 considered part of the source program being assembled if the argument
3078 (which must be an @var{absolute expression}) is non-zero. The end of
3079 the conditional section of code must be marked by @code{.endif}
3080 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
3081 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
3083 The following variants of @code{.if} are also supported:
3085 @item .ifdef @var{symbol}
3086 @cindex @code{ifdef} directive
3087 Assembles the following section of code if the specified @var{symbol}
3092 @cindex @code{ifeqs} directive
3093 Not yet implemented.
3096 @item .ifndef @var{symbol}
3097 @itemx ifnotdef @var{symbol}
3098 @cindex @code{ifndef} directive
3099 @cindex @code{ifnotdef} directive
3100 Assembles the following section of code if the specified @var{symbol}
3101 has not been defined. Both spelling variants are equivalent.
3105 Not yet implemented.
3110 @section @code{.include "@var{file}"}
3112 @cindex @code{include} directive
3113 @cindex supporting files, including
3114 @cindex files, including
3115 This directive provides a way to include supporting files at specified
3116 points in your source program. The code from @var{file} is assembled as
3117 if it followed the point of the @code{.include}; when the end of the
3118 included file is reached, assembly of the original file continues. You
3119 can control the search paths used with the @samp{-I} command-line option
3120 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
3124 @section @code{.int @var{expressions}}
3126 @cindex @code{int} directive
3127 @cindex integers, 32-bit
3128 Expect zero or more @var{expressions}, of any section, separated by commas.
3129 For each expression, emit a number that, at run time, is the value of that
3130 expression. The byte order and bit size of the number depends on what kind
3131 of target the assembly is for.
3135 On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
3136 integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits
3142 @section @code{.lcomm @var{symbol} , @var{length}}
3144 @cindex @code{lcomm} directive
3145 @cindex local common symbols
3146 @cindex symbols, local common
3147 Reserve @var{length} (an absolute expression) bytes for a local common
3148 denoted by @var{symbol}. The section and value of @var{symbol} are
3149 those of the new local common. The addresses are allocated in the bss
3150 section, so that at run-time the bytes start off zeroed. @var{Symbol}
3151 is not declared global (@pxref{Global,,@code{.global}}), so is normally
3152 not visible to @code{@value{LD}}.
3155 The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
3156 @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
3160 @section @code{.lflags}
3162 @cindex @code{lflags} directive (ignored)
3163 @code{@value{AS}} accepts this directive, for compatibility with other
3164 assemblers, but ignores it.
3166 @ifclear no-line-dir
3168 @section @code{.line @var{line-number}}
3170 @cindex @code{line} directive
3174 @section @code{.ln @var{line-number}}
3176 @cindex @code{ln} directive
3178 @cindex logical line number
3180 Change the logical line number. @var{line-number} must be an absolute
3181 expression. The next line has that logical line number. Therefore any other
3182 statements on the current line (after a statement separator character) are
3183 reported as on logical line number @var{line-number} @minus{} 1. One day
3184 @code{@value{AS}} will no longer support this directive: it is recognized only
3185 for compatibility with existing assembler programs.
3189 @emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
3190 not available; use the synonym @code{.ln} in that context.
3195 @ifclear no-line-dir
3196 Even though this is a directive associated with the @code{a.out} or
3197 @code{b.out} object-code formats, @code{@value{AS}} still recognizes it
3198 when producing COFF output, and treats @samp{.line} as though it
3199 were the COFF @samp{.ln} @emph{if} it is found outside a
3200 @code{.def}/@code{.endef} pair.
3202 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
3203 used by compilers to generate auxiliary symbol information for
3208 @section @code{.ln @var{line-number}}
3210 @cindex @code{ln} directive
3211 @ifclear no-line-dir
3212 @samp{.ln} is a synonym for @samp{.line}.
3215 Tell @code{@value{AS}} to change the logical line number. @var{line-number}
3216 must be an absolute expression. The next line has that logical
3217 line number, so any other statements on the current line (after a
3218 statement separator character @code{;}) are reported as on logical
3219 line number @var{line-number} @minus{} 1.
3222 This directive is accepted, but ignored, when @code{@value{AS}} is
3223 configured for @code{b.out}; its effect is only associated with COFF
3229 @section @code{.list}
3231 @cindex @code{list} directive
3232 @cindex listing control, turning on
3233 Control (in conjunction with the @code{.nolist} directive) whether or
3234 not assembly listings are generated. These two directives maintain an
3235 internal counter (which is zero initially). @code{.list} increments the
3236 counter, and @code{.nolist} decrements it. Assembly listings are
3237 generated whenever the counter is greater than zero.
3239 By default, listings are disabled. When you enable them (with the
3240 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
3241 the initial value of the listing counter is one.
3244 @section @code{.long @var{expressions}}
3246 @cindex @code{long} directive
3247 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
3250 @c no one seems to know what this is for or whether this description is
3251 @c what it really ought to do
3253 @section @code{.lsym @var{symbol}, @var{expression}}
3255 @cindex @code{lsym} directive
3256 @cindex symbol, not referenced in assembly
3257 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
3258 the hash table, ensuring it cannot be referenced by name during the
3259 rest of the assembly. This sets the attributes of the symbol to be
3260 the same as the expression value:
3262 @var{other} = @var{descriptor} = 0
3263 @var{type} = @r{(section of @var{expression})}
3264 @var{value} = @var{expression}
3267 The new symbol is not flagged as external.
3271 @section @code{.nolist}
3273 @cindex @code{nolist} directive
3274 @cindex listing control, turning off
3275 Control (in conjunction with the @code{.list} directive) whether or
3276 not assembly listings are generated. These two directives maintain an
3277 internal counter (which is zero initially). @code{.list} increments the
3278 counter, and @code{.nolist} decrements it. Assembly listings are
3279 generated whenever the counter is greater than zero.
3282 @section @code{.octa @var{bignums}}
3284 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
3285 @cindex @code{octa} directive
3286 @cindex integer, 16-byte
3287 @cindex sixteen byte integer
3288 This directive expects zero or more bignums, separated by commas. For each
3289 bignum, it emits a 16-byte integer.
3291 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
3292 hence @emph{octa}-word for 16 bytes.
3295 @section @code{.org @var{new-lc} , @var{fill}}
3297 @cindex @code{org} directive
3298 @cindex location counter, advancing
3299 @cindex advancing location counter
3300 @cindex current address, advancing
3301 Advance the location counter of the current section to
3302 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3303 expression with the same section as the current subsection. That is,
3304 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3305 wrong section, the @code{.org} directive is ignored. To be compatible
3306 with former assemblers, if the section of @var{new-lc} is absolute,
3307 @code{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
3308 is the same as the current subsection.
3310 @code{.org} may only increase the location counter, or leave it
3311 unchanged; you cannot use @code{.org} to move the location counter
3314 @c double negative used below "not undefined" because this is a specific
3315 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3316 @c section. pesch@cygnus.com 18feb91
3317 Because @code{@value{AS}} tries to assemble programs in one pass @var{new-lc}
3318 may not be undefined. If you really detest this restriction we eagerly await
3319 a chance to share your improved assembler.
3321 Beware that the origin is relative to the start of the section, not
3322 to the start of the subsection. This is compatible with other
3323 people's assemblers.
3325 When the location counter (of the current subsection) is advanced, the
3326 intervening bytes are filled with @var{fill} which should be an
3327 absolute expression. If the comma and @var{fill} are omitted,
3328 @var{fill} defaults to zero.
3331 @section @code{.psize @var{lines} , @var{columns}}
3333 @cindex @code{psize} directive
3334 @cindex listing control: paper size
3335 @cindex paper size, for listings
3336 Use this directive to declare the number of lines---and, optionally, the
3337 number of columns---to use for each page, when generating listings.
3339 If you do not use @code{.psize}, listings use a default line-count
3340 of 60. You may omit the comma and @var{columns} specification; the
3341 default width is 200 columns.
3343 @code{@value{AS}} generates formfeeds whenever the specified number of
3344 lines is exceeded (or whenever you explicitly request one, using
3347 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3348 those explicitly specified with @code{.eject}.
3351 @section @code{.quad @var{bignums}}
3353 @cindex @code{quad} directive
3354 @code{.quad} expects zero or more bignums, separated by commas. For
3355 each bignum, it emits
3357 an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
3358 warning message; and just takes the lowest order 8 bytes of the bignum.
3359 @cindex eight-byte integer
3360 @cindex integer, 8-byte
3362 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3363 hence @emph{quad}-word for 8 bytes.
3366 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3367 warning message; and just takes the lowest order 16 bytes of the bignum.
3368 @cindex sixteen-byte integer
3369 @cindex integer, 16-byte
3373 @section @code{.sbttl "@var{subheading}"}
3375 @cindex @code{sbttl} directive
3376 @cindex subtitles for listings
3377 @cindex listing control: subtitle
3378 Use @var{subheading} as the title (third line, immediately after the
3379 title line) when generating assembly listings.
3381 This directive affects subsequent pages, as well as the current page if
3382 it appears within ten lines of the top of a page.
3386 @section @code{.scl @var{class}}
3388 @cindex @code{scl} directive
3389 @cindex symbol storage class (COFF)
3390 @cindex COFF symbol storage class
3391 Set the storage-class value for a symbol. This directive may only be
3392 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3393 whether a symbol is static or external, or it may record further
3394 symbolic debugging information.
3397 The @samp{.scl} directive is primarily associated with COFF output; when
3398 configured to generate @code{b.out} output format, @code{@value{AS}}
3399 accepts this directive but ignores it.
3405 @section @code{.section @var{name}, @var{subsection}}
3407 @cindex @code{section} directive
3408 @cindex named section (COFF)
3409 @cindex COFF named section
3410 Assemble the following code into end of subsection numbered
3411 @var{subsection} in the COFF named section @var{name}. If you omit
3412 @var{subsection}, @code{@value{AS}} uses subsection number zero.
3413 @samp{.section .text} is equivalent to the @code{.text} directive;
3414 @samp{.section .data} is equivalent to the @code{.data} directive.
3418 @section @code{.set @var{symbol}, @var{expression}}
3420 @cindex @code{set} directive
3421 @cindex symbol value, setting
3422 Set the value of @var{symbol} to @var{expression}. This
3423 changes @var{symbol}'s value and type to conform to
3424 @var{expression}. If @var{symbol} was flagged as external, it remains
3425 flagged. (@xref{Symbol Attributes}.)
3427 You may @code{.set} a symbol many times in the same assembly.
3428 If the expression's section is unknowable during pass 1, a second
3429 pass over the source program is necessary. The second pass is
3430 currently not implemented. @code{@value{AS}} aborts with an error
3431 message if one is required.
3433 If you @code{.set} a global symbol, the value stored in the object
3434 file is the last value stored into it.
3437 The syntax for @code{set} on the HPPA is
3438 @samp{@var{symbol} .set @var{expression}}.
3442 @section @code{.short @var{expressions}}
3444 @cindex @code{short} directive
3446 @code{.short} is normally the same as @samp{.word}.
3447 @xref{Word,,@code{.word}}.
3449 In some configurations, however, @code{.short} and @code{.word} generate
3450 numbers of different lengths; @pxref{Machine Dependencies}.
3454 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3457 This expects zero or more @var{expressions}, and emits
3458 a 16 bit number for each.
3463 @section @code{.single @var{flonums}}
3465 @cindex @code{single} directive
3466 @cindex floating point numbers (single)
3467 This directive assembles zero or more flonums, separated by commas. It
3468 has the same effect as @code{.float}.
3470 The exact kind of floating point numbers emitted depends on how
3471 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
3475 On the @value{TARGET} family, @code{.single} emits 32-bit floating point
3476 numbers in @sc{ieee} format.
3482 @section @code{.size}
3484 @cindex @code{size} directive
3485 This directive is generated by compilers to include auxiliary debugging
3486 information in the symbol table. It is only permitted inside
3487 @code{.def}/@code{.endef} pairs.
3490 @samp{.size} is only meaningful when generating COFF format output; when
3491 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3496 @ifclear no-space-dir
3498 @section @code{.space @var{size} , @var{fill}}
3500 @cindex @code{space} directive
3501 @cindex filling memory
3502 This directive emits @var{size} bytes, each of value @var{fill}. Both
3503 @var{size} and @var{fill} are absolute expressions. If the comma
3504 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3508 @emph{Warning:} @code{.space} has a completely different meaning for HPPA
3509 targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800
3510 Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the
3511 @code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives},
3520 @section @code{.space}
3521 @cindex @code{space} directive
3523 On the AMD 29K, this directive is ignored; it is accepted for
3524 compatibility with other AMD 29K assemblers.
3527 @emph{Warning:} In most versions of the GNU assembler, the directive
3528 @code{.space} has the effect of @code{.block} @xref{Machine Dependencies}.
3534 @section @code{.stabd, .stabn, .stabs}
3536 @cindex symbolic debuggers, information for
3537 @cindex @code{stab@var{x}} directives
3538 There are three directives that begin @samp{.stab}.
3539 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3540 The symbols are not entered in the @code{@value{AS}} hash table: they
3541 cannot be referenced elsewhere in the source file.
3542 Up to five fields are required:
3546 This is the symbol's name. It may contain any character except
3547 @samp{\000}, so is more general than ordinary symbol names. Some
3548 debuggers used to code arbitrarily complex structures into symbol names
3552 An absolute expression. The symbol's type is set to the low 8 bits of
3553 this expression. Any bit pattern is permitted, but @code{@value{LD}}
3554 and debuggers choke on silly bit patterns.
3557 An absolute expression. The symbol's ``other'' attribute is set to the
3558 low 8 bits of this expression.
3561 An absolute expression. The symbol's descriptor is set to the low 16
3562 bits of this expression.
3565 An absolute expression which becomes the symbol's value.
3568 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3569 or @code{.stabs} statement, the symbol has probably already been created;
3570 you get a half-formed symbol in your object file. This is
3571 compatible with earlier assemblers!
3574 @cindex @code{stabd} directive
3575 @item .stabd @var{type} , @var{other} , @var{desc}
3577 The ``name'' of the symbol generated is not even an empty string.
3578 It is a null pointer, for compatibility. Older assemblers used a
3579 null pointer so they didn't waste space in object files with empty
3582 The symbol's value is set to the location counter,
3583 relocatably. When your program is linked, the value of this symbol
3584 is the address of the location counter when the @code{.stabd} was
3587 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3588 @cindex @code{stabn} directive
3589 The name of the symbol is set to the empty string @code{""}.
3591 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3592 @cindex @code{stabs} directive
3593 All five fields are specified.
3599 @section @code{.string} "@var{str}"
3601 @cindex string, copying to object file
3602 @cindex @code{string} directive
3604 Copy the characters in @var{str} to the object file. You may specify more than
3605 one string to copy, separated by commas. Unless otherwise specified for a
3606 particular machine, the assembler marks the end of each string with a 0 byte.
3607 You can use any of the escape sequences described in @ref{Strings,,Strings}.
3611 @section @code{.tag @var{structname}}
3613 @cindex COFF structure debugging
3614 @cindex structure debugging, COFF
3615 @cindex @code{tag} directive
3616 This directive is generated by compilers to include auxiliary debugging
3617 information in the symbol table. It is only permitted inside
3618 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3619 definitions in the symbol table with instances of those structures.
3622 @samp{.tag} is only used when generating COFF format output; when
3623 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3629 @section @code{.text @var{subsection}}
3631 @cindex @code{text} directive
3632 Tells @code{@value{AS}} to assemble the following statements onto the end of
3633 the text subsection numbered @var{subsection}, which is an absolute
3634 expression. If @var{subsection} is omitted, subsection number zero
3638 @section @code{.title "@var{heading}"}
3640 @cindex @code{title} directive
3641 @cindex listing control: title line
3642 Use @var{heading} as the title (second line, immediately after the
3643 source file name and pagenumber) when generating assembly listings.
3645 This directive affects subsequent pages, as well as the current page if
3646 it appears within ten lines of the top of a page.
3650 @section @code{.type @var{int}}
3652 @cindex COFF symbol type
3653 @cindex symbol type, COFF
3654 @cindex @code{type} directive
3655 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3656 records the integer @var{int} as the type attribute of a symbol table entry.
3659 @samp{.type} is associated only with COFF format output; when
3660 @code{@value{AS}} is configured for @code{b.out} output, it accepts this
3661 directive but ignores it.
3667 @section @code{.val @var{addr}}
3669 @cindex @code{val} directive
3670 @cindex COFF value attribute
3671 @cindex value attribute, COFF
3672 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3673 records the address @var{addr} as the value attribute of a symbol table
3677 @samp{.val} is used only for COFF output; when @code{@value{AS}} is
3678 configured for @code{b.out}, it accepts this directive but ignores it.
3683 @section @code{.word @var{expressions}}
3685 @cindex @code{word} directive
3686 This directive expects zero or more @var{expressions}, of any section,
3687 separated by commas.
3690 For each expression, @code{@value{AS}} emits a 32-bit number.
3693 For each expression, @code{@value{AS}} emits a 16-bit number.
3698 The size of the number emitted, and its byte order,
3699 depend on what target computer the assembly is for.
3702 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3703 @c happen---32-bit addressability, period; no long/short jumps.
3704 @ifset DIFF-TBL-KLUGE
3705 @cindex difference tables altered
3706 @cindex altered difference tables
3708 @emph{Warning: Special Treatment to support Compilers}
3712 Machines with a 32-bit address space, but that do less than 32-bit
3713 addressing, require the following special treatment. If the machine of
3714 interest to you does 32-bit addressing (or doesn't require it;
3715 @pxref{Machine Dependencies}), you can ignore this issue.
3718 In order to assemble compiler output into something that works,
3719 @code{@value{AS}} occasionlly does strange things to @samp{.word} directives.
3720 Directives of the form @samp{.word sym1-sym2} are often emitted by
3721 compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a
3722 directive of the form @samp{.word sym1-sym2}, and the difference between
3723 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}}
3724 creates a @dfn{secondary jump table}, immediately before the next label.
3725 This secondary jump table is preceded by a short-jump to the
3726 first byte after the secondary table. This short-jump prevents the flow
3727 of control from accidentally falling into the new table. Inside the
3728 table is a long-jump to @code{sym2}. The original @samp{.word}
3729 contains @code{sym1} minus the address of the long-jump to
3732 If there were several occurrences of @samp{.word sym1-sym2} before the
3733 secondary jump table, all of them are adjusted. If there was a
3734 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3735 long-jump to @code{sym4} is included in the secondary jump table,
3736 and the @code{.word} directives are adjusted to contain @code{sym3}
3737 minus the address of the long-jump to @code{sym4}; and so on, for as many
3738 entries in the original jump table as necessary.
3741 @emph{This feature may be disabled by compiling @code{@value{AS}} with the
3742 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3743 assembly language programmers.
3746 @c end DIFF-TBL-KLUGE
3749 @section Deprecated Directives
3751 @cindex deprecated directives
3752 @cindex obsolescent directives
3753 One day these directives won't work.
3754 They are included for compatibility with older assemblers.
3762 @node Machine Dependencies
3763 @chapter Machine Dependent Features
3765 @cindex machine dependencies
3766 The machine instruction sets are (almost by definition) different on
3767 each machine where @code{@value{AS}} runs. Floating point representations
3768 vary as well, and @code{@value{AS}} often supports a few additional
3769 directives or command-line options for compatibility with other
3770 assemblers on a particular platform. Finally, some versions of
3771 @code{@value{AS}} support special pseudo-instructions for branch
3774 This chapter discusses most of these differences, though it does not
3775 include details on any machine's instruction set. For details on that
3776 subject, see the hardware manufacturer's manual.
3780 * Vax-Dependent:: VAX Dependent Features
3783 * AMD29K-Dependent:: AMD 29K Dependent Features
3786 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
3789 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
3792 * HPPA-Dependent:: HPPA Dependent Features
3795 * SH-Dependent:: Hitachi SH Dependent Features
3798 * i960-Dependent:: Intel 80960 Dependent Features
3801 * M68K-Dependent:: M680x0 Dependent Features
3804 * Sparc-Dependent:: SPARC Dependent Features
3807 * Z8000-Dependent:: Z8000 Dependent Features
3810 * MIPS-Dependent:: MIPS Dependent Features
3813 * i386-Dependent:: 80386 Dependent Features
3820 @c The following major nodes are *sections* in the GENERIC version, *chapters*
3821 @c in single-cpu versions. This is mainly achieved by @lowersections. There is a
3822 @c peculiarity: to preserve cross-references, there must be a node called
3823 @c "Machine Dependencies". Hence the conditional nodenames in each
3824 @c major node below. Node defaulting in makeinfo requires adjacency of
3825 @c node and sectioning commands; hence the repetition of @chapter BLAH
3826 @c in both conditional blocks.
3831 @chapter VAX Dependent Features
3836 @node Machine Dependencies
3837 @chapter VAX Dependent Features
3843 * Vax-Opts:: VAX Command-Line Options
3844 * VAX-float:: VAX Floating Point
3845 * VAX-directives:: Vax Machine Directives
3846 * VAX-opcodes:: VAX Opcodes
3847 * VAX-branch:: VAX Branch Improvement
3848 * VAX-operands:: VAX Operands
3849 * VAX-no:: Not Supported on VAX
3854 @section VAX Command-Line Options
3856 @cindex command-line options ignored, VAX
3857 @cindex VAX command-line options ignored
3858 The Vax version of @code{@value{AS}} accepts any of the following options,
3859 gives a warning message that the option was ignored and proceeds.
3860 These options are for compatibility with scripts designed for other
3861 people's assemblers.
3864 @item @code{-D} (Debug)
3865 @itemx @code{-S} (Symbol Table)
3866 @itemx @code{-T} (Token Trace)
3867 @cindex @code{-D}, ignored on VAX
3868 @cindex @code{-S}, ignored on VAX
3869 @cindex @code{-T}, ignored on VAX
3870 These are obsolete options used to debug old assemblers.
3872 @item @code{-d} (Displacement size for JUMPs)
3873 @cindex @code{-d}, VAX option
3874 This option expects a number following the @samp{-d}. Like options
3875 that expect filenames, the number may immediately follow the
3876 @samp{-d} (old standard) or constitute the whole of the command line
3877 argument that follows @samp{-d} (GNU standard).
3879 @item @code{-V} (Virtualize Interpass Temporary File)
3880 @cindex @code{-V}, redundant on VAX
3881 Some other assemblers use a temporary file. This option
3882 commanded them to keep the information in active memory rather
3883 than in a disk file. @code{@value{AS}} always does this, so this
3884 option is redundant.
3886 @item @code{-J} (JUMPify Longer Branches)
3887 @cindex @code{-J}, ignored on VAX
3888 Many 32-bit computers permit a variety of branch instructions
3889 to do the same job. Some of these instructions are short (and
3890 fast) but have a limited range; others are long (and slow) but
3891 can branch anywhere in virtual memory. Often there are 3
3892 flavors of branch: short, medium and long. Some other
3893 assemblers would emit short and medium branches, unless told by
3894 this option to emit short and long branches.
3896 @item @code{-t} (Temporary File Directory)
3897 @cindex @code{-t}, ignored on VAX
3898 Some other assemblers may use a temporary file, and this option
3899 takes a filename being the directory to site the temporary
3900 file. Since @code{@value{AS}} does not use a temporary disk file, this
3901 option makes no difference. @samp{-t} needs exactly one
3905 @cindex VMS (VAX) options
3906 @cindex options for VAX/VMS
3907 @cindex VAX/VMS options
3908 @cindex @code{-h} option, VAX/VMS
3909 @cindex @code{-+} option, VAX/VMS
3910 @cindex Vax-11 C compatibility
3911 @cindex symbols with lowercase, VAX/VMS
3912 @c FIXME! look into "I think" below, correct if needed, delete.
3913 The Vax version of the assembler accepts two options when
3914 compiled for VMS. They are @samp{-h}, and @samp{-+}. The
3915 @samp{-h} option prevents @code{@value{AS}} from modifying the
3916 symbol-table entries for symbols that contain lowercase
3917 characters (I think). The @samp{-+} option causes @code{@value{AS}} to
3918 print warning messages if the FILENAME part of the object file,
3919 or any symbol name is larger than 31 characters. The @samp{-+}
3920 option also inserts some code following the @samp{_main}
3921 symbol so that the object file is compatible with Vax-11
3925 @section VAX Floating Point
3927 @cindex VAX floating point
3928 @cindex floating point, VAX
3929 Conversion of flonums to floating point is correct, and
3930 compatible with previous assemblers. Rounding is
3931 towards zero if the remainder is exactly half the least significant bit.
3933 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
3936 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
3937 are rendered correctly. Again, rounding is towards zero in the
3940 @cindex @code{float} directive, VAX
3941 @cindex @code{double} directive, VAX
3942 The @code{.float} directive produces @code{f} format numbers.
3943 The @code{.double} directive produces @code{d} format numbers.
3945 @node VAX-directives
3946 @section Vax Machine Directives
3948 @cindex machine directives, VAX
3949 @cindex VAX machine directives
3950 The Vax version of the assembler supports four directives for
3951 generating Vax floating point constants. They are described in the
3954 @cindex wide floating point directives, VAX
3957 @cindex @code{dfloat} directive, VAX
3958 This expects zero or more flonums, separated by commas, and
3959 assembles Vax @code{d} format 64-bit floating point constants.
3962 @cindex @code{ffloat} directive, VAX
3963 This expects zero or more flonums, separated by commas, and
3964 assembles Vax @code{f} format 32-bit floating point constants.
3967 @cindex @code{gfloat} directive, VAX
3968 This expects zero or more flonums, separated by commas, and
3969 assembles Vax @code{g} format 64-bit floating point constants.
3972 @cindex @code{hfloat} directive, VAX
3973 This expects zero or more flonums, separated by commas, and
3974 assembles Vax @code{h} format 128-bit floating point constants.
3979 @section VAX Opcodes
3981 @cindex VAX opcode mnemonics
3982 @cindex opcode mnemonics, VAX
3983 @cindex mnemonics for opcodes, VAX
3984 All DEC mnemonics are supported. Beware that @code{case@dots{}}
3985 instructions have exactly 3 operands. The dispatch table that
3986 follows the @code{case@dots{}} instruction should be made with
3987 @code{.word} statements. This is compatible with all unix
3988 assemblers we know of.
3991 @section VAX Branch Improvement
3993 @cindex VAX branch improvement
3994 @cindex branch improvement, VAX
3995 @cindex pseudo-ops for branch, VAX
3996 Certain pseudo opcodes are permitted. They are for branch
3997 instructions. They expand to the shortest branch instruction that
3998 reaches the target. Generally these mnemonics are made by
3999 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
4000 This feature is included both for compatibility and to help
4001 compilers. If you do not need this feature, avoid these
4002 opcodes. Here are the mnemonics, and the code they can expand into.
4006 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
4008 @item (byte displacement)
4010 @item (word displacement)
4012 @item (long displacement)
4017 Unconditional branch.
4019 @item (byte displacement)
4021 @item (word displacement)
4023 @item (long displacement)
4027 @var{COND} may be any one of the conditional branches
4028 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
4029 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
4030 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
4031 @var{COND} may also be one of the bit tests
4032 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
4033 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
4034 @var{NOTCOND} is the opposite condition to @var{COND}.
4036 @item (byte displacement)
4037 @kbd{b@var{COND} @dots{}}
4038 @item (word displacement)
4039 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
4040 @item (long displacement)
4041 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
4044 @var{X} may be one of @code{b d f g h l w}.
4046 @item (word displacement)
4047 @kbd{@var{OPCODE} @dots{}}
4048 @item (long displacement)
4050 @var{OPCODE} @dots{}, foo ;
4057 @var{YYY} may be one of @code{lss leq}.
4059 @var{ZZZ} may be one of @code{geq gtr}.
4061 @item (byte displacement)
4062 @kbd{@var{OPCODE} @dots{}}
4063 @item (word displacement)
4065 @var{OPCODE} @dots{}, foo ;
4067 foo: brw @var{destination} ;
4070 @item (long displacement)
4072 @var{OPCODE} @dots{}, foo ;
4074 foo: jmp @var{destination} ;
4083 @item (byte displacement)
4084 @kbd{@var{OPCODE} @dots{}}
4085 @item (word displacement)
4087 @var{OPCODE} @dots{}, foo ;
4089 foo: brw @var{destination} ;
4092 @item (long displacement)
4094 @var{OPCODE} @dots{}, foo ;
4096 foo: jmp @var{destination} ;
4103 @section VAX Operands
4105 @cindex VAX operand notation
4106 @cindex operand notation, VAX
4107 @cindex immediate character, VAX
4108 @cindex VAX immediate character
4109 The immediate character is @samp{$} for Unix compatibility, not
4110 @samp{#} as DEC writes it.
4112 @cindex indirect character, VAX
4113 @cindex VAX indirect character
4114 The indirect character is @samp{*} for Unix compatibility, not
4115 @samp{@@} as DEC writes it.
4117 @cindex displacement sizing character, VAX
4118 @cindex VAX displacement sizing character
4119 The displacement sizing character is @samp{`} (an accent grave) for
4120 Unix compatibility, not @samp{^} as DEC writes it. The letter
4121 preceding @samp{`} may have either case. @samp{G} is not
4122 understood, but all other letters (@code{b i l s w}) are understood.
4124 @cindex register names, VAX
4125 @cindex VAX register names
4126 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
4127 pc}. Upper and lower case letters are equivalent.
4134 Any expression is permitted in an operand. Operands are comma
4137 @c There is some bug to do with recognizing expressions
4138 @c in operands, but I forget what it is. It is
4139 @c a syntax clash because () is used as an address mode
4140 @c and to encapsulate sub-expressions.
4143 @section Not Supported on VAX
4145 @cindex VAX bitfields not supported
4146 @cindex bitfields, not supported on VAX
4147 Vax bit fields can not be assembled with @code{@value{AS}}. Someone
4148 can add the required code if they really need it.
4154 @node AMD29K-Dependent
4155 @chapter AMD 29K Dependent Features
4158 @node Machine Dependencies
4159 @chapter AMD 29K Dependent Features
4162 @cindex AMD 29K support
4165 * AMD29K Options:: Options
4166 * AMD29K Syntax:: Syntax
4167 * AMD29K Floating Point:: Floating Point
4168 * AMD29K Directives:: AMD 29K Machine Directives
4169 * AMD29K Opcodes:: Opcodes
4172 @node AMD29K Options
4174 @cindex AMD 29K options (none)
4175 @cindex options for AMD29K (none)
4176 @code{@value{AS}} has no additional command-line options for the AMD
4182 * AMD29K-Chars:: Special Characters
4183 * AMD29K-Regs:: Register Names
4187 @subsection Special Characters
4189 @cindex line comment character, AMD 29K
4190 @cindex AMD 29K line comment character
4191 @samp{;} is the line comment character.
4193 @cindex line separator, AMD 29K
4194 @cindex AMD 29K line separator
4195 @cindex statement separator, AMD 29K
4196 @cindex AMD 29K statement separator
4197 @samp{@@} can be used instead of a newline to separate statements.
4199 @cindex identifiers, AMD 29K
4200 @cindex AMD 29K identifiers
4201 The character @samp{?} is permitted in identifiers (but may not begin
4205 @subsection Register Names
4207 @cindex AMD 29K register names
4208 @cindex register names, AMD 29K
4209 General-purpose registers are represented by predefined symbols of the
4210 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
4211 (for local registers), where @var{nnn} represents a number between
4212 @code{0} and @code{127}, written with no leading zeros. The leading
4213 letters may be in either upper or lower case; for example, @samp{gr13}
4214 and @samp{LR7} are both valid register names.
4216 You may also refer to general-purpose registers by specifying the
4217 register number as the result of an expression (prefixed with @samp{%%}
4218 to flag the expression as a register number):
4223 ---where @var{expression} must be an absolute expression evaluating to a
4224 number between @code{0} and @code{255}. The range [0, 127] refers to
4225 global registers, and the range [128, 255] to local registers.
4227 @cindex special purpose registers, AMD 29K
4228 @cindex AMD 29K special purpose registers
4229 @cindex protected registers, AMD 29K
4230 @cindex AMD 29K protected registers
4231 In addition, @code{@value{AS}} understands the following protected
4232 special-purpose register names for the AMD 29K family:
4242 These unprotected special-purpose register names are also recognized:
4250 @node AMD29K Floating Point
4251 @section Floating Point
4253 @cindex floating point, AMD 29K (@sc{ieee})
4254 @cindex AMD 29K floating point (@sc{ieee})
4255 The AMD 29K family uses @sc{ieee} floating-point numbers.
4257 @node AMD29K Directives
4258 @section AMD 29K Machine Directives
4260 @cindex machine directives, AMD 29K
4261 @cindex AMD 29K machine directives
4263 @item .block @var{size} , @var{fill}
4264 @cindex @code{block} directive, AMD 29K
4265 This directive emits @var{size} bytes, each of value @var{fill}. Both
4266 @var{size} and @var{fill} are absolute expressions. If the comma
4267 and @var{fill} are omitted, @var{fill} is assumed to be zero.
4269 In other versions of the GNU assembler, this directive is called
4275 @cindex @code{cputype} directive, AMD 29K
4276 This directive is ignored; it is accepted for compatibility with other
4280 @cindex @code{file} directive, AMD 29K
4281 This directive is ignored; it is accepted for compatibility with other
4285 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
4286 used for the directive called @code{.app-file} in the AMD 29K support.
4290 @cindex @code{line} directive, AMD 29K
4291 This directive is ignored; it is accepted for compatibility with other
4295 @c since we're ignoring .lsym...
4296 @item .reg @var{symbol}, @var{expression}
4297 @cindex @code{reg} directive, AMD 29K
4298 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
4302 @cindex @code{sect} directive, AMD 29K
4303 This directive is ignored; it is accepted for compatibility with other
4306 @item .use @var{section name}
4307 @cindex @code{use} directive, AMD 29K
4308 Establishes the section and subsection for the following code;
4309 @var{section name} may be one of @code{.text}, @code{.data},
4310 @code{.data1}, or @code{.lit}. With one of the first three @var{section
4311 name} options, @samp{.use} is equivalent to the machine directive
4312 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
4316 @node AMD29K Opcodes
4319 @cindex AMD 29K opcodes
4320 @cindex opcodes for AMD 29K
4321 @code{@value{AS}} implements all the standard AMD 29K opcodes. No
4322 additional pseudo-instructions are needed on this family.
4324 For information on the 29K machine instruction set, see @cite{Am29000
4325 User's Manual}, Advanced Micro Devices, Inc.
4330 @node Machine Dependencies
4331 @chapter Machine Dependent Features
4333 The machine instruction sets are different on each Hitachi chip family,
4334 and there are also some syntax differences among the families. This
4335 chapter describes the specific @code{@value{AS}} features for each
4339 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
4340 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
4341 * SH-Dependent:: Hitachi SH Dependent Features
4351 @node H8/300-Dependent
4352 @chapter H8/300 Dependent Features
4354 @cindex H8/300 support
4356 * H8/300 Options:: Options
4357 * H8/300 Syntax:: Syntax
4358 * H8/300 Floating Point:: Floating Point
4359 * H8/300 Directives:: H8/300 Machine Directives
4360 * H8/300 Opcodes:: Opcodes
4363 @node H8/300 Options
4366 @cindex H8/300 options (none)
4367 @cindex options, H8/300 (none)
4368 @code{@value{AS}} has no additional command-line options for the Hitachi
4374 * H8/300-Chars:: Special Characters
4375 * H8/300-Regs:: Register Names
4376 * H8/300-Addressing:: Addressing Modes
4380 @subsection Special Characters
4382 @cindex line comment character, H8/300
4383 @cindex H8/300 line comment character
4384 @samp{;} is the line comment character.
4386 @cindex line separator, H8/300
4387 @cindex statement separator, H8/300
4388 @cindex H8/300 line separator
4389 @samp{$} can be used instead of a newline to separate statements.
4390 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4393 @subsection Register Names
4395 @cindex H8/300 registers
4396 @cindex register names, H8/300
4397 You can use predefined symbols of the form @samp{r@var{n}h} and
4398 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4399 general-purpose registers. @var{n} is a digit from @samp{0} to
4400 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4403 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4404 to the H8/300 registers as 16-bit registers (you must use this form for
4407 On the H8/300H, you can also use the eight predefined symbols
4408 @samp{er@var{n}} (@samp{er0} @dots{} @samp{er7}) to refer to the 32-bit
4409 general purpose registers.
4411 The two control registers are called @code{pc} (program counter; a
4412 16-bit register, except on the H8/300H where it is 24 bits) and
4413 @code{ccr} (condition code register; an 8-bit register). @code{r7} is
4414 used as the stack pointer, and can also be called @code{sp}.
4416 @node H8/300-Addressing
4417 @subsection Addressing Modes
4419 @cindex addressing modes, H8/300
4420 @cindex H8/300 addressing modes
4421 @value{AS} understands the following addressing modes for the H8/300:
4429 @item @@(@var{d}, r@var{n})
4430 @itemx @@(@var{d}:16, r@var{n})
4431 @itemx @@(@var{d}:24, r@var{n})
4432 Register indirect: 16-bit or 24-bit displacement @var{d} from register
4433 @var{n}. (24-bit displacements are only meaningful on the H8/300H.)
4436 Register indirect with post-increment
4439 Register indirect with pre-decrement
4441 @item @code{@@}@var{aa}
4442 @itemx @code{@@}@var{aa}:8
4443 @itemx @code{@@}@var{aa}:16
4444 @itemx @code{@@}@var{aa}:24
4445 Absolute address @code{aa}. (The address size @samp{:24} only makes
4446 sense on the H8/300H.)
4452 Immediate data @var{xx}. You may specify the @samp{:8}, @samp{:16}, or
4453 @samp{:32} for clarity, if you wish; but @code{@value{AS}} neither
4454 requires this nor uses it---the data size required is taken from
4457 @item @code{@@}@code{@@}@var{aa}
4458 @itemx @code{@@}@code{@@}@var{aa}:8
4459 Memory indirect. You may specify the @samp{:8} for clarity, if you
4460 wish; but @code{@value{AS}} neither requires this nor uses it.
4463 @node H8/300 Floating Point
4464 @section Floating Point
4466 @cindex floating point, H8/300 (@sc{ieee})
4467 @cindex H8/300 floating point (@sc{ieee})
4468 The H8/300 family has no hardware floating point, but the @code{.float}
4469 directive generates @sc{ieee} floating-point numbers for compatibility
4470 with other development tools.
4473 @node H8/300 Directives
4474 @section H8/300 Machine Directives
4476 @cindex H8/300 machine directives (none)
4477 @cindex machine directives, H8/300 (none)
4478 @cindex @code{word} directive, H8/300
4479 @cindex @code{int} directive, H8/300
4480 @code{@value{AS}} has only one machine-dependent directive for the
4485 @cindex H8/300H, assembling for
4486 Recognize and emit additional instructions for the H8/300H variant, and
4487 also make @code{.int} emit 32-bit numbers rather than the usual (16-bit)
4488 for the H8/300 family.
4491 On the H8/300 family (including the H8/300H) @samp{.word} directives
4492 generate 16-bit numbers.
4494 @node H8/300 Opcodes
4497 @cindex H8/300 opcode summary
4498 @cindex opcode summary, H8/300
4499 @cindex mnemonics, H8/300
4500 @cindex instruction summary, H8/300
4501 For detailed information on the H8/300 machine instruction set, see
4502 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025). For
4503 information specific to the H8/300H, see @cite{H8/300H Series
4504 Programming Manual} (Hitachi).
4506 @code{@value{AS}} implements all the standard H8/300 opcodes. No additional
4507 pseudo-instructions are needed on this family.
4510 @c this table, due to the multi-col faking and hardcoded order, looks silly
4511 @c except in smallbook. See comments below "@set SMALL" near top of this file.
4513 The following table summarizes the H8/300 opcodes, and their arguments.
4514 Entries marked @samp{*} are opcodes used only on the H8/300H.
4517 @c Using @group seems to use the normal baselineskip, not the smallexample
4518 @c baselineskip; looks approx doublespaced.
4520 Rs @r{source register}
4521 Rd @r{destination register}
4522 abs @r{absolute address}
4523 imm @r{immediate data}
4524 disp:N @r{N-bit displacement from a register}
4525 pcrel:N @r{N-bit displacement relative to program counter}
4527 add.b #imm,rd * andc #imm,ccr
4528 add.b rs,rd band #imm,rd
4529 add.w rs,rd band #imm,@@rd
4530 * add.w #imm,rd band #imm,@@abs:8
4531 * add.l rs,rd bra pcrel:8
4532 * add.l #imm,rd * bra pcrel:16
4533 adds #imm,rd bt pcrel:8
4534 addx #imm,rd * bt pcrel:16
4535 addx rs,rd brn pcrel:8
4536 and.b #imm,rd * brn pcrel:16
4537 and.b rs,rd bf pcrel:8
4538 * and.w rs,rd * bf pcrel:16
4539 * and.w #imm,rd bhi pcrel:8
4540 * and.l #imm,rd * bhi pcrel:16
4541 * and.l rs,rd bls pcrel:8
4543 * bls pcrel:16 bld #imm,rd
4544 bcc pcrel:8 bld #imm,@@rd
4545 * bcc pcrel:16 bld #imm,@@abs:8
4546 bhs pcrel:8 bnot #imm,rd
4547 * bhs pcrel:16 bnot #imm,@@rd
4548 bcs pcrel:8 bnot #imm,@@abs:8
4549 * bcs pcrel:16 bnot rs,rd
4550 blo pcrel:8 bnot rs,@@rd
4551 * blo pcrel:16 bnot rs,@@abs:8
4552 bne pcrel:8 bor #imm,rd
4553 * bne pcrel:16 bor #imm,@@rd
4554 beq pcrel:8 bor #imm,@@abs:8
4555 * beq pcrel:16 bset #imm,rd
4556 bvc pcrel:8 bset #imm,@@rd
4557 * bvc pcrel:16 bset #imm,@@abs:8
4558 bvs pcrel:8 bset rs,rd
4559 * bvs pcrel:16 bset rs,@@rd
4560 bpl pcrel:8 bset rs,@@abs:8
4561 * bpl pcrel:16 bsr pcrel:8
4562 bmi pcrel:8 bsr pcrel:16
4563 * bmi pcrel:16 bst #imm,rd
4564 bge pcrel:8 bst #imm,@@rd
4565 * bge pcrel:16 bst #imm,@@abs:8
4566 blt pcrel:8 btst #imm,rd
4567 * blt pcrel:16 btst #imm,@@rd
4568 bgt pcrel:8 btst #imm,@@abs:8
4569 * bgt pcrel:16 btst rs,rd
4570 ble pcrel:8 btst rs,@@rd
4571 * ble pcrel:16 btst rs,@@abs:8
4572 bclr #imm,rd bxor #imm,rd
4573 bclr #imm,@@rd bxor #imm,@@rd
4574 bclr #imm,@@abs:8 bxor #imm,@@abs:8
4575 bclr rs,rd cmp.b #imm,rd
4576 bclr rs,@@rd cmp.b rs,rd
4577 bclr rs,@@abs:8 cmp.w rs,rd
4578 biand #imm,rd cmp.w rs,rd
4579 biand #imm,@@rd * cmp.w #imm,rd
4580 biand #imm,@@abs:8 * cmp.l #imm,rd
4581 bild #imm,rd * cmp.l rs,rd
4582 bild #imm,@@rd daa rs
4583 bild #imm,@@abs:8 das rs
4584 bior #imm,rd dec.b rs
4585 bior #imm,@@rd * dec.w #imm,rd
4586 bior #imm,@@abs:8 * dec.l #imm,rd
4587 bist #imm,rd divxu.b rs,rd
4588 bist #imm,@@rd * divxu.w rs,rd
4589 bist #imm,@@abs:8 * divxs.b rs,rd
4590 bixor #imm,rd * divxs.w rs,rd
4591 bixor #imm,@@rd eepmov
4592 bixor #imm,@@abs:8 * eepmovw
4594 * exts.w rd mov.w rs,@@abs:16
4595 * exts.l rd * mov.l #imm,rd
4596 * extu.w rd * mov.l rs,rd
4597 * extu.l rd * mov.l @@rs,rd
4598 inc rs * mov.l @@(disp:16,rs),rd
4599 * inc.w #imm,rd * mov.l @@(disp:24,rs),rd
4600 * inc.l #imm,rd * mov.l @@rs+,rd
4601 jmp @@rs * mov.l @@abs:16,rd
4602 jmp abs * mov.l @@abs:24,rd
4603 jmp @@@@abs:8 * mov.l rs,@@rd
4604 jsr @@rs * mov.l rs,@@(disp:16,rd)
4605 jsr abs * mov.l rs,@@(disp:24,rd)
4606 jsr @@@@abs:8 * mov.l rs,@@-rd
4607 ldc #imm,ccr * mov.l rs,@@abs:16
4608 ldc rs,ccr * mov.l rs,@@abs:24
4609 * ldc @@abs:16,ccr movfpe @@abs:16,rd
4610 * ldc @@abs:24,ccr movtpe rs,@@abs:16
4611 * ldc @@(disp:16,rs),ccr mulxu.b rs,rd
4612 * ldc @@(disp:24,rs),ccr * mulxu.w rs,rd
4613 * ldc @@rs+,ccr * mulxs.b rs,rd
4614 * ldc @@rs,ccr * mulxs.w rs,rd
4615 * mov.b @@(disp:24,rs),rd neg.b rs
4616 * mov.b rs,@@(disp:24,rd) * neg.w rs
4617 mov.b @@abs:16,rd * neg.l rs
4619 mov.b @@abs:8,rd not.b rs
4620 mov.b rs,@@abs:8 * not.w rs
4621 mov.b rs,rd * not.l rs
4622 mov.b #imm,rd or.b #imm,rd
4623 mov.b @@rs,rd or.b rs,rd
4624 mov.b @@(disp:16,rs),rd * or.w #imm,rd
4625 mov.b @@rs+,rd * or.w rs,rd
4626 mov.b @@abs:8,rd * or.l #imm,rd
4627 mov.b rs,@@rd * or.l rs,rd
4628 mov.b rs,@@(disp:16,rd) orc #imm,ccr
4629 mov.b rs,@@-rd pop.w rs
4630 mov.b rs,@@abs:8 * pop.l rs
4631 mov.w rs,@@rd push.w rs
4632 * mov.w @@(disp:24,rs),rd * push.l rs
4633 * mov.w rs,@@(disp:24,rd) rotl.b rs
4634 * mov.w @@abs:24,rd * rotl.w rs
4635 * mov.w rs,@@abs:24 * rotl.l rs
4636 mov.w rs,rd rotr.b rs
4637 mov.w #imm,rd * rotr.w rs
4638 mov.w @@rs,rd * rotr.l rs
4639 mov.w @@(disp:16,rs),rd rotxl.b rs
4640 mov.w @@rs+,rd * rotxl.w rs
4641 mov.w @@abs:16,rd * rotxl.l rs
4642 mov.w rs,@@(disp:16,rd) rotxr.b rs
4643 mov.w rs,@@-rd * rotxr.w rs
4645 * rotxr.l rs * stc ccr,@@(disp:24,rd)
4647 rte * stc ccr,@@abs:16
4648 rts * stc ccr,@@abs:24
4649 shal.b rs sub.b rs,rd
4650 * shal.w rs sub.w rs,rd
4651 * shal.l rs * sub.w #imm,rd
4652 shar.b rs * sub.l rs,rd
4653 * shar.w rs * sub.l #imm,rd
4654 * shar.l rs subs #imm,rd
4655 shll.b rs subx #imm,rd
4656 * shll.w rs subx rs,rd
4657 * shll.l rs * trapa #imm
4658 shlr.b rs xor #imm,rd
4659 * shlr.w rs xor rs,rd
4660 * shlr.l rs * xor.w #imm,rd
4662 stc ccr,rd * xor.l #imm,rd
4663 * stc ccr,@@rs * xor.l rs,rd
4664 * stc ccr,@@(disp:16,rd) xorc #imm,ccr
4668 @cindex size suffixes, H8/300
4669 @cindex H8/300 size suffixes
4670 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4671 @code{sub}) are defined with variants using the suffixes @samp{.b},
4672 @samp{.w}, and @samp{.l} to specify the size of a memory operand.
4673 @code{@value{AS}} supports these suffixes, but does not require them;
4674 since one of the operands is always a register, @code{@value{AS}} can
4675 deduce the correct size.
4677 For example, since @code{r0} refers to a 16-bit register,
4680 @exdent is equivalent to
4684 If you use the size suffixes, @code{@value{AS}} issues a warning when
4685 the suffix and the register size do not match.
4690 @node H8/500-Dependent
4691 @chapter H8/500 Dependent Features
4693 @cindex H8/500 support
4695 * H8/500 Options:: Options
4696 * H8/500 Syntax:: Syntax
4697 * H8/500 Floating Point:: Floating Point
4698 * H8/500 Directives:: H8/500 Machine Directives
4699 * H8/500 Opcodes:: Opcodes
4702 @node H8/500 Options
4705 @cindex H8/500 options (none)
4706 @cindex options, H8/500 (none)
4707 @code{@value{AS}} has no additional command-line options for the Hitachi
4714 * H8/500-Chars:: Special Characters
4715 * H8/500-Regs:: Register Names
4716 * H8/500-Addressing:: Addressing Modes
4720 @subsection Special Characters
4722 @cindex line comment character, H8/500
4723 @cindex H8/500 line comment character
4724 @samp{!} is the line comment character.
4726 @cindex line separator, H8/500
4727 @cindex statement separator, H8/500
4728 @cindex H8/500 line separator
4729 @samp{;} can be used instead of a newline to separate statements.
4731 @cindex symbol names, @samp{$} in
4732 @cindex @code{$} in symbol names
4733 Since @samp{$} has no special meaning, you may use it in symbol names.
4736 @subsection Register Names
4738 @cindex H8/500 registers
4739 @cindex registers, H8/500
4740 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
4741 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, and @samp{r7} to refer to
4742 the H8/500 registers.
4744 The H8/500 also has these control registers:
4766 condition code register
4769 All registers are 16 bits long. To represent 32 bit numbers, use two
4770 adjacent registers; for distant memory addresses, use one of the segment
4771 pointers (@code{cp} for the program counter; @code{dp} for
4772 @code{r0}--@code{r3}; @code{ep} for @code{r4} and @code{r5}; and
4773 @code{tp} for @code{r6} and @code{r7}.
4775 @node H8/500-Addressing
4776 @subsection Addressing Modes
4778 @cindex addressing modes, H8/500
4779 @cindex H8/500 addressing modes
4780 @value{AS} understands the following addressing modes for the H8/500:
4788 @item @@(d:8, R@var{n})
4789 Register indirect with 8 bit signed displacement
4791 @item @@(d:16, R@var{n})
4792 Register indirect with 16 bit signed displacement
4795 Register indirect with pre-decrement
4798 Register indirect with post-increment
4801 8 bit absolute address
4804 16 bit absolute address
4813 @node H8/500 Floating Point
4814 @section Floating Point
4816 @cindex floating point, H8/500 (@sc{ieee})
4817 @cindex H8/500 floating point (@sc{ieee})
4818 The H8/500 family uses @sc{ieee} floating-point numbers.
4820 @node H8/500 Directives
4821 @section H8/500 Machine Directives
4823 @cindex H8/500 machine directives (none)
4824 @cindex machine directives, H8/500 (none)
4825 @cindex @code{word} directive, H8/500
4826 @cindex @code{int} directive, H8/500
4827 @code{@value{AS}} has no machine-dependent directives for the H8/500.
4828 However, on this platform the @samp{.int} and @samp{.word} directives
4829 generate 16-bit numbers.
4831 @node H8/500 Opcodes
4834 @cindex H8/500 opcode summary
4835 @cindex opcode summary, H8/500
4836 @cindex mnemonics, H8/500
4837 @cindex instruction summary, H8/500
4838 For detailed information on the H8/500 machine instruction set, see
4839 @cite{H8/500 Series Programming Manual} (Hitachi M21T001).
4841 @code{@value{AS}} implements all the standard H8/500 opcodes. No additional
4842 pseudo-instructions are needed on this family.
4845 @c this table, due to the multi-col faking and hardcoded order, looks silly
4846 @c except in smallbook. See comments below "@set SMALL" near top of this file.
4848 The following table summarizes H8/500 opcodes and their operands:
4850 @c Use @group if it ever works, instead of @page
4854 abs8 @r{8-bit absolute address}
4855 abs16 @r{16-bit absolute address}
4856 abs24 @r{24-bit absolute address}
4857 crb @r{@code{ccr}, @code{br}, @code{ep}, @code{dp}, @code{tp}, @code{dp}}
4858 disp8 @r{8-bit displacement}
4859 ea @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4860 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16},}
4861 @r{@code{#xx:8}, @code{#xx:16}}
4862 ea_mem @r{@code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4863 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4864 ea_noimm @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4865 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4867 imm4 @r{4-bit immediate data}
4868 imm8 @r{8-bit immediate data}
4869 imm16 @r{16-bit immediate data}
4870 pcrel8 @r{8-bit offset from program counter}
4871 pcrel16 @r{16-bit offset from program counter}
4872 qim @r{@code{-2}, @code{-1}, @code{1}, @code{2}}
4874 rs @r{a register distinct from rd}
4875 rlist @r{comma-separated list of registers in parentheses;}
4876 @r{register ranges @code{rd-rs} are allowed}
4877 sp @r{stack pointer (@code{r7})}
4878 sr @r{status register}
4879 sz @r{size; @samp{.b} or @samp{.w}. If omitted, default @samp{.w}}
4881 ldc[.b] ea,crb bcc[.w] pcrel16
4882 ldc[.w] ea,sr bcc[.b] pcrel8
4883 add[:q] sz qim,ea_noimm bhs[.w] pcrel16
4884 add[:g] sz ea,rd bhs[.b] pcrel8
4885 adds sz ea,rd bcs[.w] pcrel16
4886 addx sz ea,rd bcs[.b] pcrel8
4887 and sz ea,rd blo[.w] pcrel16
4888 andc[.b] imm8,crb blo[.b] pcrel8
4889 andc[.w] imm16,sr bne[.w] pcrel16
4891 bra[.w] pcrel16 beq[.w] pcrel16
4892 bra[.b] pcrel8 beq[.b] pcrel8
4893 bt[.w] pcrel16 bvc[.w] pcrel16
4894 bt[.b] pcrel8 bvc[.b] pcrel8
4895 brn[.w] pcrel16 bvs[.w] pcrel16
4896 brn[.b] pcrel8 bvs[.b] pcrel8
4897 bf[.w] pcrel16 bpl[.w] pcrel16
4898 bf[.b] pcrel8 bpl[.b] pcrel8
4899 bhi[.w] pcrel16 bmi[.w] pcrel16
4900 bhi[.b] pcrel8 bmi[.b] pcrel8
4901 bls[.w] pcrel16 bge[.w] pcrel16
4902 bls[.b] pcrel8 bge[.b] pcrel8
4904 blt[.w] pcrel16 mov[:g][.b] imm8,ea_mem
4905 blt[.b] pcrel8 mov[:g][.w] imm16,ea_mem
4906 bgt[.w] pcrel16 movfpe[.b] ea,rd
4907 bgt[.b] pcrel8 movtpe[.b] rs,ea_noimm
4908 ble[.w] pcrel16 mulxu sz ea,rd
4909 ble[.b] pcrel8 neg sz ea
4910 bclr sz imm4,ea_noimm nop
4911 bclr sz rs,ea_noimm not sz ea
4912 bnot sz imm4,ea_noimm or sz ea,rd
4913 bnot sz rs,ea_noimm orc[.b] imm8,crb
4914 bset sz imm4,ea_noimm orc[.w] imm16,sr
4915 bset sz rs,ea_noimm pjmp abs24
4916 bsr[.b] pcrel8 pjmp @@rd
4917 bsr[.w] pcrel16 pjsr abs24
4918 btst sz imm4,ea_noimm pjsr @@rd
4919 btst sz rs,ea_noimm prtd imm8
4920 clr sz ea prtd imm16
4921 cmp[:e][.b] imm8,rd prts
4922 cmp[:i][.w] imm16,rd rotl sz ea
4923 cmp[:g].b imm8,ea_noimm rotr sz ea
4924 cmp[:g][.w] imm16,ea_noimm rotxl sz ea
4925 Cmp[:g] sz ea,rd rotxr sz ea
4927 divxu sz ea,rd rtd imm16
4929 exts[.b] rd scb/f rs,pcrel8
4930 extu[.b] rd scb/ne rs,pcrel8
4931 jmp @@rd scb/eq rs,pcrel8
4932 jmp @@(imm8,rd) shal sz ea
4933 jmp @@(imm16,rd) shar sz ea
4934 jmp abs16 shll sz ea
4936 jsr @@(imm8,rd) sleep
4937 jsr @@(imm16,rd) stc[.b] crb,ea_noimm
4938 jsr abs16 stc[.w] sr,ea_noimm
4939 ldm @@sp+,(rlist) stm (rlist),@@-sp
4940 link fp,imm8 sub sz ea,rd
4941 link fp,imm16 subs sz ea,rd
4942 mov[:e][.b] imm8,rd subx sz ea,rd
4943 mov[:i][.w] imm16,rd swap[.b] rd
4944 mov[:l][.w] abs8,rd tas[.b] ea
4945 mov[:l].b abs8,rd trapa imm4
4946 mov[:s][.w] rs,abs8 trap/vs
4947 mov[:s].b rs,abs8 tst sz ea
4948 mov[:f][.w] @@(disp8,fp),rd unlk fp
4949 mov[:f][.w] rs,@@(disp8,fp) xch[.w] rs,rd
4950 mov[:f].b @@(disp8,fp),rd xor sz ea,rd
4951 mov[:f].b rs,@@(disp8,fp) xorc.b imm8,crb
4952 mov[:g] sz rs,ea_mem xorc.w imm16,sr
4960 @node HPPA-Dependent
4961 @chapter HPPA Dependent Features
4965 * HPPA Notes:: Notes
4966 * HPPA Options:: Options
4967 * HPPA Syntax:: Syntax
4968 * HPPA Floating Point:: Floating Point
4969 * HPPA Directives:: HPPA Machine Directives
4970 * HPPA Opcodes:: Opcodes
4975 As a back end for GNU CC @code{@value{AS}} has been throughly tested and should
4976 work extremely well. We have tested it only minimally on hand written assembly
4977 code and no one has tested it much on the assembly output from the HP
4980 The format of the debugging sections has changed since the original
4981 @code{@value{AS}} port (version 1.3X) was released; therefore,
4982 you must rebuild all HPPA objects and libraries with the new
4983 assembler so that you can debug the final executable.
4985 The HPPA @code{@value{AS}} port generates a small subset of the relocations
4986 available in the SOM and ELF object file formats. Additional relocation
4987 support will be added as it becomes necessary.
4991 @code{@value{AS}} has no machine-dependent command-line options for the HPPA.
4996 The assembler syntax closely follows the HPPA instruction set
4997 reference manual; assembler directives and general syntax closely follow the
4998 HPPA assembly language reference manual, with a few noteworthy differences.
5000 First, a colon may immediately follow a label definition. This is
5001 simply for compatibility with how most assembly language programmers
5004 Some obscure expression parsing problems may affect hand written code which
5005 uses the @code{spop} instructions, or code which makes significant
5006 use of the @code{!} line separator.
5008 @code{@value{AS}} is much less forgiving about missing arguments and other
5009 similar oversights than the HP assembler. @code{@value{AS}} notifies you
5010 of missing arguments as syntax errors; this is regarded as a feature, not a
5013 Finally, @code{@value{AS}} allows you to use an external symbol without
5014 explicitly importing the symbol. @emph{Warning:} in the future this will be
5015 an error for HPPA targets.
5017 Special characters for HPPA targets include:
5019 @samp{;} is the line comment character.
5021 @samp{!} can be used instead of a newline to separate statements.
5023 Since @samp{$} has no special meaning, you may use it in symbol names.
5025 @node HPPA Floating Point
5026 @section Floating Point
5027 @cindex floating point, HPPA (@sc{ieee})
5028 @cindex HPPA floating point (@sc{ieee})
5029 The HPPA family uses @sc{ieee} floating-point numbers.
5031 @node HPPA Directives
5032 @section HPPA Assembler Directives
5034 @code{@value{AS}} for the HPPA supports many additional directives for
5035 compatibility with the native assembler. This section describes them only
5036 briefly. For detailed information on HPPA-specific assembler directives, see
5037 @cite{HP9000 Series 800 Assembly Language Reference Manual} (HP 92432-90001).
5039 @cindex HPPA directives not supported
5040 @code{@value{AS}} does @emph{not} support the following assembler directives
5041 described in the HP manual:
5050 @cindex @code{.param} on HPPA
5051 Beyond those implemented for compatibility, @code{@value{AS}} supports one
5052 additional assembler directive for the HPPA: @code{.param}. It conveys
5053 register argument locations for static functions. Its syntax closely follows
5054 the @code{.export} directive.
5056 @cindex HPPA-only directives
5057 These are the additional directives in @code{@value{AS}} for the HPPA:
5060 @item .block @var{n}
5061 @itemx .blockz @var{n}
5062 Reserve @var{n} bytes of storage, and initialize them to zero.
5065 Mark the beginning of a procedure call. Only the special case with @emph{no
5066 arguments} is allowed.
5068 @item .callinfo [ @var{param}=@var{value}, @dots{} ] [ @var{flag}, @dots{} ]
5069 Specify a number of parameters and flags that define the environment for a
5072 @var{param} may be any of @samp{frame} (frame size), @samp{entry_gr} (end of
5073 general register range), @samp{entry_fr} (end of float register range),
5074 @samp{entry_sr} (end of space register range).
5076 The values for @var{flag} are @samp{calls} or @samp{caller} (proc has
5077 subroutines), @samp{no_calls} (proc does not call subroutines), @samp{save_rp}
5078 (preserve return pointer), @samp{save_sp} (proc preserves stack pointer),
5079 @samp{no_unwind} (do not unwind this proc), @samp{hpux_int} (proc is interrupt
5083 Assemble into the standard section called @samp{$TEXT$}, subsection
5087 @item .copyright "@var{string}"
5088 In the SOM object format, insert @var{string} into the object code, marked as a
5093 @item .copyright "@var{string}"
5094 In the ELF object format, insert @var{string} into the object code, marked as a
5099 Not yet supported; the assembler rejects programs containing this directive.
5102 Mark the beginning of a procedure.
5105 Mark the end of a procedure.
5107 @item .export @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5108 Make a procedure @var{name} available to callers. @var{typ}, if present, must
5109 be one of @samp{absolute}, @samp{code} (ELF only, not SOM), @samp{data},
5110 @samp{entry}, @samp{data}, @samp{entry}, @samp{millicode}, @samp{plabel},
5111 @samp{pri_prog}, or @samp{sec_prog}.
5113 @var{param}, if present, provides either relocation information for the
5114 procedure arguments and result, or a privilege level. @var{param} may be
5115 @samp{argw@var{n}} (where @var{n} ranges from @code{0} to @code{3}, and
5116 indicates one of four one-word arguments); @samp{rtnval} (the procedure's
5117 result); or @samp{priv_lev} (privilege level). For arguments or the result,
5118 @var{r} specifies how to relocate, and must be one of @samp{no} (not
5119 relocatable), @samp{gr} (argument is in general register), @samp{fr} (in
5120 floating point register), or @samp{fu} (upper half of float register).
5121 For @samp{priv_lev}, @var{r} is an integer.
5124 Define a two-byte integer constant @var{n}; synonym for the portable
5125 @code{@value{AS}} directive @code{.short}.
5127 @item .import @var{name} [ ,@var{typ} ]
5128 Converse of @code{.export}; make a procedure available to call. The arguments
5129 use the same conventions as the first two arguments for @code{.export}.
5131 @item .label @var{name}
5132 Define @var{name} as a label for the current assembly location.
5135 Not yet supported; the assembler rejects programs containing this directive.
5137 @item .origin @var{lc}
5138 Advance location counter to @var{lc}. Synonym for the @code{@value{as}}
5139 portable directive @code{.org}.
5141 @item .param @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5142 @c Not in HP manual; GNU HPPA extension
5143 Similar to @code{.export}, but used for static procedures.
5146 Use preceding the first statement of a procedure.
5149 Use following the last statement of a procedure.
5151 @item @var{label} .reg @var{expr}
5152 @c ?? Not in HP manual (Jan 1988 vn)
5153 Synonym for @code{.equ}; define @var{label} with the absolute expression
5154 @var{expr} as its value.
5156 @item .space @var{secname} [ ,@var{params} ]
5157 Switch to section @var{secname}, creating a new section by that name if
5158 necessary. You may only use @var{params} when creating a new section, not
5159 when switching to an existing one. @var{secname} may identify a section by
5160 number rather than by name.
5162 If specified, the list @var{params} declares attributes of the section,
5163 identified by keywords. The keywords recognized are @samp{spnum=@var{exp}}
5164 (identify this section by the number @var{exp}, an absolute expression),
5165 @samp{sort=@var{exp}} (order sections according to this sort key when linking;
5166 @var{exp} is an absolute expression), @samp{unloadable} (section contains no
5167 loadable data), @samp{notdefined} (this section defined elsewhere), and
5168 @samp{private} (data in this section not available to other programs).
5170 @item .spnum @var{secnam}
5171 @c ?? Not in HP manual (Jan 1988)
5172 Allocate four bytes of storage, and initialize them with the section number of
5173 the section named @var{secnam}. (You can define the section number with the
5174 HPPA @code{.space} directive.)
5176 @item .string "@var{str}"
5177 @cindex @code{string} directive on HPPA
5178 Copy the characters in the string @var{str} to the object file.
5179 @xref{Strings,,Strings}, for information on escape sequences you can use in
5180 @code{@value{AS}} strings.
5182 @emph{Warning!} The HPPA version of @code{.string} differs from the
5183 usual @code{@value{AS}} definition: it does @emph{not} write a zero byte
5184 after copying @var{str}.
5186 @item .stringz "@var{str}"
5187 Like @code{.string}, but appends a zero byte after copying @var{str} to object
5190 @item .subspa @var{name} [ ,@var{params} ]
5191 Similar to @code{.space}, but selects a subsection @var{name} within the
5192 current section. You may only specify @var{params} when you create a
5193 subsection (in the first instance of @code{.subspa} for this @var{name}).
5195 If specified, the list @var{params} declares attributes of the subsection,
5196 identified by keywords. The keywords recognized are @samp{quad=@var{expr}}
5197 (``quadrant'' for this subsection), @samp{align=@var{expr}} (alignment for
5198 beginning of this subsection; a power of two), @samp{access=@var{expr}} (value
5199 for ``access rights'' field), @samp{sort=@var{expr}} (sorting order for this
5200 subspace in link), @samp{code_only} (subsection contains only code),
5201 @samp{unloadable} (subsection cannot be loaded into memory), @samp{common}
5202 (subsection is common block), @samp{dup_comm} (initialized data may have
5203 duplicate names), or @samp{zero} (subsection is all zeros, do not write in
5206 @item .version "@var{str}"
5207 Write @var{str} as version identifier in object code.
5212 For detailed information on the HPPA machine instruction set, see
5213 @cite{PA-RISC Architecture and Instruction Set Reference Manual}
5220 @chapter Hitachi SH Dependent Features
5224 * SH Options:: Options
5225 * SH Syntax:: Syntax
5226 * SH Floating Point:: Floating Point
5227 * SH Directives:: SH Machine Directives
5228 * SH Opcodes:: Opcodes
5234 @cindex SH options (none)
5235 @cindex options, SH (none)
5236 @code{@value{AS}} has no additional command-line options for the Hitachi
5243 * SH-Chars:: Special Characters
5244 * SH-Regs:: Register Names
5245 * SH-Addressing:: Addressing Modes
5249 @subsection Special Characters
5251 @cindex line comment character, SH
5252 @cindex SH line comment character
5253 @samp{!} is the line comment character.
5255 @cindex line separator, SH
5256 @cindex statement separator, SH
5257 @cindex SH line separator
5258 You can use @samp{;} instead of a newline to separate statements.
5260 @cindex symbol names, @samp{$} in
5261 @cindex @code{$} in symbol names
5262 Since @samp{$} has no special meaning, you may use it in symbol names.
5265 @subsection Register Names
5267 @cindex SH registers
5268 @cindex registers, SH
5269 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
5270 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, @samp{r7}, @samp{r8},
5271 @samp{r9}, @samp{r10}, @samp{r11}, @samp{r12}, @samp{r13}, @samp{r14},
5272 and @samp{r15} to refer to the SH registers.
5274 The SH also has these control registers:
5278 procedure register (holds return address)
5285 high and low multiply accumulator registers
5291 global base register
5294 vector base register (for interrupt vectors)
5298 @subsection Addressing Modes
5300 @cindex addressing modes, SH
5301 @cindex SH addressing modes
5302 @code{@value{AS}} understands the following addressing modes for the SH.
5303 @code{R@var{n}} in the following refers to any of the numbered
5304 registers, but @emph{not} the control registers.
5314 Register indirect with pre-decrement
5317 Register indirect with post-increment
5319 @item @@(@var{disp}, R@var{n})
5320 Register indirect with displacement
5322 @item @@(R0, R@var{n})
5325 @item @@(@var{disp}, GBR)
5332 @itemx @@(@var{disp}, PC)
5333 PC relative address (for branch or for addressing memory). The
5334 @code{@value{AS}} implementation allows you to use the simpler form
5335 @var{addr} anywhere a PC relative address is called for; the alternate
5336 form is supported for compatibility with other assemblers.
5342 @node SH Floating Point
5343 @section Floating Point
5345 @cindex floating point, SH (@sc{ieee})
5346 @cindex SH floating point (@sc{ieee})
5347 The SH family uses @sc{ieee} floating-point numbers.
5350 @section SH Machine Directives
5352 @cindex SH machine directives (none)
5353 @cindex machine directives, SH (none)
5354 @cindex @code{word} directive, SH
5355 @cindex @code{int} directive, SH
5356 @code{@value{AS}} has no machine-dependent directives for the SH.
5361 @cindex SH opcode summary
5362 @cindex opcode summary, SH
5363 @cindex mnemonics, SH
5364 @cindex instruction summary, SH
5365 For detailed information on the SH machine instruction set, see
5366 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
5368 @code{@value{AS}} implements all the standard SH opcodes. No additional
5369 pseudo-instructions are needed on this family. Note, however, that
5370 because @code{@value{AS}} supports a simpler form of PC-relative
5371 addressing, you may simply write (for example)
5378 where other assemblers might require an explicit displacement to
5379 @code{bar} from the program counter:
5382 mov.l @@(@var{disp}, PC)
5386 @c this table, due to the multi-col faking and hardcoded order, looks silly
5387 @c except in smallbook. See comments below "@set SMALL" near top of this file.
5389 Here is a summary of SH opcodes:
5394 Rn @r{a numbered register}
5395 Rm @r{another numbered register}
5396 #imm @r{immediate data}
5397 disp @r{displacement}
5398 disp8 @r{8-bit displacement}
5399 disp12 @r{12-bit displacement}
5401 add #imm,Rn lds.l @@Rn+,PR
5402 add Rm,Rn mac.w @@Rm+,@@Rn+
5403 addc Rm,Rn mov #imm,Rn
5404 addv Rm,Rn mov Rm,Rn
5405 and #imm,R0 mov.b Rm,@@(R0,Rn)
5406 and Rm,Rn mov.b Rm,@@-Rn
5407 and.b #imm,@@(R0,GBR) mov.b Rm,@@Rn
5408 bf disp8 mov.b @@(disp,Rm),R0
5409 bra disp12 mov.b @@(disp,GBR),R0
5410 bsr disp12 mov.b @@(R0,Rm),Rn
5411 bt disp8 mov.b @@Rm+,Rn
5412 clrmac mov.b @@Rm,Rn
5413 clrt mov.b R0,@@(disp,Rm)
5414 cmp/eq #imm,R0 mov.b R0,@@(disp,GBR)
5415 cmp/eq Rm,Rn mov.l Rm,@@(disp,Rn)
5416 cmp/ge Rm,Rn mov.l Rm,@@(R0,Rn)
5417 cmp/gt Rm,Rn mov.l Rm,@@-Rn
5418 cmp/hi Rm,Rn mov.l Rm,@@Rn
5419 cmp/hs Rm,Rn mov.l @@(disp,Rn),Rm
5420 cmp/pl Rn mov.l @@(disp,GBR),R0
5421 cmp/pz Rn mov.l @@(disp,PC),Rn
5422 cmp/str Rm,Rn mov.l @@(R0,Rm),Rn
5423 div0s Rm,Rn mov.l @@Rm+,Rn
5425 div1 Rm,Rn mov.l R0,@@(disp,GBR)
5426 exts.b Rm,Rn mov.w Rm,@@(R0,Rn)
5427 exts.w Rm,Rn mov.w Rm,@@-Rn
5428 extu.b Rm,Rn mov.w Rm,@@Rn
5429 extu.w Rm,Rn mov.w @@(disp,Rm),R0
5430 jmp @@Rn mov.w @@(disp,GBR),R0
5431 jsr @@Rn mov.w @@(disp,PC),Rn
5432 ldc Rn,GBR mov.w @@(R0,Rm),Rn
5433 ldc Rn,SR mov.w @@Rm+,Rn
5434 ldc Rn,VBR mov.w @@Rm,Rn
5435 ldc.l @@Rn+,GBR mov.w R0,@@(disp,Rm)
5436 ldc.l @@Rn+,SR mov.w R0,@@(disp,GBR)
5437 ldc.l @@Rn+,VBR mova @@(disp,PC),R0
5439 lds Rn,MACL muls Rm,Rn
5440 lds Rn,PR mulu Rm,Rn
5441 lds.l @@Rn+,MACH neg Rm,Rn
5442 lds.l @@Rn+,MACL negc Rm,Rn
5445 not Rm,Rn stc.l GBR,@@-Rn
5446 or #imm,R0 stc.l SR,@@-Rn
5447 or Rm,Rn stc.l VBR,@@-Rn
5448 or.b #imm,@@(R0,GBR) sts MACH,Rn
5449 rotcl Rn sts MACL,Rn
5451 rotl Rn sts.l MACH,@@-Rn
5452 rotr Rn sts.l MACL,@@-Rn
5457 shar Rn swap.b Rm,Rn
5458 shll Rn swap.w Rm,Rn
5459 shll16 Rn tas.b @@Rn
5461 shll8 Rn tst #imm,R0
5463 shlr16 Rn tst.b #imm,@@(R0,GBR)
5464 shlr2 Rn xor #imm,R0
5466 sleep xor.b #imm,@@(R0,GBR)
5467 stc GBR,Rn xtrct Rm,Rn
5482 @node i960-Dependent
5483 @chapter Intel 80960 Dependent Features
5486 @node Machine Dependencies
5487 @chapter Intel 80960 Dependent Features
5490 @cindex i960 support
5492 * Options-i960:: i960 Command-line Options
5493 * Floating Point-i960:: Floating Point
5494 * Directives-i960:: i960 Machine Directives
5495 * Opcodes for i960:: i960 Opcodes
5498 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
5499 @c long as they're not turned on for other machines than 960.
5503 @section i960 Command-line Options
5505 @cindex i960 options
5506 @cindex options, i960
5509 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
5510 @cindex i960 architecture options
5511 @cindex architecture options, i960
5512 @cindex @code{-A} options, i960
5513 Select the 80960 architecture. Instructions or features not supported
5514 by the selected architecture cause fatal errors.
5516 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
5517 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
5519 If none of these options is specified, @code{@value{AS}} generates code for any
5520 instruction or feature that is supported by @emph{some} version of the
5521 960 (even if this means mixing architectures!). In principle,
5522 @code{@value{AS}} attempts to deduce the minimal sufficient processor
5523 type if none is specified; depending on the object code format, the
5524 processor type may be recorded in the object file. If it is critical
5525 that the @code{@value{AS}} output match a specific architecture, specify that
5526 architecture explicitly.
5529 @cindex @code{-b} option, i960
5530 @cindex branch recording, i960
5531 @cindex i960 branch recording
5532 Add code to collect information about conditional branches taken, for
5533 later optimization using branch prediction bits. (The conditional branch
5534 instructions have branch prediction bits in the CA, CB, and CC
5535 architectures.) If @var{BR} represents a conditional branch instruction,
5536 the following represents the code generated by the assembler when
5537 @samp{-b} is specified:
5540 call @var{increment routine}
5541 .word 0 # pre-counter
5543 call @var{increment routine}
5544 .word 0 # post-counter
5547 The counter following a branch records the number of times that branch
5548 was @emph{not} taken; the differenc between the two counters is the
5549 number of times the branch @emph{was} taken.
5551 @cindex @code{gbr960}, i960 postprocessor
5552 @cindex branch statistics table, i960
5553 A table of every such @code{Label} is also generated, so that the
5554 external postprocessor @code{gbr960} (supplied by Intel) can locate all
5555 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
5556 this is a local symbol to permit collecting statistics for many separate
5557 object files. The table is word aligned, and begins with a two-word
5558 header. The first word, initialized to 0, is used in maintaining linked
5559 lists of branch tables. The second word is a count of the number of
5560 entries in the table, which follow immediately: each is a word, pointing
5561 to one of the labels illustrated above.
5565 @c END TEXI2ROFF-KILL
5567 +------------+------------+------------+ ... +------------+
5569 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
5571 +------------+------------+------------+ ... +------------+
5573 __BRANCH_TABLE__ layout
5579 \line{\leftskip=0pt\hskip\tableindent
5580 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
5581 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
5582 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
5584 @c END TEXI2ROFF-KILL
5586 The first word of the header is used to locate multiple branch tables,
5587 since each object file may contain one. Normally the links are
5588 maintained with a call to an initialization routine, placed at the
5589 beginning of each function in the file. The GNU C compiler
5590 generates these calls automatically when you give it a @samp{-b} option.
5591 For further details, see the documentation of @samp{gbr960}.
5594 @cindex @code{-norelax} option, i960
5595 Normally, Compare-and-Branch instructions with targets that require
5596 displacements greater than 13 bits (or that have external targets) are
5597 replaced with the corresponding compare (or @samp{chkbit}) and branch
5598 instructions. You can use the @samp{-norelax} option to specify that
5599 @code{@value{AS}} should generate errors instead, if the target displacement
5600 is larger than 13 bits.
5602 This option does not affect the Compare-and-Jump instructions; the code
5603 emitted for them is @emph{always} adjusted when necessary (depending on
5604 displacement size), regardless of whether you use @samp{-norelax}.
5607 @node Floating Point-i960
5608 @section Floating Point
5610 @cindex floating point, i960 (@sc{ieee})
5611 @cindex i960 floating point (@sc{ieee})
5612 @code{@value{AS}} generates @sc{ieee} floating-point numbers for the directives
5613 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
5615 @node Directives-i960
5616 @section i960 Machine Directives
5618 @cindex machine directives, i960
5619 @cindex i960 machine directives
5622 @cindex @code{bss} directive, i960
5623 @item .bss @var{symbol}, @var{length}, @var{align}
5624 Reserve @var{length} bytes in the bss section for a local @var{symbol},
5625 aligned to the power of two specified by @var{align}. @var{length} and
5626 @var{align} must be positive absolute expressions. This directive
5627 differs from @samp{.lcomm} only in that it permits you to specify
5628 an alignment. @xref{Lcomm,,@code{.lcomm}}.
5632 @item .extended @var{flonums}
5633 @cindex @code{extended} directive, i960
5634 @code{.extended} expects zero or more flonums, separated by commas; for
5635 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
5636 floating-point number.
5638 @item .leafproc @var{call-lab}, @var{bal-lab}
5639 @cindex @code{leafproc} directive, i960
5640 You can use the @samp{.leafproc} directive in conjunction with the
5641 optimized @code{callj} instruction to enable faster calls of leaf
5642 procedures. If a procedure is known to call no other procedures, you
5643 may define an entry point that skips procedure prolog code (and that does
5644 not depend on system-supplied saved context), and declare it as the
5645 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
5646 entry point that goes through the normal prolog, you can specify that
5647 entry point as @var{call-lab}.
5649 A @samp{.leafproc} declaration is meant for use in conjunction with the
5650 optimized call instruction @samp{callj}; the directive records the data
5651 needed later to choose between converting the @samp{callj} into a
5652 @code{bal} or a @code{call}.
5654 @var{call-lab} is optional; if only one argument is present, or if the
5655 two arguments are identical, the single argument is assumed to be the
5656 @code{bal} entry point.
5658 @item .sysproc @var{name}, @var{index}
5659 @cindex @code{sysproc} directive, i960
5660 The @samp{.sysproc} directive defines a name for a system procedure.
5661 After you define it using @samp{.sysproc}, you can use @var{name} to
5662 refer to the system procedure identified by @var{index} when calling
5663 procedures with the optimized call instruction @samp{callj}.
5665 Both arguments are required; @var{index} must be between 0 and 31
5669 @node Opcodes for i960
5670 @section i960 Opcodes
5672 @cindex opcodes, i960
5673 @cindex i960 opcodes
5674 All Intel 960 machine instructions are supported;
5675 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
5676 selecting the instruction subset for a particular 960
5677 architecture.@refill
5679 Some opcodes are processed beyond simply emitting a single corresponding
5680 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
5681 instructions with target displacements larger than 13 bits.
5684 * callj-i960:: @code{callj}
5685 * Compare-and-branch-i960:: Compare-and-Branch
5689 @subsection @code{callj}
5691 @cindex @code{callj}, i960 pseudo-opcode
5692 @cindex i960 @code{callj} pseudo-opcode
5693 You can write @code{callj} to have the assembler or the linker determine
5694 the most appropriate form of subroutine call: @samp{call},
5695 @samp{bal}, or @samp{calls}. If the assembly source contains
5696 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
5697 defining the operand---then @code{@value{AS}} translates the
5698 @code{callj}; if not, it simply emits the @code{callj}, leaving it
5699 for the linker to resolve.
5701 @node Compare-and-branch-i960
5702 @subsection Compare-and-Branch
5704 @cindex i960 compare/branch instructions
5705 @cindex compare/branch instructions, i960
5706 The 960 architectures provide combined Compare-and-Branch instructions
5707 that permit you to store the branch target in the lower 13 bits of the
5708 instruction word itself. However, if you specify a branch target far
5709 enough away that its address won't fit in 13 bits, the assembler can
5710 either issue an error, or convert your Compare-and-Branch instruction
5711 into separate instructions to do the compare and the branch.
5713 @cindex compare and jump expansions, i960
5714 @cindex i960 compare and jump expansions
5715 Whether @code{@value{AS}} gives an error or expands the instruction depends
5716 on two choices you can make: whether you use the @samp{-norelax} option,
5717 and whether you use a ``Compare and Branch'' instruction or a ``Compare
5718 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
5719 expanded if necessary; the ``Branch'' instructions are expanded when
5720 necessary @emph{unless} you specify @code{-norelax}---in which case
5721 @code{@value{AS}} gives an error instead.
5723 These are the Compare-and-Branch instructions, their ``Jump'' variants,
5724 and the instruction pairs they may expand into:
5728 @c END TEXI2ROFF-KILL
5731 Branch Jump Expanded to
5732 ------ ------ ------------
5735 cmpibe cmpije cmpi; be
5736 cmpibg cmpijg cmpi; bg
5737 cmpibge cmpijge cmpi; bge
5738 cmpibl cmpijl cmpi; bl
5739 cmpible cmpijle cmpi; ble
5740 cmpibno cmpijno cmpi; bno
5741 cmpibne cmpijne cmpi; bne
5742 cmpibo cmpijo cmpi; bo
5743 cmpobe cmpoje cmpo; be
5744 cmpobg cmpojg cmpo; bg
5745 cmpobge cmpojge cmpo; bge
5746 cmpobl cmpojl cmpo; bl
5747 cmpoble cmpojle cmpo; ble
5748 cmpobne cmpojne cmpo; bne
5754 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
5755 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
5756 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
5757 bbc& & chkbit; bno\cr
5758 bbs& & chkbit; bo\cr
5759 cmpibe& cmpije& cmpi; be\cr
5760 cmpibg& cmpijg& cmpi; bg\cr
5761 cmpibge& cmpijge& cmpi; bge\cr
5762 cmpibl& cmpijl& cmpi; bl\cr
5763 cmpible& cmpijle& cmpi; ble\cr
5764 cmpibno& cmpijno& cmpi; bno\cr
5765 cmpibne& cmpijne& cmpi; bne\cr
5766 cmpibo& cmpijo& cmpi; bo\cr
5767 cmpobe& cmpoje& cmpo; be\cr
5768 cmpobg& cmpojg& cmpo; bg\cr
5769 cmpobge& cmpojge& cmpo; bge\cr
5770 cmpobl& cmpojl& cmpo; bl\cr
5771 cmpoble& cmpojle& cmpo; ble\cr
5772 cmpobne& cmpojne& cmpo; bne\cr}
5774 @c END TEXI2ROFF-KILL
5780 @node M68K-Dependent
5781 @chapter M680x0 Dependent Features
5784 @node Machine Dependencies
5785 @chapter M680x0 Dependent Features
5788 @cindex M680x0 support
5790 * M68K-Opts:: M680x0 Options
5791 * M68K-Syntax:: Syntax
5792 * M68K-Moto-Syntax:: Motorola Syntax
5793 * M68K-Float:: Floating Point
5794 * M68K-Directives:: 680x0 Machine Directives
5795 * M68K-opcodes:: Opcodes
5799 @section M680x0 Options
5801 @cindex options, M680x0
5802 @cindex M680x0 options
5803 The Motorola 680x0 version of @code{@value{AS}} has two machine dependent options.
5804 One shortens undefined references from 32 to 16 bits, while the
5805 other is used to tell @code{@value{AS}} what kind of machine it is
5808 @cindex @code{-l} option, M680x0
5809 You can use the @samp{-l} option to shorten the size of references to undefined
5810 symbols. If you do not use the @samp{-l} option, references to undefined
5811 symbols are wide enough for a full @code{long} (32 bits). (Since
5812 @code{@value{AS}} cannot know where these symbols end up, @code{@value{AS}} can
5813 only allocate space for the linker to fill in later. Since @code{@value{AS}}
5814 doesn't know how far away these symbols are, it allocates as much space as it
5815 can.) If you use this option, the references are only one word wide (16 bits).
5816 This may be useful if you want the object file to be as small as possible, and
5817 you know that the relevant symbols are always less than 17 bits away.
5819 @cindex @code{-m68000} and related options
5820 @cindex architecture options, M680x0
5821 @cindex M680x0 architecture options
5822 The 680x0 version of @code{@value{AS}} is most frequently used to assemble
5823 programs for the Motorola MC68020 microprocessor. Occasionally it is
5824 used to assemble programs for the mostly similar, but slightly different
5825 MC68000 or MC68010 microprocessors. You can give @code{@value{AS}} the options
5826 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
5827 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
5834 This syntax for the Motorola 680x0 was developed at @sc{mit}.
5836 @cindex M680x0 syntax
5837 @cindex syntax, M680x0
5838 @cindex M680x0 size modifiers
5839 @cindex size modifiers, M680x0
5840 The 680x0 version of @code{@value{AS}} uses syntax compatible with the Sun
5841 assembler. Intervening periods are ignored; for example, @samp{movl} is
5842 equivalent to @samp{move.l}.
5845 If @code{@value{AS}} is compiled with SUN_ASM_SYNTAX defined, it
5846 also allows Sun-style local labels of the form @samp{1$} through
5850 In the following table @dfn{apc} stands for any of the address
5851 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
5852 Program Counter (@samp{pc}), or the zero-address relative to the
5853 program counter (@samp{zpc}).
5855 @cindex M680x0 addressing modes
5856 @cindex addressing modes, M680x0
5857 The following addressing modes are understood:
5860 @samp{#@var{digits}}
5863 @samp{d0} through @samp{d7}
5865 @item Address Register
5866 @samp{a0} through @samp{a7}@*
5867 @samp{a7} is also known as @samp{sp}, i.e. the Stack Pointer. @code{a6}
5868 is also known as @samp{fp}, the Frame Pointer.
5870 @item Address Register Indirect
5871 @samp{a0@@} through @samp{a7@@}
5873 @item Address Register Postincrement
5874 @samp{a0@@+} through @samp{a7@@+}
5876 @item Address Register Predecrement
5877 @samp{a0@@-} through @samp{a7@@-}
5879 @item Indirect Plus Offset
5880 @samp{@var{apc}@@(@var{digits})}
5883 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
5885 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
5888 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
5890 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
5893 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5895 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5897 @item Memory Indirect
5898 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
5901 @samp{@var{symbol}}, or @samp{@var{digits}}
5903 @c pesch@cygnus.com: gnu, rich concur the following needs careful
5904 @c research before documenting.
5905 , or either of the above followed
5906 by @samp{:b}, @samp{:w}, or @samp{:l}.
5910 For some configurations, especially those where the compiler normally
5911 does not prepend an underscore to the names of user variables, the
5912 assembler requires a @samp{%} before any use of a register name. This
5913 is intended to let the assembler distinguish between user variables and
5914 registers named @samp{a0} through @samp{a7}, and so on. The @samp{%} is
5915 always accepted, but is only required for some configurations, notably
5918 @node M68K-Moto-Syntax
5919 @section Motorola Syntax
5921 @cindex Motorola syntax for the 680x0
5922 @cindex alternate syntax for the 680x0
5924 The standard Motorola syntax for this chip differs from the syntax
5925 already discussed (@pxref{M68K-Syntax,,Syntax}). @code{@value{AS}} can
5926 accept both kinds of syntax, even within a single instruction. The
5927 two kinds of syntax are fully compatible.
5929 @c FIXME! I can't figure out what this means. Surely the "always" is in some
5930 @c restricted context, for instance. It's not necessary for the preceding text
5931 @c to explain this, so just ignore it for now; re-enable someday when someone
5932 @c has time to explain it better.
5933 , because the Motorola syntax never uses
5934 the @samp{@@} character and the @sc{mit} syntax always does, except in
5935 cases where the syntaxes are identical.
5938 @cindex M680x0 syntax
5939 @cindex syntax, M680x0
5940 In particular, you may write or generate M68K assembler with the
5941 following conventions:
5943 (In the following table @dfn{apc} stands for any of the address
5944 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
5945 Program Counter (@samp{pc}), or the zero-address relative to the
5946 program counter (@samp{zpc}).)
5948 @cindex M680x0 addressing modes
5949 @cindex addressing modes, M680x0
5950 The following additional addressing modes are understood:
5952 @item Address Register Indirect
5953 @samp{a0} through @samp{a7}@*
5954 @samp{a7} is also known as @samp{sp}, i.e. the Stack Pointer. @code{a6}
5955 is also known as @samp{fp}, the Frame Pointer.
5957 @item Address Register Postincrement
5958 @samp{(a0)+} through @samp{(a7)+}
5960 @item Address Register Predecrement
5961 @samp{-(a0)} through @samp{-(a7)}
5963 @item Indirect Plus Offset
5964 @samp{@var{digits}(@var{apc})}
5967 @samp{@var{digits}(@var{apc},(@var{register}.@var{size}*@var{scale})}@*
5968 or @samp{(@var{apc},@var{register}.@var{size}*@var{scale})}@*
5969 In either case, @var{size} and @var{scale} are optional
5970 (@var{scale} defaults to @samp{1}, @var{size} defaults to @samp{l}).
5971 @var{scale} can be @samp{1}, @samp{2}, @samp{4}, or @samp{8}.
5972 @var{size} can be @samp{w} or @samp{l}. @var{scale} is only supported
5973 on the 68020 and greater.
5977 @section Floating Point
5979 @cindex floating point, M680x0
5980 @cindex M680x0 floating point
5981 @c FIXME is this "not too well tested" crud STILL true?
5982 The floating point code is not too well tested, and may have
5985 Packed decimal (P) format floating literals are not supported.
5986 Feel free to add the code!
5988 The floating point formats generated by directives are these.
5992 @cindex @code{float} directive, M680x0
5993 @code{Single} precision floating point constants.
5996 @cindex @code{double} directive, M680x0
5997 @code{Double} precision floating point constants.
6000 There is no directive to produce regions of memory holding
6001 extended precision numbers, however they can be used as
6002 immediate operands to floating-point instructions. Adding a
6003 directive to create extended precision numbers would not be
6004 hard, but it has not yet seemed necessary.
6006 @node M68K-Directives
6007 @section 680x0 Machine Directives
6009 @cindex M680x0 directives
6010 @cindex directives, M680x0
6011 In order to be compatible with the Sun assembler the 680x0 assembler
6012 understands the following directives.
6016 @cindex @code{data1} directive, M680x0
6017 This directive is identical to a @code{.data 1} directive.
6020 @cindex @code{data2} directive, M680x0
6021 This directive is identical to a @code{.data 2} directive.
6024 @cindex @code{even} directive, M680x0
6025 This directive is identical to a @code{.align 1} directive.
6026 @c Is this true? does it work???
6029 @cindex @code{skip} directive, M680x0
6030 This directive is identical to a @code{.space} directive.
6037 @cindex M680x0 opcodes
6038 @cindex opcodes, M680x0
6039 @cindex instruction set, M680x0
6040 @c pesch@cygnus.com: I don't see any point in the following
6041 @c paragraph. Bugs are bugs; how does saying this
6044 Danger: Several bugs have been found in the opcode table (and
6045 fixed). More bugs may exist. Be careful when using obscure
6050 * M68K-Branch:: Branch Improvement
6051 * M68K-Chars:: Special Characters
6055 @subsection Branch Improvement
6057 @cindex pseudo-opcodes, M680x0
6058 @cindex M680x0 pseudo-opcodes
6059 @cindex branch improvement, M680x0
6060 @cindex M680x0 branch improvement
6061 Certain pseudo opcodes are permitted for branch instructions.
6062 They expand to the shortest branch instruction that reach the
6063 target. Generally these mnemonics are made by substituting @samp{j} for
6064 @samp{b} at the start of a Motorola mnemonic.
6066 The following table summarizes the pseudo-operations. A @code{*} flags
6067 cases that are more fully described after the table:
6071 +-------------------------------------------------
6073 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
6074 +-------------------------------------------------
6075 jbsr |bsrs bsr bsrl jsr jsr
6076 jra |bras bra bral jmp jmp
6077 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
6078 * dbXX |dbXX dbXX dbXX; bra; jmpl
6079 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
6082 NX: negative of condition XX
6085 @center @code{*}---see full description below
6090 These are the simplest jump pseudo-operations; they always map to one
6091 particular machine instruction, depending on the displacement to the
6095 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
6096 where @var{XX} is a conditional branch or condition-code test. The full
6097 list of pseudo-ops in this family is:
6099 jhi jls jcc jcs jne jeq jvc
6100 jvs jpl jmi jge jlt jgt jle
6103 For the cases of non-PC relative displacements and long displacements on
6104 the 68000 or 68010, @code{@value{AS}} issues a longer code fragment in terms of
6105 @var{NX}, the opposite condition to @var{XX}. For example, for the
6106 non-PC relative case:
6118 The full family of pseudo-operations covered here is
6120 dbhi dbls dbcc dbcs dbne dbeq dbvc
6121 dbvs dbpl dbmi dbge dblt dbgt dble
6125 Other than for word and byte displacements, when the source reads
6126 @samp{db@var{XX} foo}, @code{@value{AS}} emits
6135 This family includes
6137 fjne fjeq fjge fjlt fjgt fjle fjf
6138 fjt fjgl fjgle fjnge fjngl fjngle fjngt
6139 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
6140 fjor fjseq fjsf fjsne fjst fjueq fjuge
6141 fjugt fjule fjult fjun
6144 For branch targets that are not PC relative, @code{@value{AS}} emits
6150 when it encounters @samp{fj@var{XX} foo}.
6155 @subsection Special Characters
6157 @cindex special characters, M680x0
6158 @cindex M680x0 immediate character
6159 @cindex immediate character, M680x0
6160 @cindex M680x0 line comment character
6161 @cindex line comment character, M680x0
6162 @cindex comments, M680x0
6163 The immediate character is @samp{#} for Sun compatibility. The
6164 line-comment character is @samp{|}. If a @samp{#} appears at the
6165 beginning of a line, it is treated as a comment unless it looks like
6166 @samp{# line file}, in which case it is treated normally.
6170 @c FIXME! Stop ignoring when filled in.
6175 The 32x32 version of @code{@value{AS}} accepts a @samp{-m32032} option to
6176 specify thiat it is compiling for a 32032 processor, or a
6177 @samp{-m32532} to specify that it is compiling for a 32532 option.
6178 The default (if neither is specified) is chosen when the assembler
6182 I don't know anything about the 32x32 syntax assembled by
6183 @code{@value{AS}}. Someone who undersands the processor (I've never seen
6184 one) and the possible syntaxes should write this section.
6186 @section Floating Point
6187 The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{AS}}
6188 only creates single or double precision values. I don't know if the
6189 32x32 understands extended precision numbers.
6191 @section 32x32 Machine Directives
6192 The 32x32 has no machine dependent directives.
6198 @node Sparc-Dependent
6199 @chapter SPARC Dependent Features
6202 @node Machine Dependencies
6203 @chapter SPARC Dependent Features
6206 @cindex SPARC support
6208 * Sparc-Opts:: Options
6209 * Sparc-Float:: Floating Point
6210 * Sparc-Directives:: Sparc Machine Directives
6216 @cindex options for SPARC
6217 @cindex SPARC options
6218 @cindex architectures, SPARC
6219 @cindex SPARC architectures
6220 The SPARC chip family includes several successive levels (or other
6221 variants) of chip, using the same core instruction set, but including
6222 a few additional instructions at each level.
6224 By default, @code{@value{AS}} assumes the core instruction set (SPARC
6225 v6), but ``bumps'' the architecture level as needed: it switches to
6226 successively higher architectures as it encounters instructions that
6227 only exist in the higher levels.
6230 @item -Av6 | -Av7 | -Av8 | -Asparclite
6235 Use one of the @samp{-A} options to select one of the SPARC
6236 architectures explicitly. If you select an architecture explicitly,
6237 @code{@value{AS}} reports a fatal error if it encounters an instruction
6238 or feature requiring a higher level.
6241 Permit the assembler to ``bump'' the architecture level as required, but
6242 warn whenever it is necessary to switch to another level.
6246 @c FIXME: (sparc) Fill in "syntax" section!
6247 @c subsection syntax
6248 I don't know anything about Sparc syntax. Someone who does
6249 will have to write this section.
6253 @section Floating Point
6255 @cindex floating point, SPARC (@sc{ieee})
6256 @cindex SPARC floating point (@sc{ieee})
6257 The Sparc uses @sc{ieee} floating-point numbers.
6259 @node Sparc-Directives
6260 @section Sparc Machine Directives
6262 @cindex SPARC machine directives
6263 @cindex machine directives, SPARC
6264 The Sparc version of @code{@value{AS}} supports the following additional
6269 @cindex @code{common} directive, SPARC
6270 This must be followed by a symbol name, a positive number, and
6271 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
6272 syntax is different.
6275 @cindex @code{half} directive, SPARC
6276 This is functionally identical to @code{.short}.
6279 @cindex @code{proc} directive, SPARC
6280 This directive is ignored. Any text following it on the same
6281 line is also ignored.
6284 @cindex @code{reserve} directive, SPARC
6285 This must be followed by a symbol name, a positive number, and
6286 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
6287 syntax is different.
6290 @cindex @code{seg} directive, SPARC
6291 This must be followed by @code{"text"}, @code{"data"}, or
6292 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
6296 @cindex @code{skip} directive, SPARC
6297 This is functionally identical to the @code{.space} directive.
6300 @cindex @code{word} directive, SPARC
6301 On the Sparc, the .word directive produces 32 bit values,
6302 instead of the 16 bit values it produces on many other machines.
6309 @node i386-Dependent
6310 @chapter 80386 Dependent Features
6313 @node Machine Dependencies
6314 @chapter 80386 Dependent Features
6317 @cindex i386 support
6318 @cindex i80306 support
6320 * i386-Options:: Options
6321 * i386-Syntax:: AT&T Syntax versus Intel Syntax
6322 * i386-Opcodes:: Opcode Naming
6323 * i386-Regs:: Register Naming
6324 * i386-prefixes:: Opcode Prefixes
6325 * i386-Memory:: Memory References
6326 * i386-jumps:: Handling of Jump Instructions
6327 * i386-Float:: Floating Point
6328 * i386-Notes:: Notes
6334 @cindex options for i386 (none)
6335 @cindex i386 options (none)
6336 The 80386 has no machine dependent options.
6339 @section AT&T Syntax versus Intel Syntax
6341 @cindex i386 syntax compatibility
6342 @cindex syntax compatibility, i386
6343 In order to maintain compatibility with the output of @code{@value{GCC}},
6344 @code{@value{AS}} supports AT&T System V/386 assembler syntax. This is quite
6345 different from Intel syntax. We mention these differences because
6346 almost all 80386 documents used only Intel syntax. Notable differences
6347 between the two syntaxes are:
6351 @cindex immediate operands, i386
6352 @cindex i386 immediate operands
6353 @cindex register operands, i386
6354 @cindex i386 register operands
6355 @cindex jump/call operands, i386
6356 @cindex i386 jump/call operands
6357 @cindex operand delimiters, i386
6358 AT&T immediate operands are preceded by @samp{$}; Intel immediate
6359 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
6360 AT&T register operands are preceded by @samp{%}; Intel register operands
6361 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
6362 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
6365 @cindex i386 source, destination operands
6366 @cindex source, destination operands; i386
6367 AT&T and Intel syntax use the opposite order for source and destination
6368 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
6369 @samp{source, dest} convention is maintained for compatibility with
6370 previous Unix assemblers.
6373 @cindex opcode suffixes, i386
6374 @cindex sizes operands, i386
6375 @cindex i386 size suffixes
6376 In AT&T syntax the size of memory operands is determined from the last
6377 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
6378 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
6379 memory references. Intel syntax accomplishes this by prefixes memory
6380 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
6381 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
6382 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
6385 @cindex return instructions, i386
6386 @cindex i386 jump, call, return
6387 Immediate form long jumps and calls are
6388 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
6390 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
6392 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
6393 @samp{ret far @var{stack-adjust}}.
6396 @cindex sections, i386
6397 @cindex i386 sections
6398 The AT&T assembler does not provide support for multiple section
6399 programs. Unix style systems expect all programs to be single sections.
6403 @section Opcode Naming
6405 @cindex i386 opcode naming
6406 @cindex opcode naming, i386
6407 Opcode names are suffixed with one character modifiers which specify the
6408 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
6409 byte, word, and long operands. If no suffix is specified by an
6410 instruction and it contains no memory operands then @code{@value{AS}} tries to
6411 fill in the missing suffix based on the destination register operand
6412 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
6413 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
6414 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
6415 assembler which assumes that a missing opcode suffix implies long
6416 operand size. (This incompatibility does not affect compiler output
6417 since compilers always explicitly specify the opcode suffix.)
6419 Almost all opcodes have the same names in AT&T and Intel format. There
6420 are a few exceptions. The sign extend and zero extend instructions need
6421 two sizes to specify them. They need a size to sign/zero extend
6422 @emph{from} and a size to zero extend @emph{to}. This is accomplished
6423 by using two opcode suffixes in AT&T syntax. Base names for sign extend
6424 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
6425 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
6426 suffixes are tacked on to this base name, the @emph{from} suffix before
6427 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
6428 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
6429 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
6430 and @samp{wl} (from word to long).
6432 @cindex conversion instructions, i386
6433 @cindex i386 conversion instructions
6434 The Intel-syntax conversion instructions
6438 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
6441 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
6444 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
6447 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
6451 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
6452 AT&T naming. @code{@value{AS}} accepts either naming for these instructions.
6454 @cindex jump instructions, i386
6455 @cindex call instructions, i386
6456 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
6457 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
6461 @section Register Naming
6463 @cindex i386 registers
6464 @cindex registers, i386
6465 Register operands are always prefixes with @samp{%}. The 80386 registers
6470 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
6471 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
6472 frame pointer), and @samp{%esp} (the stack pointer).
6475 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
6476 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
6479 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
6480 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
6481 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
6482 @samp{%cx}, and @samp{%dx})
6485 the 6 section registers @samp{%cs} (code section), @samp{%ds}
6486 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
6490 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
6494 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
6495 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
6498 the 2 test registers @samp{%tr6} and @samp{%tr7}.
6501 the 8 floating point register stack @samp{%st} or equivalently
6502 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
6503 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
6507 @section Opcode Prefixes
6509 @cindex i386 opcode prefixes
6510 @cindex opcode prefixes, i386
6511 @cindex prefixes, i386
6512 Opcode prefixes are used to modify the following opcode. They are used
6513 to repeat string instructions, to provide section overrides, to perform
6514 bus lock operations, and to give operand and address size (16-bit
6515 operands are specified in an instruction by prefixing what would
6516 normally be 32-bit operands with a ``operand size'' opcode prefix).
6517 Opcode prefixes are usually given as single-line instructions with no
6518 operands, and must directly precede the instruction they act upon. For
6519 example, the @samp{scas} (scan string) instruction is repeated with:
6525 Here is a list of opcode prefixes:
6529 @cindex section override prefixes, i386
6530 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
6531 @samp{fs}, @samp{gs}. These are automatically added by specifying
6532 using the @var{section}:@var{memory-operand} form for memory references.
6535 @cindex size prefixes, i386
6536 Operand/Address size prefixes @samp{data16} and @samp{addr16}
6537 change 32-bit operands/addresses into 16-bit operands/addresses. Note
6538 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
6539 are not supported (yet).
6542 @cindex bus lock prefixes, i386
6543 @cindex inhibiting interrupts, i386
6544 The bus lock prefix @samp{lock} inhibits interrupts during
6545 execution of the instruction it precedes. (This is only valid with
6546 certain instructions; see a 80386 manual for details).
6549 @cindex coprocessor wait, i386
6550 The wait for coprocessor prefix @samp{wait} waits for the
6551 coprocessor to complete the current instruction. This should never be
6552 needed for the 80386/80387 combination.
6555 @cindex repeat prefixes, i386
6556 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
6557 to string instructions to make them repeat @samp{%ecx} times.
6561 @section Memory References
6563 @cindex i386 memory references
6564 @cindex memory references, i386
6565 An Intel syntax indirect memory reference of the form
6568 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
6572 is translated into the AT&T syntax
6575 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
6579 where @var{base} and @var{index} are the optional 32-bit base and
6580 index registers, @var{disp} is the optional displacement, and
6581 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
6582 to calculate the address of the operand. If no @var{scale} is
6583 specified, @var{scale} is taken to be 1. @var{section} specifies the
6584 optional section register for the memory operand, and may override the
6585 default section register (see a 80386 manual for section register
6586 defaults). Note that section overrides in AT&T syntax @emph{must} have
6587 be preceded by a @samp{%}. If you specify a section override which
6588 coincides with the default section register, @code{@value{AS}} does @emph{not}
6589 output any section register override prefixes to assemble the given
6590 instruction. Thus, section overrides can be specified to emphasize which
6591 section register is used for a given memory operand.
6593 Here are some examples of Intel and AT&T style memory references:
6596 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
6597 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
6598 missing, and the default section is used (@samp{%ss} for addressing with
6599 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
6601 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
6602 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
6603 @samp{foo}. All other fields are missing. The section register here
6604 defaults to @samp{%ds}.
6606 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
6607 This uses the value pointed to by @samp{foo} as a memory operand.
6608 Note that @var{base} and @var{index} are both missing, but there is only
6609 @emph{one} @samp{,}. This is a syntactic exception.
6611 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
6612 This selects the contents of the variable @samp{foo} with section
6613 register @var{section} being @samp{%gs}.
6616 Absolute (as opposed to PC relative) call and jump operands must be
6617 prefixed with @samp{*}. If no @samp{*} is specified, @code{@value{AS}}
6618 always chooses PC relative addressing for jump/call labels.
6620 Any instruction that has a memory operand @emph{must} specify its size (byte,
6621 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
6625 @section Handling of Jump Instructions
6627 @cindex jump optimization, i386
6628 @cindex i386 jump optimization
6629 Jump instructions are always optimized to use the smallest possible
6630 displacements. This is accomplished by using byte (8-bit) displacement
6631 jumps whenever the target is sufficiently close. If a byte displacement
6632 is insufficient a long (32-bit) displacement is used. We do not support
6633 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
6634 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
6635 @samp{%eip} to 16 bits after the word displacement is added.
6637 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
6638 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in byte
6639 displacements, so that if you use these instructions (@code{@value{GCC}} does
6640 not use them) you may get an error message (and incorrect code). The AT&T
6641 80386 assembler tries to get around this problem by expanding @samp{jcxz foo}
6652 @section Floating Point
6654 @cindex i386 floating point
6655 @cindex floating point, i386
6656 All 80387 floating point types except packed BCD are supported.
6657 (BCD support may be added without much difficulty). These data
6658 types are 16-, 32-, and 64- bit integers, and single (32-bit),
6659 double (64-bit), and extended (80-bit) precision floating point.
6660 Each supported type has an opcode suffix and a constructor
6661 associated with it. Opcode suffixes specify operand's data
6662 types. Constructors build these data types into memory.
6666 @cindex @code{float} directive, i386
6667 @cindex @code{single} directive, i386
6668 @cindex @code{double} directive, i386
6669 @cindex @code{tfloat} directive, i386
6670 Floating point constructors are @samp{.float} or @samp{.single},
6671 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
6672 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
6673 @samp{t} stands for temporary real, and that the 80387 only supports
6674 this format via the @samp{fldt} (load temporary real to stack top) and
6675 @samp{fstpt} (store temporary real and pop stack) instructions.
6678 @cindex @code{word} directive, i386
6679 @cindex @code{long} directive, i386
6680 @cindex @code{int} directive, i386
6681 @cindex @code{quad} directive, i386
6682 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
6683 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
6684 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
6685 (quad). As with the temporary real format the 64-bit @samp{q} format is
6686 only present in the @samp{fildq} (load quad integer to stack top) and
6687 @samp{fistpq} (store quad integer and pop stack) instructions.
6690 Register to register operations do not require opcode suffixes,
6691 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
6693 @cindex i386 @code{fwait} instruction
6694 @cindex @code{fwait instruction}, i386
6695 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
6696 instructions are almost never needed (this is not the case for the
6697 80286/80287 and 8086/8087 combinations). Therefore, @code{@value{AS}} suppresses
6698 the @samp{fwait} instruction whenever it is implicitly selected by one
6699 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
6700 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
6701 instructions are made equivalent to @samp{f@dots{}} instructions. If
6702 @samp{fwait} is desired it must be explicitly coded.
6707 @cindex i386 @code{mul}, @code{imul} instructions
6708 @cindex @code{mul} instruction, i386
6709 @cindex @code{imul} instruction, i386
6710 There is some trickery concerning the @samp{mul} and @samp{imul}
6711 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
6712 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
6713 for @samp{imul}) can be output only in the one operand form. Thus,
6714 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
6715 the expanding multiply would clobber the @samp{%edx} register, and this
6716 would confuse @code{@value{GCC}} output. Use @samp{imul %ebx} to get the
6717 64-bit product in @samp{%edx:%eax}.
6719 We have added a two operand form of @samp{imul} when the first operand
6720 is an immediate mode expression and the second operand is a register.
6721 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
6722 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
6729 @node Z8000-Dependent
6730 @chapter Z8000 Dependent Features
6733 @node Machine Dependencies
6734 @chapter Z8000 Dependent Features
6737 @cindex Z8000 support
6738 The Z8000 @value{AS} supports both members of the Z8000 family: the
6739 unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with
6742 When the assembler is in unsegmented mode (specified with the
6743 @code{unsegm} directive), an address takes up one word (16 bit)
6744 sized register. When the assembler is in segmented mode (specified with
6745 the @code{segm} directive), a 24-bit address takes up a long (32 bit)
6746 register. @xref{Z8000 Directives,,Assembler Directives for the Z8000},
6747 for a list of other Z8000 specific assembler directives.
6750 * Z8000 Options:: No special command-line options for Z8000
6751 * Z8000 Syntax:: Assembler syntax for the Z8000
6752 * Z8000 Directives:: Special directives for the Z8000
6753 * Z8000 Opcodes:: Opcodes
6759 @cindex Z8000 options
6760 @cindex options, Z8000
6761 @code{@value{AS}} has no additional command-line options for the Zilog
6767 * Z8000-Chars:: Special Characters
6768 * Z8000-Regs:: Register Names
6769 * Z8000-Addressing:: Addressing Modes
6773 @subsection Special Characters
6775 @cindex line comment character, Z8000
6776 @cindex Z8000 line comment character
6777 @samp{!} is the line comment character.
6779 @cindex line separator, Z8000
6780 @cindex statement separator, Z8000
6781 @cindex Z8000 line separator
6782 You can use @samp{;} instead of a newline to separate statements.
6785 @subsection Register Names
6787 @cindex Z8000 registers
6788 @cindex registers, Z8000
6789 The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer
6790 to different sized groups of registers by register number, with the
6791 prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and
6792 @samp{rq} for 64 bit registers. You can also refer to the contents of
6793 the first eight (of the sixteen 16 bit registers) by bytes. They are
6794 named @samp{r@var{n}h} and @samp{r@var{n}l}.
6797 @exdent @emph{byte registers}
6798 r0l r0h r1h r1l r2h r2l r3h r3l
6799 r4h r4l r5h r5l r6h r6l r7h r7l
6801 @exdent @emph{word registers}
6802 r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15
6804 @exdent @emph{long word registers}
6805 rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14
6807 @exdent @emph{quad word registers}
6811 @node Z8000-Addressing
6812 @subsection Addressing Modes
6814 @cindex addressing modes, Z8000
6815 @cindex Z800 addressing modes
6816 @value{AS} understands the following addressing modes for the Z8000:
6826 Direct: the 16 bit or 24 bit address (depending on whether the assembler
6827 is in segmented or unsegmented mode) of the operand is in the instruction.
6829 @item address(r@var{n})
6830 Indexed: the 16 or 24 bit address is added to the 16 bit register to produce
6831 the final address in memory of the operand.
6833 @item r@var{n}(#@var{imm})
6834 Base Address: the 16 or 24 bit register is added to the 16 bit sign
6835 extended immediate displacement to produce the final address in memory
6838 @item r@var{n}(r@var{m})
6839 Base Index: the 16 or 24 bit register r@var{n} is added to the sign
6840 extended 16 bit index register r@var{m} to produce the final address in
6841 memory of the operand.
6844 Immediate data @var{xx}.
6847 @node Z8000 Directives
6848 @section Assembler Directives for the Z8000
6850 @cindex Z8000 directives
6851 @cindex directives, Z8000
6852 The Z8000 port of @value{AS} includes these additional assembler directives,
6853 for compatibility with other Z8000 assemblers. As shown, these do not
6854 begin with @samp{.} (unlike the ordinary @value{AS} directives).
6859 Generates code for the segmented Z8001.
6863 Generates code for the unsegmented Z8002.
6867 Synonym for @code{.file}
6871 Synonum for @code{.global}
6875 Synonym for @code{.word}
6879 Synonym for @code{.long}
6883 Synonym for @code{.byte}
6887 Assemble a string. @code{sval} expects one string literal, delimited by
6888 single quotes. It assembles each byte of the string into consecutive
6889 addresses. You can use the escape sequence @samp{%@var{xx}} (where
6890 @var{xx} represents a two-digit hexadecimal number) to represent the
6891 character whose @sc{ascii} value is @var{xx}. Use this feature to
6892 describe single quote and other characters that may not appear in string
6893 literals as themselves. For example, the C statement @w{@samp{char *a =
6894 "he said \"it's 50% off\"";}} is represented in Z8000 assembly language
6895 (shown with the assembler output in hex at the left) as
6899 @let@nonarrowing=@comment
6902 68652073 sval 'he said %22it%27s 50%25 off%22%00'
6915 synonym for @code{.section}
6919 synonym for @code{.space}
6923 synonym for @code{.align 1}
6929 @cindex Z8000 opcode summary
6930 @cindex opcode summary, Z8000
6931 @cindex mnemonics, Z8000
6932 @cindex instruction summary, Z8000
6933 For detailed information on the Z8000 machine instruction set, see
6934 @cite{Z8000 Technical Manual}.
6937 @c this table, due to the multi-col faking and hardcoded order, looks silly
6938 @c except in smallbook. See comments below "@set SMALL" near top of this file.
6940 The following table summarizes the opcodes and their arguments:
6943 @let@nonarrowing=@comment
6947 rs @r{16 bit source register}
6948 rd @r{16 bit destination register}
6949 rbs @r{8 bit source register}
6950 rbd @r{8 bit destination register}
6951 rrs @r{32 bit source register}
6952 rrd @r{32 bit destination register}
6953 rqs @r{64 bit source register}
6954 rqd @r{64 bit destination register}
6955 addr @r{16/24 bit address}
6956 imm @r{immediate data}
6958 adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc
6959 adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc
6960 add rd,@@rs clrb rbd dab rbd
6961 add rd,addr com @@rd dbjnz rbd,disp7
6962 add rd,addr(rs) com addr dec @@rd,imm4m1
6963 add rd,imm16 com addr(rd) dec addr(rd),imm4m1
6964 add rd,rs com rd dec addr,imm4m1
6965 addb rbd,@@rs comb @@rd dec rd,imm4m1
6966 addb rbd,addr comb addr decb @@rd,imm4m1
6967 addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1
6968 addb rbd,imm8 comb rbd decb addr,imm4m1
6969 addb rbd,rbs comflg flags decb rbd,imm4m1
6970 addl rrd,@@rs cp @@rd,imm16 di i2
6971 addl rrd,addr cp addr(rd),imm16 div rrd,@@rs
6972 addl rrd,addr(rs) cp addr,imm16 div rrd,addr
6973 addl rrd,imm32 cp rd,@@rs div rrd,addr(rs)
6974 addl rrd,rrs cp rd,addr div rrd,imm16
6975 and rd,@@rs cp rd,addr(rs) div rrd,rs
6976 and rd,addr cp rd,imm16 divl rqd,@@rs
6977 and rd,addr(rs) cp rd,rs divl rqd,addr
6978 and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs)
6979 and rd,rs cpb addr(rd),imm8 divl rqd,imm32
6980 andb rbd,@@rs cpb addr,imm8 divl rqd,rrs
6981 andb rbd,addr cpb rbd,@@rs djnz rd,disp7
6982 andb rbd,addr(rs) cpb rbd,addr ei i2
6983 andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs
6984 andb rbd,rbs cpb rbd,imm8 ex rd,addr
6985 bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs)
6986 bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs
6987 bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs
6988 bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr
6989 bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs)
6990 bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs
6991 bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8
6992 bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8
6993 bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8
6994 bitb rbd,rs cpl rrd,@@rs ext8f imm8
6995 bpt cpl rrd,addr exts rrd
6996 call @@rd cpl rrd,addr(rs) extsb rd
6997 call addr cpl rrd,imm32 extsl rqd
6998 call addr(rd) cpl rrd,rrs halt
6999 calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs
7000 clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16
7001 clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs
7002 clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16
7003 clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1
7004 clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1
7005 inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs)
7006 inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16
7007 incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs
7008 incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs
7009 incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr
7010 incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs)
7011 ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32
7012 indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs
7013 inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd
7014 inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr
7015 iret ldib @@rd,@@rs,rr neg addr(rd)
7016 jp cc,@@rd ldir @@rd,@@rs,rr neg rd
7017 jp cc,addr ldirb @@rd,@@rs,rr negb @@rd
7018 jp cc,addr(rd) ldk rd,imm4 negb addr
7019 jr cc,disp8 ldl @@rd,rrs negb addr(rd)
7020 ld @@rd,imm16 ldl addr(rd),rrs negb rbd
7021 ld @@rd,rs ldl addr,rrs nop
7022 ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs
7023 ld addr(rd),rs ldl rd(rx),rrs or rd,addr
7024 ld addr,imm16 ldl rrd,@@rs or rd,addr(rs)
7025 ld addr,rs ldl rrd,addr or rd,imm16
7026 ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs
7027 ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs
7028 ld rd,@@rs ldl rrd,rrs orb rbd,addr
7029 ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs)
7030 ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8
7031 ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs
7032 ld rd,rs ldm addr(rd),rs,n out @@rd,rs
7033 ld rd,rs(imm16) ldm addr,rs,n out imm16,rs
7034 ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs
7035 lda rd,addr ldm rd,addr(rs),n outb imm16,rbs
7036 lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra
7037 lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba
7038 lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra
7039 ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra
7040 ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs
7041 ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs
7042 ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs
7043 ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs
7044 ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs
7045 ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs
7046 ldb rbd,@@rs mbit popl addr,@@rs
7047 ldb rbd,addr mreq rd popl rrd,@@rs
7048 ldb rbd,addr(rs) mres push @@rd,@@rs
7049 ldb rbd,imm8 mset push @@rd,addr
7050 ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs)
7051 ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16
7052 push @@rd,rs set addr,imm4 subl rrd,imm32
7053 pushl @@rd,@@rs set rd,imm4 subl rrd,rrs
7054 pushl @@rd,addr set rd,rs tcc cc,rd
7055 pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd
7056 pushl @@rd,rrs setb addr(rd),imm4 test @@rd
7057 res @@rd,imm4 setb addr,imm4 test addr
7058 res addr(rd),imm4 setb rbd,imm4 test addr(rd)
7059 res addr,imm4 setb rbd,rs test rd
7060 res rd,imm4 setflg imm4 testb @@rd
7061 res rd,rs sinb rbd,imm16 testb addr
7062 resb @@rd,imm4 sinb rd,imm16 testb addr(rd)
7063 resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd
7064 resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd
7065 resb rbd,imm4 sinib @@rd,@@rs,ra testl addr
7066 resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd)
7067 resflg imm4 sla rd,imm8 testl rrd
7068 ret cc slab rbd,imm8 trdb @@rd,@@rs,rba
7069 rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba
7070 rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr
7071 rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr
7072 rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr
7073 rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr
7074 rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr
7075 rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr
7076 rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd
7077 rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr
7078 rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd)
7079 rsvd36 sra rd,imm8 tset rd
7080 rsvd38 srab rbd,imm8 tsetb @@rd
7081 rsvd78 sral rrd,imm8 tsetb addr
7082 rsvd7e srl rd,imm8 tsetb addr(rd)
7083 rsvd9d srlb rbd,imm8 tsetb rbd
7084 rsvd9f srll rrd,imm8 xor rd,@@rs
7085 rsvdb9 sub rd,@@rs xor rd,addr
7086 rsvdbf sub rd,addr xor rd,addr(rs)
7087 sbc rd,rs sub rd,addr(rs) xor rd,imm16
7088 sbcb rbd,rbs sub rd,imm16 xor rd,rs
7089 sc imm8 sub rd,rs xorb rbd,@@rs
7090 sda rd,rs subb rbd,@@rs xorb rbd,addr
7091 sdab rbd,rs subb rbd,addr xorb rbd,addr(rs)
7092 sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8
7093 sdl rd,rs subb rbd,imm8 xorb rbd,rbs
7094 sdlb rbd,rs subb rbd,rbs xorb rbd,rbs
7095 sdll rrd,rs subl rrd,@@rs
7096 set @@rd,imm4 subl rrd,addr
7097 set addr(rd),imm4 subl rrd,addr(rs)
7109 @node MIPS-Dependent
7110 @chapter MIPS Dependent Features
7113 @node Machine Dependencies
7114 @chapter MIPS Dependent Features
7119 @sc{gnu} @code{@value{AS}} for @sc{mips} architectures supports the @sc{mips}
7120 @sc{r2000} and @sc{r3000} processors. For information about the @sc{mips}
7121 instruction set, see @cite{MIPS RISC Architecture}, by Kane and Heindrich
7125 * MIPS Opts:: Assembler options
7126 * MIPS Object:: ECOFF object code
7127 * MIPS Stabs:: Directives for debugging information
7131 @section Assembler options
7133 The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support three
7134 special options, and accept one other for command-line compatibility.
7137 @cindex @code{-G} option (MIPS)
7139 This option sets the largest size of an object that can be referenced
7140 implicitly with the @code{gp} register. It is only accepted for targets
7141 that use @sc{ecoff} format. The default value is 8.
7143 @cindex @code{-EB} option (MIPS)
7144 @cindex @code{-EL} option (MIPS)
7145 @cindex MIPS big-endian output
7146 @cindex MIPS little-endian output
7147 @cindex big-endian output, MIPS
7148 @cindex little-endian output, MIPS
7151 Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or
7152 little-endian output at run time (unlike the other @sc{gnu} development
7153 tools, which must be configured for one or the other). Use @samp{-EB}
7154 to select big-endian output, and @samp{-EL} for little-endian.
7156 @cindex @code{-nocpp} ignored (MIPS)
7158 This option is ignored. It is accepted for command-line compatibility with
7159 other assemblers, which use it to turn off C style preprocessing. With
7160 @sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the
7161 @sc{gnu} assembler itself never runs the C preprocessor.
7165 @section MIPS ECOFF object code
7167 @cindex ECOFF sections
7168 @cindex MIPS ECOFF sections
7169 Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections
7170 besides the usual @code{.text}, @code{.data} and @code{.bss}. The
7171 additional sections are @code{.rdata}, used for read-only data,
7172 @code{.sdata}, used for small data, and @code{.sbss}, used for small
7175 @cindex small objects, MIPS ECOFF
7176 @cindex @code{gp} register, MIPS
7177 When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28})
7178 register to form the address of a ``small object''. Any object in the
7179 @code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense.
7180 For external objects, or for objects in the @code{.bss} section, you can use
7181 the @sc{gcc} @samp{-G} option to control the size of objects addressed via
7182 @code{$gp}; the default value is 8, meaning that a reference to any object
7183 eight bytes or smaller uses @code{$gp}. Passing @samp{-G 0} to
7184 @code{@value{AS}} prevents it from using the @code{$gp} register on the basis
7185 of object size (but the assembler uses @code{$gp} for objects in @code{.sdata}
7186 or @code{sbss} in any case). The size of an object in the @code{.bss} section
7187 is set by the @code{.comm} or @code{.lcomm} directive that defines it. The
7188 size of an external object may be set with the @code{.extern} directive. For
7189 example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes
7190 in length, whie leaving @code{sym} otherwise undefined.
7192 Using small @sc{ecoff} objects requires linker support, and assumes that the
7193 @code{$gp} register is correctly initialized (normally done automatically by
7194 the startup code). @sc{mips} @sc{ecoff} assembly code must not modify the
7195 @code{$gp} register.
7198 @section Directives for debugging information
7200 @cindex MIPS debugging directives
7201 @sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for
7202 generating debugging information which are not support by traditional @sc{mips}
7203 assemblers. These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file},
7204 @code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val},
7205 @code{.stabd}, @code{.stabn}, and @code{.stabs}. The debugging information
7206 generated by the three @code{.stab} directives can only be read by @sc{gdb},
7207 not by traditional @sc{mips} debuggers (this enhancement is required to fully
7208 support C++ debugging). These directives are primarily used by compilers, not
7209 assembly language programmers!
7214 @c reverse effect of @down at top of generic Machine-Dep chapter
7218 @node Acknowledgements
7219 @chapter Acknowledgements
7221 If you have contributed to @code{@value{AS}} and your name isn't listed here,
7222 it is not meant as a slight. We just don't know about it. Send mail to the
7223 maintainer, and we'll correct the situation. Currently (January 1994), the
7224 maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
7226 Dean Elsner wrote the original GNU assembler for the VAX.@footnote{Any more
7229 Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
7230 information and the 68k series machines, most of the preprocessing pass, and
7231 extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}.
7233 K. Richard Pixley maintained GAS for a while, adding various enhancements and
7234 many bug fixes, including merging support for several processors, breaking GAS
7235 up to handle multiple object file format back ends (including heavy rewrite,
7236 testing, an integration of the coff and b.out back ends), adding configuration
7237 including heavy testing and verification of cross assemblers and file splits
7238 and renaming, converted GAS to strictly ANSI C including full prototypes, added
7239 support for m680[34]0 and cpu32, did considerable work on i960 including a COFF
7240 port (including considerable amounts of reverse engineering), a SPARC opcode
7241 file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know''
7242 assertions and made them work, much other reorganization, cleanup, and lint.
7244 Ken Raeburn wrote the high-level BFD interface code to replace most of the code
7245 in format-specific I/O modules.
7247 The original VMS support was contributed by David L. Kashtan. Eric Youngdale
7248 has done much work with it since.
7250 The Intel 80386 machine description was written by Eliot Dresselhaus.
7252 Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
7254 The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
7255 University and Torbjorn Granlund of the Swedish Institute of Computer Science.
7257 Keith Knowles at the Open Software Foundation wrote the original MIPS back end
7258 (@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support
7259 (which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to
7260 support a.out format.
7262 Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k,
7263 tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
7264 Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
7265 use BFD for some low-level operations, for use with the H8/300 and AMD 29k
7268 John Gilmore built the AMD 29000 support, added @code{.include} support, and
7269 simplified the configuration of which versions accept which directives. He
7270 updated the 68k machine description so that Motorola's opcodes always produced
7271 fixed-size instructions (e.g. @code{jsr}), while synthetic instructions
7272 remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested
7273 cross-compilation support, and one bug in relaxation that took a week and
7274 required the proverbial one-bit fix.
7276 Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
7277 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
7278 and made a few other minor patches.
7280 Steve Chamberlain made @code{@value{AS}} able to generate listings.
7282 Hewlett-Packard contributed support for the HP9000/300.
7284 Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
7285 along with a fairly extensive HPPA testsuite (for both SOM and ELF object
7286 formats). This work was supported by both the Center for Software Science at
7287 the University of Utah and Cygnus Support.
7289 Support for ELF format files has been worked on by Mark Eichin of Cygnus
7290 Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
7291 Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
7292 Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
7293 and some initial 64-bit support).
7295 Several engineers at Cygnus Support have also provided many small bug fixes and
7296 configuration enhancements.
7298 Many others have contributed large or small bugfixes and enhancements. If
7299 you have contributed significant work and are not mentioned on this list, and
7300 want to be, let us know. Some of the history has been lost; we are not
7301 intentionally leaving anyone out.