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} ] [ -mips1 ] [ -mips2 ] [ -mips3 ]
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/R4000/R6000 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.
382 Generate code for a particular MIPS Instruction Set Architecture level. -mips1
383 corresponds to the @sc{r2000} and @sc{r3000} processors, -mips2 to the
384 @sc{r6000} processor, and -mips3 to the @sc{r4000} processor.
387 This option is ignored. It is accepted for compatibility with the native
393 * Manual:: Structure of this Manual
394 * GNU Assembler:: @value{AS}, the GNU Assembler
395 * Object Formats:: Object File Formats
396 * Command Line:: Command Line
397 * Input Files:: Input Files
398 * Object:: Output (Object) File
399 * Errors:: Error and Warning Messages
403 @section Structure of this Manual
405 @cindex manual, structure and purpose
406 This manual is intended to describe what you need to know to use
407 @sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including
408 notation for symbols, constants, and expressions; the directives that
409 @code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}.
412 We also cover special features in the @value{TARGET}
413 configuration of @code{@value{AS}}, including assembler directives.
416 This manual also describes some of the machine-dependent features of
417 various flavors of the assembler.
420 @cindex machine instructions (not covered)
421 On the other hand, this manual is @emph{not} intended as an introduction
422 to programming in assembly language---let alone programming in general!
423 In a similar vein, we make no attempt to introduce the machine
424 architecture; we do @emph{not} describe the instruction set, standard
425 mnemonics, registers or addressing modes that are standard to a
426 particular architecture.
428 You may want to consult the manufacturer's
429 machine architecture manual for this information.
433 For information on the H8/300 machine instruction set, see @cite{H8/300
434 Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H,
435 see @cite{H8/300H Series Programming Manual} (Hitachi).
438 For information on the H8/500 machine instruction set, see @cite{H8/500
439 Series Programming Manual} (Hitachi M21T001).
442 For information on the Hitachi SH machine instruction set, see
443 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
446 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
450 @c I think this is premature---pesch@cygnus.com, 17jan1991
452 Throughout this manual, we assume that you are running @dfn{GNU},
453 the portable operating system from the @dfn{Free Software
454 Foundation, Inc.}. This restricts our attention to certain kinds of
455 computer (in particular, the kinds of computers that GNU can run on);
456 once this assumption is granted examples and definitions need less
459 @code{@value{AS}} is part of a team of programs that turn a high-level
460 human-readable series of instructions into a low-level
461 computer-readable series of instructions. Different versions of
462 @code{@value{AS}} are used for different kinds of computer.
465 @c There used to be a section "Terminology" here, which defined
466 @c "contents", "byte", "word", and "long". Defining "word" to any
467 @c particular size is confusing when the .word directive may generate 16
468 @c bits on one machine and 32 bits on another; in general, for the user
469 @c version of this manual, none of these terms seem essential to define.
470 @c They were used very little even in the former draft of the manual;
471 @c this draft makes an effort to avoid them (except in names of
475 @section @value{AS}, the GNU Assembler
477 GNU @code{as} is really a family of assemblers.
479 This manual describes @code{@value{AS}}, a member of that family which is
480 configured for the @value{TARGET} architectures.
482 If you use (or have used) the GNU assembler on one architecture, you
483 should find a fairly similar environment when you use it on another
484 architecture. Each version has much in common with the others,
485 including object file formats, most assembler directives (often called
486 @dfn{pseudo-ops}) and assembler syntax.@refill
488 @cindex purpose of @sc{gnu} @code{@value{AS}}
489 @code{@value{AS}} is primarily intended to assemble the output of the
490 GNU C compiler @code{@value{GCC}} for use by the linker
491 @code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}}
492 assemble correctly everything that other assemblers for the same
493 machine would assemble.
495 Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
498 @c This remark should appear in generic version of manual; assumption
499 @c here is that generic version sets M680x0.
500 This doesn't mean @code{@value{AS}} always uses the same syntax as another
501 assembler for the same architecture; for example, we know of several
502 incompatible versions of 680x0 assembly language syntax.
505 Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
506 program in one pass of the source file. This has a subtle impact on the
507 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
510 @section Object File Formats
512 @cindex object file format
513 The GNU assembler can be configured to produce several alternative
514 object file formats. For the most part, this does not affect how you
515 write assembly language programs; but directives for debugging symbols
516 are typically different in different file formats. @xref{Symbol
517 Attributes,,Symbol Attributes}.
520 On the @value{TARGET}, @code{@value{AS}} is configured to produce
521 @value{OBJ-NAME} format object files.
523 @c The following should exhaust all configs that set MULTI-OBJ, ideally
525 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
526 @code{a.out} or COFF format object files.
529 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
530 @code{b.out} or COFF format object files.
533 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
534 SOM or ELF format object files.
539 @section Command Line
541 @cindex command line conventions
542 After the program name @code{@value{AS}}, the command line may contain
543 options and file names. Options may appear in any order, and may be
544 before, after, or between file names. The order of file names is
547 @cindex standard input, as input file
549 @file{--} (two hyphens) by itself names the standard input file
550 explicitly, as one of the files for @code{@value{AS}} to assemble.
552 @cindex options, command line
553 Except for @samp{--} any command line argument that begins with a
554 hyphen (@samp{-}) is an option. Each option changes the behavior of
555 @code{@value{AS}}. No option changes the way another option works. An
556 option is a @samp{-} followed by one or more letters; the case of
557 the letter is important. All options are optional.
559 Some options expect exactly one file name to follow them. The file
560 name may either immediately follow the option's letter (compatible
561 with older assemblers) or it may be the next command argument (GNU
562 standard). These two command lines are equivalent:
565 @value{AS} -o my-object-file.o mumble.s
566 @value{AS} -omy-object-file.o mumble.s
573 @cindex source program
575 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
576 describe the program input to one run of @code{@value{AS}}. The program may
577 be in one or more files; how the source is partitioned into files
578 doesn't change the meaning of the source.
580 @c I added "con" prefix to "catenation" just to prove I can overcome my
581 @c APL training... pesch@cygnus.com
582 The source program is a concatenation of the text in all the files, in the
585 Each time you run @code{@value{AS}} it assembles exactly one source
586 program. The source program is made up of one or more files.
587 (The standard input is also a file.)
589 You give @code{@value{AS}} a command line that has zero or more input file
590 names. The input files are read (from left file name to right). A
591 command line argument (in any position) that has no special meaning
592 is taken to be an input file name.
594 If you give @code{@value{AS}} no file names it attempts to read one input file
595 from the @code{@value{AS}} standard input, which is normally your terminal. You
596 may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program
599 Use @samp{--} if you need to explicitly name the standard input file
600 in your command line.
602 If the source is empty, @code{@value{AS}} produces a small, empty object
605 @subheading Filenames and Line-numbers
607 @cindex input file linenumbers
608 @cindex line numbers, in input files
609 There are two ways of locating a line in the input file (or files) and
610 either may be used in reporting error messages. One way refers to a line
611 number in a physical file; the other refers to a line number in a
612 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
614 @dfn{Physical files} are those files named in the command line given
615 to @code{@value{AS}}.
617 @dfn{Logical files} are simply names declared explicitly by assembler
618 directives; they bear no relation to physical files. Logical file names
619 help error messages reflect the original source file, when @code{@value{AS}}
620 source is itself synthesized from other files.
621 @xref{App-File,,@code{.app-file}}.
624 @section Output (Object) File
630 Every time you run @code{@value{AS}} it produces an output file, which is
631 your assembly language program translated into numbers. This file
632 is the object file. Its default name is
640 @code{b.out} when @code{@value{AS}} is configured for the Intel 80960.
642 You can give it another name by using the @code{-o} option. Conventionally,
643 object file names end with @file{.o}. The default name is used for historical
644 reasons: older assemblers were capable of assembling self-contained programs
645 directly into a runnable program. (For some formats, this isn't currently
646 possible, but it can be done for the @code{a.out} format.)
650 The object file is meant for input to the linker @code{@value{LD}}. It contains
651 assembled program code, information to help @code{@value{LD}} integrate
652 the assembled program into a runnable file, and (optionally) symbolic
653 information for the debugger.
655 @c link above to some info file(s) like the description of a.out.
656 @c don't forget to describe GNU info as well as Unix lossage.
659 @section Error and Warning Messages
661 @cindex error messsages
662 @cindex warning messages
663 @cindex messages from @code{@value{AS}}
664 @code{@value{AS}} may write warnings and error messages to the standard error
665 file (usually your terminal). This should not happen when a compiler
666 runs @code{@value{AS}} automatically. Warnings report an assumption made so
667 that @code{@value{AS}} could keep assembling a flawed program; errors report a
668 grave problem that stops the assembly.
670 @cindex format of warning messages
671 Warning messages have the format
674 file_name:@b{NNN}:Warning Message Text
678 @cindex line numbers, in warnings/errors
679 (where @b{NNN} is a line number). If a logical file name has been given
680 (@pxref{App-File,,@code{.app-file}}) it is used for the filename,
681 otherwise the name of the current input file is used. If a logical line
684 (@pxref{Line,,@code{.line}})
688 (@pxref{Line,,@code{.line}})
691 (@pxref{Ln,,@code{.ln}})
694 then it is used to calculate the number printed,
695 otherwise the actual line in the current source file is printed. The
696 message text is intended to be self explanatory (in the grand Unix
699 @cindex format of error messages
700 Error messages have the format
702 file_name:@b{NNN}:FATAL:Error Message Text
704 The file name and line number are derived as for warning
705 messages. The actual message text may be rather less explanatory
706 because many of them aren't supposed to happen.
709 @chapter Command-Line Options
711 @cindex options, all versions of @code{@value{AS}}
712 This chapter describes command-line options available in @emph{all}
713 versions of the GNU assembler; @pxref{Machine Dependencies}, for options specific
715 to the @value{TARGET}.
718 to particular machine architectures.
721 If you are invoking @code{@value{AS}} via the GNU C compiler (version 2), you
722 can use the @samp{-Wa} option to pass arguments through to the
723 assembler. The assembler arguments must be separated from each other
724 (and the @samp{-Wa}) by commas. For example:
727 gcc -c -g -O -Wa,-alh,-L file.c
731 emits a listing to standard output with high-level
734 Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
735 command-line options are automatically passed to the assembler by the compiler.
736 (You can call the GNU compiler driver with the @samp{-v} option to see
737 precisely what options it passes to each compilation pass, including the
741 * a:: -a[dhlns] enable listings
742 * D:: -D for compatibility
743 * f:: -f to work faster
744 * I:: -I for .include search path
745 @ifclear DIFF-TBL-KLUGE
746 * K:: -K for compatibility
748 @ifset DIFF-TBL-KLUGE
749 * K:: -K for difference tables
752 * L:: -L to retain local labels
753 * o:: -o to name the object file
754 * R:: -R to join data and text sections
755 * statistics:: --statistics to see statistics about assembly
756 * v:: -v to announce version
757 * W:: -W to suppress warnings
758 * Z:: -Z to make object file even after errors
762 @section Enable Listings: @code{-a[dhlns]}
770 @cindex listings, enabling
771 @cindex assembly listings, enabling
773 These options enable listing output from the assembler. By itself,
774 @samp{-a} requests high-level, assembly, and symbols listing.
775 Other letters may be used to select specific options for the list:
776 @samp{-ah} requests a high-level language listing,
777 @samp{-al} requests an output-program assembly listing, and
778 @samp{-as} requests a symbol table listing.
779 High-level listings require that a compiler debugging option like
780 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
783 The @samp{-ad} option may be used to omit debugging directives from the
786 Once you have specified one of these options, you can further control
787 listing output and its appearance using the directives @code{.list},
788 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
790 The @samp{-an} option turns off all forms processing.
791 If you do not request listing output with one of the @samp{-a} options, the
792 listing-control directives have no effect.
794 The letters after @samp{-a} may be combined into one option,
795 @emph{e.g.}, @samp{-aln}.
801 This option has no effect whatsoever, but it is accepted to make it more
802 likely that scripts written for other assemblers also work with
806 @section Work Faster: @code{-f}
809 @cindex trusted compiler
810 @cindex faster processing (@code{-f})
811 @samp{-f} should only be used when assembling programs written by a
812 (trusted) compiler. @samp{-f} stops the assembler from doing whitespace
813 and comment preprocessing on
814 the input file(s) before assembling them. @xref{Preprocessing,
818 @emph{Warning:} if you use @samp{-f} when the files actually need to be
819 preprocessed (if they contain comments, for example), @code{@value{AS}} does
824 @section @code{.include} search path: @code{-I} @var{path}
826 @kindex -I @var{path}
827 @cindex paths for @code{.include}
828 @cindex search path for @code{.include}
829 @cindex @code{include} directive search path
830 Use this option to add a @var{path} to the list of directories
831 @code{@value{AS}} searches for files specified in @code{.include}
832 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
833 many times as necessary to include a variety of paths. The current
834 working directory is always searched first; after that, @code{@value{AS}}
835 searches any @samp{-I} directories in the same order as they were
836 specified (left to right) on the command line.
839 @section Difference Tables: @code{-K}
842 @ifclear DIFF-TBL-KLUGE
843 On the @value{TARGET} family, this option is allowed, but has no effect. It is
844 permitted for compatibility with the GNU assembler on other platforms,
845 where it can be used to warn when the assembler alters the machine code
846 generated for @samp{.word} directives in difference tables. The @value{TARGET}
847 family does not have the addressing limitations that sometimes lead to this
848 alteration on other platforms.
851 @ifset DIFF-TBL-KLUGE
852 @cindex difference tables, warning
853 @cindex warning for altered difference tables
854 @code{@value{AS}} sometimes alters the code emitted for directives of the form
855 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
856 You can use the @samp{-K} option if you want a warning issued when this
861 @section Include Local Labels: @code{-L}
864 @cindex local labels, retaining in output
865 Labels beginning with @samp{L} (upper case only) are called @dfn{local
866 labels}. @xref{Symbol Names}. Normally you do not see such labels when
867 debugging, because they are intended for the use of programs (like
868 compilers) that compose assembler programs, not for your notice.
869 Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not
870 normally debug with them.
872 This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols
873 in the object file. Usually if you do this you also tell the linker
874 @code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
876 By default, a local label is any label beginning with @samp{L}, but each
877 target is allowed to redefine the local label prefix.
879 On the HPPA local labels begin with @samp{L$}.
883 @section Name the Object File: @code{-o}
886 @cindex naming object file
887 @cindex object file name
888 There is always one object file output when you run @code{@value{AS}}. By
889 default it has the name
892 @file{a.out} (or @file{b.out}, for Intel 960 targets only).
906 You use this option (which takes exactly one filename) to give the
907 object file a different name.
909 Whatever the object file is called, @code{@value{AS}} overwrites any
910 existing file of the same name.
913 @section Join Data and Text Sections: @code{-R}
916 @cindex data and text sections, joining
917 @cindex text and data sections, joining
918 @cindex joining text and data sections
919 @cindex merging text and data sections
920 @code{-R} tells @code{@value{AS}} to write the object file as if all
921 data-section data lives in the text section. This is only done at
922 the very last moment: your binary data are the same, but data
923 section parts are relocated differently. The data section part of
924 your object file is zero bytes long because all its bytes are
925 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
927 When you specify @code{-R} it would be possible to generate shorter
928 address displacements (because we do not have to cross between text and
929 data section). We refrain from doing this simply for compatibility with
930 older versions of @code{@value{AS}}. In future, @code{-R} may work this way.
933 When @code{@value{AS}} is configured for COFF output,
934 this option is only useful if you use sections named @samp{.text} and
939 @code{-R} is not supported for any of the HPPA targets. Using
940 @code{-R} generates a warning from @code{@value{AS}}.
944 @section Display Assembly Statistics: @code{--statistics}
947 @cindex statistics, about assembly
948 @cindex time, total for assembly
949 @cindex space used, maximum for assembly
950 Use @samp{--statistics} to display two statistics about the resources used by
951 @code{@value{AS}}: the maximum amount of space allocated during the assembly
952 (in bytes), and the total execution time taken for the assembly (in @sc{cpu}
956 @section Announce Version: @code{-v}
960 @cindex @code{@value{AS}} version
961 @cindex version of @code{@value{AS}}
962 You can find out what version of as is running by including the
963 option @samp{-v} (which you can also spell as @samp{-version}) on the
967 @section Suppress Warnings: @code{-W}
970 @cindex suppressing warnings
971 @cindex warnings, suppressing
972 @code{@value{AS}} should never give a warning or error message when
973 assembling compiler output. But programs written by people often
974 cause @code{@value{AS}} to give a warning that a particular assumption was
975 made. All such warnings are directed to the standard error file.
976 If you use this option, no warnings are issued. This option only
977 affects the warning messages: it does not change any particular of how
978 @code{@value{AS}} assembles your file. Errors, which stop the assembly, are
982 @section Generate Object File in Spite of Errors: @code{-Z}
983 @cindex object file, after errors
984 @cindex errors, continuing after
985 After an error message, @code{@value{AS}} normally produces no output. If for
986 some reason you are interested in object file output even after
987 @code{@value{AS}} gives an error message on your program, use the @samp{-Z}
988 option. If there are any errors, @code{@value{AS}} continues anyways, and
989 writes an object file after a final warning message of the form @samp{@var{n}
990 errors, @var{m} warnings, generating bad object file.}
995 @cindex machine-independent syntax
996 @cindex syntax, machine-independent
997 This chapter describes the machine-independent syntax allowed in a
998 source file. @code{@value{AS}} syntax is similar to what many other
999 assemblers use; it is inspired by the BSD 4.2
1004 assembler, except that @code{@value{AS}} does not assemble Vax bit-fields.
1008 * Preprocessing:: Preprocessing
1009 * Whitespace:: Whitespace
1010 * Comments:: Comments
1011 * Symbol Intro:: Symbols
1012 * Statements:: Statements
1013 * Constants:: Constants
1017 @section Preprocessing
1019 @cindex preprocessing
1020 The @code{@value{AS}} internal preprocessor:
1022 @cindex whitespace, removed by preprocessor
1024 adjusts and removes extra whitespace. It leaves one space or tab before
1025 the keywords on a line, and turns any other whitespace on the line into
1028 @cindex comments, removed by preprocessor
1030 removes all comments, replacing them with a single space, or an
1031 appropriate number of newlines.
1033 @cindex constants, converted by preprocessor
1035 converts character constants into the appropriate numeric values.
1038 Note that it does not do macro processing, include file handling, or
1039 anything else you may get from your C compiler's preprocessor. You can
1040 do include file processing with the @code{.include} directive
1041 (@pxref{Include,,@code{.include}}). Other ``CPP'' style preprocessing
1042 can be done with the @sc{GNU} C compiler, by giving the input file a
1043 @samp{.S} suffix; see the compiler documentation for details.
1045 Excess whitespace, comments, and character constants
1046 cannot be used in the portions of the input text that are not
1049 @cindex turning preprocessing on and off
1050 @cindex preprocessing, turning on and off
1053 If the first line of an input file is @code{#NO_APP} or if you use the
1054 @samp{-f} option, whitespace and comments are not removed from the input file.
1055 Within an input file, you can ask for whitespace and comment removal in
1056 specific portions of the by putting a line that says @code{#APP} before the
1057 text that may contain whitespace or comments, and putting a line that says
1058 @code{#NO_APP} after this text. This feature is mainly intend to support
1059 @code{asm} statements in compilers whose output is otherwise free of comments
1066 @dfn{Whitespace} is one or more blanks or tabs, in any order.
1067 Whitespace is used to separate symbols, and to make programs neater for
1068 people to read. Unless within character constants
1069 (@pxref{Characters,,Character Constants}), any whitespace means the same
1070 as exactly one space.
1076 There are two ways of rendering comments to @code{@value{AS}}. In both
1077 cases the comment is equivalent to one space.
1079 Anything from @samp{/*} through the next @samp{*/} is a comment.
1080 This means you may not nest these comments.
1084 The only way to include a newline ('\n') in a comment
1085 is to use this sort of comment.
1088 /* This sort of comment does not nest. */
1091 @cindex line comment character
1092 Anything from the @dfn{line comment} character to the next newline
1093 is considered a comment and is ignored. The line comment character is
1095 @samp{#} on the Vax;
1098 @samp{#} on the i960;
1101 @samp{!} on the SPARC;
1104 @samp{|} on the 680x0;
1107 @samp{;} for the AMD 29K family;
1110 @samp{;} for the H8/300 family;
1113 @samp{!} for the H8/500 family;
1116 @samp{;} for the HPPA;
1119 @samp{!} for the Hitachi SH;
1122 @samp{!} for the Z8000;
1124 see @ref{Machine Dependencies}. @refill
1125 @c FIXME What about i386, m88k, i860?
1128 On some machines there are two different line comment characters. One
1129 character only begins a comment if it is the first non-whitespace character on
1130 a line, while the other always begins a comment.
1134 @cindex lines starting with @code{#}
1135 @cindex logical line numbers
1136 To be compatible with past assemblers, a special interpretation is given to
1137 lines that begin with @samp{#}. Following the @samp{#} should be an absolute
1138 expression (@pxref{Expressions}): the logical line number of the @emph{next}
1139 line. Then a string (@xref{Strings}.) is allowed: if present it is a new
1140 logical file name. The rest of the line, if any, should be whitespace.
1142 If the first non-whitespace characters on the line are not numeric,
1143 the line is ignored. (Just like a comment.)
1145 # This is an ordinary comment.
1146 # 42-6 "new_file_name" # New logical file name
1147 # This is logical line # 36.
1149 This feature is deprecated, and may disappear from future versions
1150 of @code{@value{AS}}.
1155 @cindex characters used in symbols
1156 @ifclear SPECIAL-SYMS
1157 A @dfn{symbol} is one or more characters chosen from the set of all
1158 letters (both upper and lower case), digits and the three characters
1164 A @dfn{symbol} is one or more characters chosen from the set of all
1165 letters (both upper and lower case), digits and the three characters
1166 @samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in
1172 On most machines, you can also use @code{$} in symbol names; exceptions
1173 are noted in @ref{Machine Dependencies}.
1175 No symbol may begin with a digit. Case is significant.
1176 There is no length limit: all characters are significant. Symbols are
1177 delimited by characters not in that set, or by the beginning of a file
1178 (since the source program must end with a newline, the end of a file is
1179 not a possible symbol delimiter). @xref{Symbols}.
1180 @cindex length of symbols
1185 @cindex statements, structure of
1186 @cindex line separator character
1187 @cindex statement separator character
1189 @ifclear abnormal-separator
1190 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
1191 semicolon (@samp{;}). The newline or semicolon is considered part of
1192 the preceding statement. Newlines and semicolons within character
1193 constants are an exception: they do not end statements.
1195 @ifset abnormal-separator
1197 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
1198 sign (@samp{@@}). The newline or at sign is considered part of the
1199 preceding statement. Newlines and at signs within character constants
1200 are an exception: they do not end statements.
1203 A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation
1204 point (@samp{!}). The newline or exclamation point is considered part of the
1205 preceding statement. Newlines and exclamation points within character
1206 constants are an exception: they do not end statements.
1209 A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
1210 H8/300) a dollar sign (@samp{$}); or (for the
1213 (@samp{;}). The newline or separator character is considered part of
1214 the preceding statement. Newlines and separators within character
1215 constants are an exception: they do not end statements.
1220 A @dfn{statement} ends at a newline character (@samp{\n}) or line
1221 separator character. (The line separator is usually @samp{;}, unless
1222 this conflicts with the comment character; @pxref{Machine Dependencies}.) The
1223 newline or separator character is considered part of the preceding
1224 statement. Newlines and separators within character constants are an
1225 exception: they do not end statements.
1228 @cindex newline, required at file end
1229 @cindex EOF, newline must precede
1230 It is an error to end any statement with end-of-file: the last
1231 character of any input file should be a newline.@refill
1233 @cindex continuing statements
1234 @cindex multi-line statements
1235 @cindex statement on multiple lines
1236 You may write a statement on more than one line if you put a
1237 backslash (@kbd{\}) immediately in front of any newlines within the
1238 statement. When @code{@value{AS}} reads a backslashed newline both
1239 characters are ignored. You can even put backslashed newlines in
1240 the middle of symbol names without changing the meaning of your
1243 An empty statement is allowed, and may include whitespace. It is ignored.
1245 @cindex instructions and directives
1246 @cindex directives and instructions
1247 @c "key symbol" is not used elsewhere in the document; seems pedantic to
1248 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
1250 A statement begins with zero or more labels, optionally followed by a
1251 key symbol which determines what kind of statement it is. The key
1252 symbol determines the syntax of the rest of the statement. If the
1253 symbol begins with a dot @samp{.} then the statement is an assembler
1254 directive: typically valid for any computer. If the symbol begins with
1255 a letter the statement is an assembly language @dfn{instruction}: it
1256 assembles into a machine language instruction.
1258 Different versions of @code{@value{AS}} for different computers
1259 recognize different instructions. In fact, the same symbol may
1260 represent a different instruction in a different computer's assembly
1264 @cindex @code{:} (label)
1265 @cindex label (@code{:})
1266 A label is a symbol immediately followed by a colon (@code{:}).
1267 Whitespace before a label or after a colon is permitted, but you may not
1268 have whitespace between a label's symbol and its colon. @xref{Labels}.
1271 For HPPA targets, labels need not be immediately followed by a colon, but
1272 the definition of a label must begin in column zero. This also implies that
1273 only one label may be defined on each line.
1277 label: .directive followed by something
1278 another_label: # This is an empty statement.
1279 instruction operand_1, operand_2, @dots{}
1286 A constant is a number, written so that its value is known by
1287 inspection, without knowing any context. Like this:
1290 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
1291 .ascii "Ring the bell\7" # A string constant.
1292 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
1293 .float 0f-314159265358979323846264338327\
1294 95028841971.693993751E-40 # - pi, a flonum.
1299 * Characters:: Character Constants
1300 * Numbers:: Number Constants
1304 @subsection Character Constants
1306 @cindex character constants
1307 @cindex constants, character
1308 There are two kinds of character constants. A @dfn{character} stands
1309 for one character in one byte and its value may be used in
1310 numeric expressions. String constants (properly called string
1311 @emph{literals}) are potentially many bytes and their values may not be
1312 used in arithmetic expressions.
1316 * Chars:: Characters
1320 @subsubsection Strings
1322 @cindex string constants
1323 @cindex constants, string
1324 A @dfn{string} is written between double-quotes. It may contain
1325 double-quotes or null characters. The way to get special characters
1326 into a string is to @dfn{escape} these characters: precede them with
1327 a backslash @samp{\} character. For example @samp{\\} represents
1328 one backslash: the first @code{\} is an escape which tells
1329 @code{@value{AS}} to interpret the second character literally as a backslash
1330 (which prevents @code{@value{AS}} from recognizing the second @code{\} as an
1331 escape character). The complete list of escapes follows.
1333 @cindex escape codes, character
1334 @cindex character escape codes
1337 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1340 @cindex @code{\b} (backspace character)
1341 @cindex backspace (@code{\b})
1342 Mnemonic for backspace; for ASCII this is octal code 010.
1345 @c Mnemonic for EOText; for ASCII this is octal code 004.
1348 @cindex @code{\f} (formfeed character)
1349 @cindex formfeed (@code{\f})
1350 Mnemonic for FormFeed; for ASCII this is octal code 014.
1353 @cindex @code{\n} (newline character)
1354 @cindex newline (@code{\n})
1355 Mnemonic for newline; for ASCII this is octal code 012.
1358 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1361 @cindex @code{\r} (carriage return character)
1362 @cindex carriage return (@code{\r})
1363 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1366 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1367 @c other assemblers.
1370 @cindex @code{\t} (tab)
1371 @cindex tab (@code{\t})
1372 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1375 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1376 @c @item \x @var{digit} @var{digit} @var{digit}
1377 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1379 @item \ @var{digit} @var{digit} @var{digit}
1380 @cindex @code{\@var{ddd}} (octal character code)
1381 @cindex octal character code (@code{\@var{ddd}})
1382 An octal character code. The numeric code is 3 octal digits.
1383 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1384 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1387 @item \@code{x} @var{hex-digit} @var{hex-digit}
1388 @cindex @code{\@var{xdd}} (hex character code)
1389 @cindex hex character code (@code{\@var{xdd}})
1390 A hex character code. The numeric code is 2 hexadecimal digits. Either
1391 upper or lower case @code{x} works.
1395 @cindex @code{\\} (@samp{\} character)
1396 @cindex backslash (@code{\\})
1397 Represents one @samp{\} character.
1400 @c Represents one @samp{'} (accent acute) character.
1401 @c This is needed in single character literals
1402 @c (@xref{Characters,,Character Constants}.) to represent
1406 @cindex @code{\"} (doublequote character)
1407 @cindex doublequote (@code{\"})
1408 Represents one @samp{"} character. Needed in strings to represent
1409 this character, because an unescaped @samp{"} would end the string.
1411 @item \ @var{anything-else}
1412 Any other character when escaped by @kbd{\} gives a warning, but
1413 assemble as if the @samp{\} was not present. The idea is that if
1414 you used an escape sequence you clearly didn't want the literal
1415 interpretation of the following character. However @code{@value{AS}} has no
1416 other interpretation, so @code{@value{AS}} knows it is giving you the wrong
1417 code and warns you of the fact.
1420 Which characters are escapable, and what those escapes represent,
1421 varies widely among assemblers. The current set is what we think
1422 the BSD 4.2 assembler recognizes, and is a subset of what most C
1423 compilers recognize. If you are in doubt, do not use an escape
1427 @subsubsection Characters
1429 @cindex single character constant
1430 @cindex character, single
1431 @cindex constant, single character
1432 A single character may be written as a single quote immediately
1433 followed by that character. The same escapes apply to characters as
1434 to strings. So if you want to write the character backslash, you
1435 must write @kbd{'\\} where the first @code{\} escapes the second
1436 @code{\}. As you can see, the quote is an acute accent, not a
1437 grave accent. A newline
1439 @ifclear abnormal-separator
1440 (or semicolon @samp{;})
1442 @ifset abnormal-separator
1444 (or at sign @samp{@@})
1447 (or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
1453 immediately following an acute accent is taken as a literal character
1454 and does not count as the end of a statement. The value of a character
1455 constant in a numeric expression is the machine's byte-wide code for
1456 that character. @code{@value{AS}} assumes your character code is ASCII:
1457 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1460 @subsection Number Constants
1462 @cindex constants, number
1463 @cindex number constants
1464 @code{@value{AS}} distinguishes three kinds of numbers according to how they
1465 are stored in the target machine. @emph{Integers} are numbers that
1466 would fit into an @code{int} in the C language. @emph{Bignums} are
1467 integers, but they are stored in more than 32 bits. @emph{Flonums}
1468 are floating point numbers, described below.
1471 * Integers:: Integers
1476 * Bit Fields:: Bit Fields
1482 @subsubsection Integers
1484 @cindex constants, integer
1486 @cindex binary integers
1487 @cindex integers, binary
1488 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1489 the binary digits @samp{01}.
1491 @cindex octal integers
1492 @cindex integers, octal
1493 An octal integer is @samp{0} followed by zero or more of the octal
1494 digits (@samp{01234567}).
1496 @cindex decimal integers
1497 @cindex integers, decimal
1498 A decimal integer starts with a non-zero digit followed by zero or
1499 more digits (@samp{0123456789}).
1501 @cindex hexadecimal integers
1502 @cindex integers, hexadecimal
1503 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1504 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1506 Integers have the usual values. To denote a negative integer, use
1507 the prefix operator @samp{-} discussed under expressions
1508 (@pxref{Prefix Ops,,Prefix Operators}).
1511 @subsubsection Bignums
1514 @cindex constants, bignum
1515 A @dfn{bignum} has the same syntax and semantics as an integer
1516 except that the number (or its negative) takes more than 32 bits to
1517 represent in binary. The distinction is made because in some places
1518 integers are permitted while bignums are not.
1521 @subsubsection Flonums
1523 @cindex floating point numbers
1524 @cindex constants, floating point
1526 @cindex precision, floating point
1527 A @dfn{flonum} represents a floating point number. The translation is
1528 indirect: a decimal floating point number from the text is converted by
1529 @code{@value{AS}} to a generic binary floating point number of more than
1530 sufficient precision. This generic floating point number is converted
1531 to a particular computer's floating point format (or formats) by a
1532 portion of @code{@value{AS}} specialized to that computer.
1534 A flonum is written by writing (in order)
1539 (@samp{0} is optional on the HPPA.)
1543 A letter, to tell @code{@value{AS}} the rest of the number is a flonum.
1545 @kbd{e} is recommended. Case is not important.
1547 @c FIXME: verify if flonum syntax really this vague for most cases
1548 (Any otherwise illegal letter works here, but that might be changed. Vax BSD
1549 4.2 assembler seems to allow any of @samp{defghDEFGH}.)
1552 On the H8/300, H8/500,
1554 and AMD 29K architectures, the letter must be
1555 one of the letters @samp{DFPRSX} (in upper or lower case).
1557 On the Intel 960 architecture, the letter must be
1558 one of the letters @samp{DFT} (in upper or lower case).
1560 On the HPPA architecture, the letter must be @samp{E} (upper case only).
1564 One of the letters @samp{DFPRSX} (in upper or lower case).
1567 One of the letters @samp{DFPRSX} (in upper or lower case).
1570 One of the letters @samp{DFT} (in upper or lower case).
1573 The letter @samp{E} (upper case only).
1578 An optional sign: either @samp{+} or @samp{-}.
1581 An optional @dfn{integer part}: zero or more decimal digits.
1584 An optional @dfn{fractional part}: @samp{.} followed by zero
1585 or more decimal digits.
1588 An optional exponent, consisting of:
1592 An @samp{E} or @samp{e}.
1593 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1594 @c principle this can perfectly well be different on different targets.
1596 Optional sign: either @samp{+} or @samp{-}.
1598 One or more decimal digits.
1603 At least one of the integer part or the fractional part must be
1604 present. The floating point number has the usual base-10 value.
1606 @code{@value{AS}} does all processing using integers. Flonums are computed
1607 independently of any floating point hardware in the computer running
1612 @c Bit fields are written as a general facility but are also controlled
1613 @c by a conditional-compilation flag---which is as of now (21mar91)
1614 @c turned on only by the i960 config of GAS.
1616 @subsubsection Bit Fields
1619 @cindex constants, bit field
1620 You can also define numeric constants as @dfn{bit fields}.
1621 specify two numbers separated by a colon---
1623 @var{mask}:@var{value}
1626 @code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
1629 The resulting number is then packed
1631 @c this conditional paren in case bit fields turned on elsewhere than 960
1632 (in host-dependent byte order)
1634 into a field whose width depends on which assembler directive has the
1635 bit-field as its argument. Overflow (a result from the bitwise and
1636 requiring more binary digits to represent) is not an error; instead,
1637 more constants are generated, of the specified width, beginning with the
1638 least significant digits.@refill
1640 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1641 @code{.short}, and @code{.word} accept bit-field arguments.
1646 @chapter Sections and Relocation
1651 * Secs Background:: Background
1652 * Ld Sections:: @value{LD} Sections
1653 * As Sections:: @value{AS} Internal Sections
1654 * Sub-Sections:: Sub-Sections
1658 @node Secs Background
1661 Roughly, a section is a range of addresses, with no gaps; all data
1662 ``in'' those addresses is treated the same for some particular purpose.
1663 For example there may be a ``read only'' section.
1665 @cindex linker, and assembler
1666 @cindex assembler, and linker
1667 The linker @code{@value{LD}} reads many object files (partial programs) and
1668 combines their contents to form a runnable program. When @code{@value{AS}}
1669 emits an object file, the partial program is assumed to start at address 0.
1670 @code{@value{LD}} assigns the final addresses for the partial program, so that
1671 different partial programs do not overlap. This is actually an
1672 oversimplification, but it suffices to explain how @code{@value{AS}} uses
1675 @code{@value{LD}} moves blocks of bytes of your program to their run-time
1676 addresses. These blocks slide to their run-time addresses as rigid
1677 units; their length does not change and neither does the order of bytes
1678 within them. Such a rigid unit is called a @emph{section}. Assigning
1679 run-time addresses to sections is called @dfn{relocation}. It includes
1680 the task of adjusting mentions of object-file addresses so they refer to
1681 the proper run-time addresses.
1683 For the H8/300 and H8/500,
1684 and for the Hitachi SH,
1685 @code{@value{AS}} pads sections if needed to
1686 ensure they end on a word (sixteen bit) boundary.
1689 @cindex standard @code{@value{AS}} sections
1690 An object file written by @code{@value{AS}} has at least three sections, any
1691 of which may be empty. These are named @dfn{text}, @dfn{data} and
1696 When it generates COFF output,
1698 @code{@value{AS}} can also generate whatever other named sections you specify
1699 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1700 If you do not use any directives that place output in the @samp{.text}
1701 or @samp{.data} sections, these sections still exist, but are empty.
1706 When @code{@value{AS}} generates SOM or ELF output for the HPPA,
1708 @code{@value{AS}} can also generate whatever other named sections you
1709 specify using the @samp{.space} and @samp{.subspace} directives. See
1710 @cite{HP9000 Series 800 Assembly Language Reference Manual}
1711 (HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
1712 assembler directives.
1715 Additionally, @code{@value{AS}} uses different names for the standard
1716 text, data, and bss sections when generating SOM output. Program text
1717 is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
1718 BSS into @samp{$BSS$}.
1722 Within the object file, the text section starts at address @code{0}, the
1723 data section follows, and the bss section follows the data section.
1726 When generating either SOM or ELF output files on the HPPA, the text
1727 section starts at address @code{0}, the data section at address
1728 @code{0x4000000}, and the bss section follows the data section.
1731 To let @code{@value{LD}} know which data changes when the sections are
1732 relocated, and how to change that data, @code{@value{AS}} also writes to the
1733 object file details of the relocation needed. To perform relocation
1734 @code{@value{LD}} must know, each time an address in the object
1738 Where in the object file is the beginning of this reference to
1741 How long (in bytes) is this reference?
1743 Which section does the address refer to? What is the numeric value of
1745 (@var{address}) @minus{} (@var{start-address of section})?
1748 Is the reference to an address ``Program-Counter relative''?
1751 @cindex addresses, format of
1752 @cindex section-relative addressing
1753 In fact, every address @code{@value{AS}} ever uses is expressed as
1755 (@var{section}) + (@var{offset into section})
1758 Further, most expressions @code{@value{AS}} computes have this section-relative
1761 (For some object formats, such as SOM for the HPPA, some expressions are
1762 symbol-relative instead.)
1764 @dfn{Absolute expression} means an expression with section
1765 ``absolute'' (@pxref{Ld Sections}). A @dfn{pass1 expression} means
1766 an expression with section ``pass1'' (@pxref{As Sections,,@value{AS}
1767 Internal Sections}). In this manual we use the notation @{@var{secname}
1768 @var{N}@} to mean ``offset @var{N} into section @var{secname}''.
1770 Apart from text, data and bss sections you need to know about the
1771 @dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
1772 addresses in the absolute section remain unchanged. For example, address
1773 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
1774 @code{@value{LD}}. Although the linker never arranges two partial programs'
1775 data sections with overlapping addresses after linking, @emph{by definition}
1776 their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one
1777 part of a program is always the same address when the program is running as
1778 address @code{@{absolute@ 239@}} in any other part of the program.
1780 The idea of sections is extended to the @dfn{undefined} section. Any
1781 address whose section is unknown at assembly time is by definition
1782 rendered @{undefined @var{U}@}---where @var{U} is filled in later.
1783 Since numbers are always defined, the only way to generate an undefined
1784 address is to mention an undefined symbol. A reference to a named
1785 common block would be such a symbol: its value is unknown at assembly
1786 time so it has section @emph{undefined}.
1788 By analogy the word @emph{section} is used to describe groups of sections in
1789 the linked program. @code{@value{LD}} puts all partial programs' text
1790 sections in contiguous addresses in the linked program. It is
1791 customary to refer to the @emph{text section} of a program, meaning all
1792 the addresses of all partial programs' text sections. Likewise for
1793 data and bss sections.
1795 Some sections are manipulated by @code{@value{LD}}; others are invented for
1796 use of @code{@value{AS}} and have no meaning except during assembly.
1799 @section @value{LD} Sections
1800 @code{@value{LD}} deals with just four kinds of sections, summarized below.
1805 @cindex named sections
1806 @cindex sections, named
1807 @item named sections
1810 @cindex text section
1811 @cindex data section
1815 These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as
1816 separate but equal sections. Anything you can say of one section is
1819 When the program is running, however, it is
1820 customary for the text section to be unalterable. The
1821 text section is often shared among processes: it contains
1822 instructions, constants and the like. The data section of a running
1823 program is usually alterable: for example, C variables would be stored
1824 in the data section.
1829 This section contains zeroed bytes when your program begins running. It
1830 is used to hold unitialized variables or common storage. The length of
1831 each partial program's bss section is important, but because it starts
1832 out containing zeroed bytes there is no need to store explicit zero
1833 bytes in the object file. The bss section was invented to eliminate
1834 those explicit zeros from object files.
1836 @cindex absolute section
1837 @item absolute section
1838 Address 0 of this section is always ``relocated'' to runtime address 0.
1839 This is useful if you want to refer to an address that @code{@value{LD}} must
1840 not change when relocating. In this sense we speak of absolute
1841 addresses being ``unrelocatable'': they do not change during relocation.
1843 @cindex undefined section
1844 @item undefined section
1845 This ``section'' is a catch-all for address references to objects not in
1846 the preceding sections.
1847 @c FIXME: ref to some other doc on obj-file formats could go here.
1850 @cindex relocation example
1851 An idealized example of three relocatable sections follows.
1853 The example uses the traditional section names @samp{.text} and @samp{.data}.
1855 Memory addresses are on the horizontal axis.
1859 @c END TEXI2ROFF-KILL
1862 partial program # 1: |ttttt|dddd|00|
1869 partial program # 2: |TTT|DDD|000|
1872 +--+---+-----+--+----+---+-----+~~
1873 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1874 +--+---+-----+--+----+---+-----+~~
1876 addresses: 0 @dots{}
1880 @c FIXME make sure no page breaks inside figure!!
1883 \line{\it Partial program \#1: \hfil}
1884 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1885 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1887 \line{\it Partial program \#2: \hfil}
1888 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1889 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1891 \line{\it linked program: \hfil}
1892 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1893 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1894 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1895 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1897 \line{\it addresses: \hfil}
1901 @c END TEXI2ROFF-KILL
1904 @section @value{AS} Internal Sections
1906 @cindex internal @code{@value{AS}} sections
1907 @cindex sections in messages, internal
1908 These sections are meant only for the internal use of @code{@value{AS}}. They
1909 have no meaning at run-time. You do not really need to know about these
1910 sections for most purposes; but they can be mentioned in @code{@value{AS}}
1911 warning messages, so it might be helpful to have an idea of their
1912 meanings to @code{@value{AS}}. These sections are used to permit the
1913 value of every expression in your assembly language program to be a
1914 section-relative address.
1917 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
1918 @cindex assembler internal logic error
1919 An internal assembler logic error has been found. This means there is a
1920 bug in the assembler.
1923 @cindex expr (internal section)
1924 The assembler stores complex expression internally as combinations of
1925 symbols. When it needs to represent an expression as a symbol, it puts
1926 it in the expr section.
1928 @c FIXME item transfer[t] vector preload
1929 @c FIXME item transfer[t] vector postload
1930 @c FIXME item register
1934 @section Sub-Sections
1936 @cindex numbered subsections
1937 @cindex grouping data
1943 fall into two sections: text and data.
1945 You may have separate groups of
1947 data in named sections
1951 data in named sections
1957 that you want to end up near to each other in the object file, even though they
1958 are not contiguous in the assembler source. @code{@value{AS}} allows you to
1959 use @dfn{subsections} for this purpose. Within each section, there can be
1960 numbered subsections with values from 0 to 8192. Objects assembled into the
1961 same subsection go into the object file together with other objects in the same
1962 subsection. For example, a compiler might want to store constants in the text
1963 section, but might not want to have them interspersed with the program being
1964 assembled. In this case, the compiler could issue a @samp{.text 0} before each
1965 section of code being output, and a @samp{.text 1} before each group of
1966 constants being output.
1968 Subsections are optional. If you do not use subsections, everything
1969 goes in subsection number zero.
1972 Each subsection is zero-padded up to a multiple of four bytes.
1973 (Subsections may be padded a different amount on different flavors
1974 of @code{@value{AS}}.)
1978 On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
1979 boundary (two bytes).
1980 The same is true on the Hitachi SH.
1983 @c FIXME section padding (alignment)?
1984 @c Rich Pixley says padding here depends on target obj code format; that
1985 @c doesn't seem particularly useful to say without further elaboration,
1986 @c so for now I say nothing about it. If this is a generic BFD issue,
1987 @c these paragraphs might need to vanish from this manual, and be
1988 @c discussed in BFD chapter of binutils (or some such).
1991 On the AMD 29K family, no particular padding is added to section or
1992 subsection sizes; @value{AS} forces no alignment on this platform.
1996 Subsections appear in your object file in numeric order, lowest numbered
1997 to highest. (All this to be compatible with other people's assemblers.)
1998 The object file contains no representation of subsections; @code{@value{LD}} and
1999 other programs that manipulate object files see no trace of them.
2000 They just see all your text subsections as a text section, and all your
2001 data subsections as a data section.
2003 To specify which subsection you want subsequent statements assembled
2004 into, use a numeric argument to specify it, in a @samp{.text
2005 @var{expression}} or a @samp{.data @var{expression}} statement.
2008 When generating COFF output, you
2013 can also use an extra subsection
2014 argument with arbitrary named sections: @samp{.section @var{name},
2017 @var{Expression} should be an absolute expression.
2018 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
2019 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
2020 begins in @code{text 0}. For instance:
2022 .text 0 # The default subsection is text 0 anyway.
2023 .ascii "This lives in the first text subsection. *"
2025 .ascii "But this lives in the second text subsection."
2027 .ascii "This lives in the data section,"
2028 .ascii "in the first data subsection."
2030 .ascii "This lives in the first text section,"
2031 .ascii "immediately following the asterisk (*)."
2034 Each section has a @dfn{location counter} incremented by one for every byte
2035 assembled into that section. Because subsections are merely a convenience
2036 restricted to @code{@value{AS}} there is no concept of a subsection location
2037 counter. There is no way to directly manipulate a location counter---but the
2038 @code{.align} directive changes it, and any label definition captures its
2039 current value. The location counter of the section where statements are being
2040 assembled is said to be the @dfn{active} location counter.
2043 @section bss Section
2046 @cindex common variable storage
2047 The bss section is used for local common variable storage.
2048 You may allocate address space in the bss section, but you may
2049 not dictate data to load into it before your program executes. When
2050 your program starts running, all the contents of the bss
2051 section are zeroed bytes.
2053 Addresses in the bss section are allocated with special directives; you
2054 may not assemble anything directly into the bss section. Hence there
2055 are no bss subsections. @xref{Comm,,@code{.comm}},
2056 @pxref{Lcomm,,@code{.lcomm}}.
2062 Symbols are a central concept: the programmer uses symbols to name
2063 things, the linker uses symbols to link, and the debugger uses symbols
2067 @cindex debuggers, and symbol order
2068 @emph{Warning:} @code{@value{AS}} does not place symbols in the object file in
2069 the same order they were declared. This may break some debuggers.
2074 * Setting Symbols:: Giving Symbols Other Values
2075 * Symbol Names:: Symbol Names
2076 * Dot:: The Special Dot Symbol
2077 * Symbol Attributes:: Symbol Attributes
2084 A @dfn{label} is written as a symbol immediately followed by a colon
2085 @samp{:}. The symbol then represents the current value of the
2086 active location counter, and is, for example, a suitable instruction
2087 operand. You are warned if you use the same symbol to represent two
2088 different locations: the first definition overrides any other
2092 On the HPPA, the usual form for a label need not be immediately followed by a
2093 colon, but instead must start in column zero. Only one label may be defined on
2094 a single line. To work around this, the HPPA version of @code{@value{AS}} also
2095 provides a special directive @code{.label} for defining labels more flexibly.
2098 @node Setting Symbols
2099 @section Giving Symbols Other Values
2101 @cindex assigning values to symbols
2102 @cindex symbol values, assigning
2103 A symbol can be given an arbitrary value by writing a symbol, followed
2104 by an equals sign @samp{=}, followed by an expression
2105 (@pxref{Expressions}). This is equivalent to using the @code{.set}
2106 directive. @xref{Set,,@code{.set}}.
2109 @section Symbol Names
2111 @cindex symbol names
2112 @cindex names, symbol
2113 @ifclear SPECIAL-SYMS
2114 Symbol names begin with a letter or with one of @samp{._}. On most
2115 machines, you can also use @code{$} in symbol names; exceptions are
2116 noted in @ref{Machine Dependencies}. That character may be followed by any
2117 string of digits, letters, dollar signs (unless otherwise noted in
2118 @ref{Machine Dependencies}), and underscores.
2121 For the AMD 29K family, @samp{?} is also allowed in the
2122 body of a symbol name, though not at its beginning.
2127 Symbol names begin with a letter or with one of @samp{._}. On the
2129 H8/500, you can also use @code{$} in symbol names. That character may
2130 be followed by any string of digits, letters, dollar signs (save on the
2131 H8/300), and underscores.
2135 Case of letters is significant: @code{foo} is a different symbol name
2138 Each symbol has exactly one name. Each name in an assembly language program
2139 refers to exactly one symbol. You may use that symbol name any number of times
2142 @subheading Local Symbol Names
2144 @cindex local symbol names
2145 @cindex symbol names, local
2146 @cindex temporary symbol names
2147 @cindex symbol names, temporary
2148 Local symbols help compilers and programmers use names temporarily.
2149 There are ten local symbol names, which are re-used throughout the
2150 program. You may refer to them using the names @samp{0} @samp{1}
2151 @dots{} @samp{9}. To define a local symbol, write a label of the form
2152 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
2153 recent previous definition of that symbol write @samp{@b{N}b}, using the
2154 same digit as when you defined the label. To refer to the next
2155 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
2156 a choice of 10 forward references. The @samp{b} stands for
2157 ``backwards'' and the @samp{f} stands for ``forwards''.
2159 Local symbols are not emitted by the current GNU C compiler.
2161 There is no restriction on how you can use these labels, but
2162 remember that at any point in the assembly you can refer to at most
2163 10 prior local labels and to at most 10 forward local labels.
2165 Local symbol names are only a notation device. They are immediately
2166 transformed into more conventional symbol names before the assembler
2167 uses them. The symbol names stored in the symbol table, appearing in
2168 error messages and optionally emitted to the object file have these
2173 All local labels begin with @samp{L}. Normally both @code{@value{AS}} and
2174 @code{@value{LD}} forget symbols that start with @samp{L}. These labels are
2175 used for symbols you are never intended to see. If you use the
2176 @samp{-L} option then @code{@value{AS}} retains these symbols in the
2177 object file. If you also instruct @code{@value{LD}} to retain these symbols,
2178 you may use them in debugging.
2181 If the label is written @samp{0:} then the digit is @samp{0}.
2182 If the label is written @samp{1:} then the digit is @samp{1}.
2183 And so on up through @samp{9:}.
2186 This unusual character is included so you do not accidentally invent
2187 a symbol of the same name. The character has ASCII value
2190 @item @emph{ordinal number}
2191 This is a serial number to keep the labels distinct. The first
2192 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
2193 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
2197 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
2198 @code{3:} is named @code{L3@ctrl{A}44}.
2201 @section The Special Dot Symbol
2203 @cindex dot (symbol)
2204 @cindex @code{.} (symbol)
2205 @cindex current address
2206 @cindex location counter
2207 The special symbol @samp{.} refers to the current address that
2208 @code{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
2209 .long .} defines @code{melvin} to contain its own address.
2210 Assigning a value to @code{.} is treated the same as a @code{.org}
2211 directive. Thus, the expression @samp{.=.+4} is the same as saying
2212 @ifclear no-space-dir
2221 @node Symbol Attributes
2222 @section Symbol Attributes
2224 @cindex symbol attributes
2225 @cindex attributes, symbol
2226 Every symbol has, as well as its name, the attributes ``Value'' and
2227 ``Type''. Depending on output format, symbols can also have auxiliary
2230 The detailed definitions are in @file{a.out.h}.
2233 If you use a symbol without defining it, @code{@value{AS}} assumes zero for
2234 all these attributes, and probably won't warn you. This makes the
2235 symbol an externally defined symbol, which is generally what you
2239 * Symbol Value:: Value
2240 * Symbol Type:: Type
2243 * a.out Symbols:: Symbol Attributes: @code{a.out}
2247 * a.out Symbols:: Symbol Attributes: @code{a.out}
2250 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
2255 * COFF Symbols:: Symbol Attributes for COFF
2258 * SOM Symbols:: Symbol Attributes for SOM
2265 @cindex value of a symbol
2266 @cindex symbol value
2267 The value of a symbol is (usually) 32 bits. For a symbol which labels a
2268 location in the text, data, bss or absolute sections the value is the
2269 number of addresses from the start of that section to the label.
2270 Naturally for text, data and bss sections the value of a symbol changes
2271 as @code{@value{LD}} changes section base addresses during linking. Absolute
2272 symbols' values do not change during linking: that is why they are
2275 The value of an undefined symbol is treated in a special way. If it is
2276 0 then the symbol is not defined in this assembler source file, and
2277 @code{@value{LD}} tries to determine its value from other files linked into the
2278 same program. You make this kind of symbol simply by mentioning a symbol
2279 name without defining it. A non-zero value represents a @code{.comm}
2280 common declaration. The value is how much common storage to reserve, in
2281 bytes (addresses). The symbol refers to the first address of the
2287 @cindex type of a symbol
2289 The type attribute of a symbol contains relocation (section)
2290 information, any flag settings indicating that a symbol is external, and
2291 (optionally), other information for linkers and debuggers. The exact
2292 format depends on the object-code output format in use.
2297 @c The following avoids a "widow" subsection title. @group would be
2298 @c better if it were available outside examples.
2301 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
2303 @cindex @code{b.out} symbol attributes
2304 @cindex symbol attributes, @code{b.out}
2305 These symbol attributes appear only when @code{@value{AS}} is configured for
2306 one of the Berkeley-descended object output formats---@code{a.out} or
2312 @subsection Symbol Attributes: @code{a.out}
2314 @cindex @code{a.out} symbol attributes
2315 @cindex symbol attributes, @code{a.out}
2321 @subsection Symbol Attributes: @code{a.out}
2323 @cindex @code{a.out} symbol attributes
2324 @cindex symbol attributes, @code{a.out}
2328 * Symbol Desc:: Descriptor
2329 * Symbol Other:: Other
2333 @subsubsection Descriptor
2335 @cindex descriptor, of @code{a.out} symbol
2336 This is an arbitrary 16-bit value. You may establish a symbol's
2337 descriptor value by using a @code{.desc} statement
2338 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
2342 @subsubsection Other
2344 @cindex other attribute, of @code{a.out} symbol
2345 This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}.
2350 @subsection Symbol Attributes for COFF
2352 @cindex COFF symbol attributes
2353 @cindex symbol attributes, COFF
2355 The COFF format supports a multitude of auxiliary symbol attributes;
2356 like the primary symbol attributes, they are set between @code{.def} and
2357 @code{.endef} directives.
2359 @subsubsection Primary Attributes
2361 @cindex primary attributes, COFF symbols
2362 The symbol name is set with @code{.def}; the value and type,
2363 respectively, with @code{.val} and @code{.type}.
2365 @subsubsection Auxiliary Attributes
2367 @cindex auxiliary attributes, COFF symbols
2368 The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
2369 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2370 information for COFF.
2375 @subsection Symbol Attributes for SOM
2377 @cindex SOM symbol attributes
2378 @cindex symbol attributes, SOM
2380 The SOM format for the HPPA supports a multitude of symbol attributes set with
2381 the @code{.EXPORT} and @code{.IMPORT} directives.
2383 The attributes are described in @cite{HP9000 Series 800 Assembly
2384 Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
2385 @code{EXPORT} assembler directive documentation.
2389 @chapter Expressions
2393 @cindex numeric values
2394 An @dfn{expression} specifies an address or numeric value.
2395 Whitespace may precede and/or follow an expression.
2398 * Empty Exprs:: Empty Expressions
2399 * Integer Exprs:: Integer Expressions
2403 @section Empty Expressions
2405 @cindex empty expressions
2406 @cindex expressions, empty
2407 An empty expression has no value: it is just whitespace or null.
2408 Wherever an absolute expression is required, you may omit the
2409 expression, and @code{@value{AS}} assumes a value of (absolute) 0. This
2410 is compatible with other assemblers.
2413 @section Integer Expressions
2415 @cindex integer expressions
2416 @cindex expressions, integer
2417 An @dfn{integer expression} is one or more @emph{arguments} delimited
2418 by @emph{operators}.
2421 * Arguments:: Arguments
2422 * Operators:: Operators
2423 * Prefix Ops:: Prefix Operators
2424 * Infix Ops:: Infix Operators
2428 @subsection Arguments
2430 @cindex expression arguments
2431 @cindex arguments in expressions
2432 @cindex operands in expressions
2433 @cindex arithmetic operands
2434 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2435 contexts arguments are sometimes called ``arithmetic operands''. In
2436 this manual, to avoid confusing them with the ``instruction operands'' of
2437 the machine language, we use the term ``argument'' to refer to parts of
2438 expressions only, reserving the word ``operand'' to refer only to machine
2439 instruction operands.
2441 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2442 @var{section} is one of text, data, bss, absolute,
2443 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2446 Numbers are usually integers.
2448 A number can be a flonum or bignum. In this case, you are warned
2449 that only the low order 32 bits are used, and @code{@value{AS}} pretends
2450 these 32 bits are an integer. You may write integer-manipulating
2451 instructions that act on exotic constants, compatible with other
2454 @cindex subexpressions
2455 Subexpressions are a left parenthesis @samp{(} followed by an integer
2456 expression, followed by a right parenthesis @samp{)}; or a prefix
2457 operator followed by an argument.
2460 @subsection Operators
2462 @cindex operators, in expressions
2463 @cindex arithmetic functions
2464 @cindex functions, in expressions
2465 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2466 operators are followed by an argument. Infix operators appear
2467 between their arguments. Operators may be preceded and/or followed by
2471 @subsection Prefix Operator
2473 @cindex prefix operators
2474 @code{@value{AS}} has the following @dfn{prefix operators}. They each take
2475 one argument, which must be absolute.
2477 @c the tex/end tex stuff surrounding this small table is meant to make
2478 @c it align, on the printed page, with the similar table in the next
2479 @c section (which is inside an enumerate).
2481 \global\advance\leftskip by \itemindent
2486 @dfn{Negation}. Two's complement negation.
2488 @dfn{Complementation}. Bitwise not.
2492 \global\advance\leftskip by -\itemindent
2496 @subsection Infix Operators
2498 @cindex infix operators
2499 @cindex operators, permitted arguments
2500 @dfn{Infix operators} take two arguments, one on either side. Operators
2501 have precedence, but operations with equal precedence are performed left
2502 to right. Apart from @code{+} or @code{-}, both arguments must be
2503 absolute, and the result is absolute.
2506 @cindex operator precedence
2507 @cindex precedence of operators
2514 @dfn{Multiplication}.
2517 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2524 @dfn{Shift Left}. Same as the C operator @samp{<<}.
2528 @dfn{Shift Right}. Same as the C operator @samp{>>}.
2532 Intermediate precedence
2537 @dfn{Bitwise Inclusive Or}.
2543 @dfn{Bitwise Exclusive Or}.
2546 @dfn{Bitwise Or Not}.
2554 @cindex addition, permitted arguments
2555 @cindex plus, permitted arguments
2556 @cindex arguments for addition
2557 @dfn{Addition}. If either argument is absolute, the result
2558 has the section of the other argument.
2559 If either argument is pass1 or undefined, the result is pass1.
2560 Otherwise @code{+} is illegal.
2563 @cindex subtraction, permitted arguments
2564 @cindex minus, permitted arguments
2565 @cindex arguments for subtraction
2566 @dfn{Subtraction}. If the right argument is absolute, the
2567 result has the section of the left argument.
2568 If either argument is pass1 the result is pass1.
2569 If either argument is undefined the result is difference section.
2570 If both arguments are in the same section, the result is absolute---provided
2571 that section is one of text, data or bss.
2572 Otherwise subtraction is illegal.
2576 The sense of the rule for addition is that it's only meaningful to add
2577 the @emph{offsets} in an address; you can only have a defined section in
2578 one of the two arguments.
2580 Similarly, you can't subtract quantities from two different sections.
2583 @chapter Assembler Directives
2585 @cindex directives, machine independent
2586 @cindex pseudo-ops, machine independent
2587 @cindex machine independent directives
2588 All assembler directives have names that begin with a period (@samp{.}).
2589 The rest of the name is letters, usually in lower case.
2591 This chapter discusses directives that are available regardless of the
2592 target machine configuration for the GNU assembler.
2594 Some machine configurations provide additional directives.
2595 @xref{Machine Dependencies}.
2598 @ifset machine-directives
2599 @xref{Machine Dependencies} for additional directives.
2604 * Abort:: @code{.abort}
2606 * ABORT:: @code{.ABORT}
2609 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2610 * App-File:: @code{.app-file @var{string}}
2611 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2612 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2613 * Byte:: @code{.byte @var{expressions}}
2614 * Comm:: @code{.comm @var{symbol} , @var{length} }
2615 * Data:: @code{.data @var{subsection}}
2617 * Def:: @code{.def @var{name}}
2620 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2626 * Double:: @code{.double @var{flonums}}
2627 * Eject:: @code{.eject}
2628 * Else:: @code{.else}
2630 * Endef:: @code{.endef}
2633 * Endif:: @code{.endif}
2634 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2635 * Extern:: @code{.extern}
2636 @ifclear no-file-dir
2637 * File:: @code{.file @var{string}}
2640 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2641 * Float:: @code{.float @var{flonums}}
2642 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2643 * hword:: @code{.hword @var{expressions}}
2644 * Ident:: @code{.ident}
2645 * If:: @code{.if @var{absolute expression}}
2646 * Include:: @code{.include "@var{file}"}
2647 * Int:: @code{.int @var{expressions}}
2648 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2649 * Lflags:: @code{.lflags}
2650 @ifclear no-line-dir
2651 * Line:: @code{.line @var{line-number}}
2654 * Ln:: @code{.ln @var{line-number}}
2655 * List:: @code{.list}
2656 * Long:: @code{.long @var{expressions}}
2658 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2661 * Nolist:: @code{.nolist}
2662 * Octa:: @code{.octa @var{bignums}}
2663 * Org:: @code{.org @var{new-lc} , @var{fill}}
2664 * Psize:: @code{.psize @var{lines}, @var{columns}}
2665 * Quad:: @code{.quad @var{bignums}}
2666 * Sbttl:: @code{.sbttl "@var{subheading}"}
2668 * Scl:: @code{.scl @var{class}}
2671 * Section:: @code{.section @var{name}, @var{subsection}}
2674 * Set:: @code{.set @var{symbol}, @var{expression}}
2675 * Short:: @code{.short @var{expressions}}
2676 * Single:: @code{.single @var{flonums}}
2678 * Size:: @code{.size}
2681 * Space:: @code{.space @var{size} , @var{fill}}
2683 * Stab:: @code{.stabd, .stabn, .stabs}
2686 * String:: @code{.string "@var{str}"}
2688 * Tag:: @code{.tag @var{structname}}
2691 * Text:: @code{.text @var{subsection}}
2692 * Title:: @code{.title "@var{heading}"}
2694 * Type:: @code{.type @var{int}}
2695 * Val:: @code{.val @var{addr}}
2698 * Word:: @code{.word @var{expressions}}
2699 * Deprecated:: Deprecated Directives
2703 @section @code{.abort}
2705 @cindex @code{abort} directive
2706 @cindex stopping the assembly
2707 This directive stops the assembly immediately. It is for
2708 compatibility with other assemblers. The original idea was that the
2709 assembly language source would be piped into the assembler. If the sender
2710 of the source quit, it could use this directive tells @code{@value{AS}} to
2711 quit also. One day @code{.abort} will not be supported.
2715 @section @code{.ABORT}
2717 @cindex @code{ABORT} directive
2718 When producing COFF output, @code{@value{AS}} accepts this directive as a
2719 synonym for @samp{.abort}.
2722 When producing @code{b.out} output, @code{@value{AS}} accepts this directive,
2728 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2730 @cindex padding the location counter
2731 @cindex @code{align} directive
2732 Pad the location counter (in the current subsection) to a particular
2733 storage boundary. The first expression (which must be absolute) is the
2734 number of low-order zero bits the location counter must have after
2735 advancement. For example @samp{.align 3} advances the location
2736 counter until it a multiple of 8. If the location counter is already a
2737 multiple of 8, no change is needed.
2740 For the HPPA, the first expression (which must be absolute) is the
2741 alignment request in bytes. For example @samp{.align 8} advances
2742 the location counter until it is a multiple of 8. If the location counter
2743 is already a multiple of 8, no change is needed.
2746 The second expression (also absolute) gives the value to be stored in
2747 the padding bytes. It (and the comma) may be omitted. If it is
2748 omitted, the padding bytes are zero.
2751 @section @code{.app-file @var{string}}
2753 @cindex logical file name
2754 @cindex file name, logical
2755 @cindex @code{app-file} directive
2757 @ifclear no-file-dir
2758 (which may also be spelled @samp{.file})
2760 tells @code{@value{AS}} that we are about to start a new
2761 logical file. @var{string} is the new file name. In general, the
2762 filename is recognized whether or not it is surrounded by quotes @samp{"};
2763 but if you wish to specify an empty file name is permitted,
2764 you must give the quotes--@code{""}. This statement may go away in
2765 future: it is only recognized to be compatible with old @code{@value{AS}}
2769 @section @code{.ascii "@var{string}"}@dots{}
2771 @cindex @code{ascii} directive
2772 @cindex string literals
2773 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2774 separated by commas. It assembles each string (with no automatic
2775 trailing zero byte) into consecutive addresses.
2778 @section @code{.asciz "@var{string}"}@dots{}
2780 @cindex @code{asciz} directive
2781 @cindex zero-terminated strings
2782 @cindex null-terminated strings
2783 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2784 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2787 @section @code{.byte @var{expressions}}
2789 @cindex @code{byte} directive
2790 @cindex integers, one byte
2791 @code{.byte} expects zero or more expressions, separated by commas.
2792 Each expression is assembled into the next byte.
2795 @section @code{.comm @var{symbol} , @var{length} }
2797 @cindex @code{comm} directive
2798 @cindex symbol, common
2799 @code{.comm} declares a named common area in the bss section. Normally
2800 @code{@value{LD}} reserves memory addresses for it during linking, so no partial
2801 program defines the location of the symbol. Use @code{.comm} to tell
2802 @code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}}
2803 allocates space for each @code{.comm} symbol that is at least as
2804 long as the longest @code{.comm} request in any of the partial programs
2805 linked. @var{length} is an absolute expression.
2808 The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
2809 @samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
2813 @section @code{.data @var{subsection}}
2815 @cindex @code{data} directive
2816 @code{.data} tells @code{@value{AS}} to assemble the following statements onto the
2817 end of the data subsection numbered @var{subsection} (which is an
2818 absolute expression). If @var{subsection} is omitted, it defaults
2823 @section @code{.def @var{name}}
2825 @cindex @code{def} directive
2826 @cindex COFF symbols, debugging
2827 @cindex debugging COFF symbols
2828 Begin defining debugging information for a symbol @var{name}; the
2829 definition extends until the @code{.endef} directive is encountered.
2832 This directive is only observed when @code{@value{AS}} is configured for COFF
2833 format output; when producing @code{b.out}, @samp{.def} is recognized,
2840 @section @code{.desc @var{symbol}, @var{abs-expression}}
2842 @cindex @code{desc} directive
2843 @cindex COFF symbol descriptor
2844 @cindex symbol descriptor, COFF
2845 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2846 to the low 16 bits of an absolute expression.
2849 The @samp{.desc} directive is not available when @code{@value{AS}} is
2850 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2851 object format. For the sake of compatibility, @code{@value{AS}} accepts
2852 it, but produces no output, when configured for COFF.
2858 @section @code{.dim}
2860 @cindex @code{dim} directive
2861 @cindex COFF auxiliary symbol information
2862 @cindex auxiliary symbol information, COFF
2863 This directive is generated by compilers to include auxiliary debugging
2864 information in the symbol table. It is only permitted inside
2865 @code{.def}/@code{.endef} pairs.
2868 @samp{.dim} is only meaningful when generating COFF format output; when
2869 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
2875 @section @code{.double @var{flonums}}
2877 @cindex @code{double} directive
2878 @cindex floating point numbers (double)
2879 @code{.double} expects zero or more flonums, separated by commas. It
2880 assembles floating point numbers.
2882 The exact kind of floating point numbers emitted depends on how
2883 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
2887 On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
2888 in @sc{ieee} format.
2893 @section @code{.eject}
2895 @cindex @code{eject} directive
2896 @cindex new page, in listings
2897 @cindex page, in listings
2898 @cindex listing control: new page
2899 Force a page break at this point, when generating assembly listings.
2902 @section @code{.else}
2904 @cindex @code{else} directive
2905 @code{.else} is part of the @code{@value{AS}} support for conditional
2906 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2907 of code to be assembled if the condition for the preceding @code{.if}
2911 @node End, Endef, Else, Pseudo Ops
2912 @section @code{.end}
2914 @cindex @code{end} directive
2915 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2916 meant to do something eventually (which is why it isn't documented here
2917 as "for compatibility with blah").
2922 @section @code{.endef}
2924 @cindex @code{endef} directive
2925 This directive flags the end of a symbol definition begun with
2929 @samp{.endef} is only meaningful when generating COFF format output; if
2930 @code{@value{AS}} is configured to generate @code{b.out}, it accepts this
2931 directive but ignores it.
2936 @section @code{.endif}
2938 @cindex @code{endif} directive
2939 @code{.endif} is part of the @code{@value{AS}} support for conditional assembly;
2940 it marks the end of a block of code that is only assembled
2941 conditionally. @xref{If,,@code{.if}}.
2944 @section @code{.equ @var{symbol}, @var{expression}}
2946 @cindex @code{equ} directive
2947 @cindex assigning values to symbols
2948 @cindex symbols, assigning values to
2949 This directive sets the value of @var{symbol} to @var{expression}.
2950 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
2953 The syntax for @code{equ} on the HPPA is
2954 @samp{@var{symbol} .equ @var{expression}}.
2958 @section @code{.extern}
2960 @cindex @code{extern} directive
2961 @code{.extern} is accepted in the source program---for compatibility
2962 with other assemblers---but it is ignored. @code{@value{AS}} treats
2963 all undefined symbols as external.
2965 @ifclear no-file-dir
2967 @section @code{.file @var{string}}
2969 @cindex @code{file} directive
2970 @cindex logical file name
2971 @cindex file name, logical
2972 @code{.file} (which may also be spelled @samp{.app-file}) tells
2973 @code{@value{AS}} that we are about to start a new logical file.
2974 @var{string} is the new file name. In general, the filename is
2975 recognized whether or not it is surrounded by quotes @samp{"}; but if
2976 you wish to specify an empty file name, you must give the
2977 quotes--@code{""}. This statement may go away in future: it is only
2978 recognized to be compatible with old @code{@value{AS}} programs.
2980 In some configurations of @code{@value{AS}}, @code{.file} has already been
2981 removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}.
2986 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
2988 @cindex @code{fill} directive
2989 @cindex writing patterns in memory
2990 @cindex patterns, writing in memory
2991 @var{result}, @var{size} and @var{value} are absolute expressions.
2992 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
2993 may be zero or more. @var{Size} may be zero or more, but if it is
2994 more than 8, then it is deemed to have the value 8, compatible with
2995 other people's assemblers. The contents of each @var{repeat} bytes
2996 is taken from an 8-byte number. The highest order 4 bytes are
2997 zero. The lowest order 4 bytes are @var{value} rendered in the
2998 byte-order of an integer on the computer @code{@value{AS}} is assembling for.
2999 Each @var{size} bytes in a repetition is taken from the lowest order
3000 @var{size} bytes of this number. Again, this bizarre behavior is
3001 compatible with other people's assemblers.
3003 @var{size} and @var{value} are optional.
3004 If the second comma and @var{value} are absent, @var{value} is
3005 assumed zero. If the first comma and following tokens are absent,
3006 @var{size} is assumed to be 1.
3009 @section @code{.float @var{flonums}}
3011 @cindex floating point numbers (single)
3012 @cindex @code{float} directive
3013 This directive assembles zero or more flonums, separated by commas. It
3014 has the same effect as @code{.single}.
3016 The exact kind of floating point numbers emitted depends on how
3017 @code{@value{AS}} is configured.
3018 @xref{Machine Dependencies}.
3022 On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
3023 in @sc{ieee} format.
3028 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
3030 @cindex @code{global} directive
3031 @cindex symbol, making visible to linker
3032 @code{.global} makes the symbol visible to @code{@value{LD}}. If you define
3033 @var{symbol} in your partial program, its value is made available to
3034 other partial programs that are linked with it. Otherwise,
3035 @var{symbol} takes its attributes from a symbol of the same name
3036 from another file linked into the same program.
3038 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
3039 compatibility with other assemblers.
3042 On the HPPA, @code{.global} is not always enough to make it accessible to other
3043 partial programs. You may need the HPPA-only @code{.EXPORT} directive as well.
3044 @xref{HPPA Directives,, HPPA Assembler Directives}.
3048 @section @code{.hword @var{expressions}}
3050 @cindex @code{hword} directive
3051 @cindex integers, 16-bit
3052 @cindex numbers, 16-bit
3053 @cindex sixteen bit integers
3054 This expects zero or more @var{expressions}, and emits
3055 a 16 bit number for each.
3058 This directive is a synonym for @samp{.short}; depending on the target
3059 architecture, it may also be a synonym for @samp{.word}.
3063 This directive is a synonym for @samp{.short}.
3066 This directive is a synonym for both @samp{.short} and @samp{.word}.
3071 @section @code{.ident}
3073 @cindex @code{ident} directive
3074 This directive is used by some assemblers to place tags in object files.
3075 @code{@value{AS}} simply accepts the directive for source-file
3076 compatibility with such assemblers, but does not actually emit anything
3080 @section @code{.if @var{absolute expression}}
3082 @cindex conditional assembly
3083 @cindex @code{if} directive
3084 @code{.if} marks the beginning of a section of code which is only
3085 considered part of the source program being assembled if the argument
3086 (which must be an @var{absolute expression}) is non-zero. The end of
3087 the conditional section of code must be marked by @code{.endif}
3088 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
3089 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
3091 The following variants of @code{.if} are also supported:
3093 @item .ifdef @var{symbol}
3094 @cindex @code{ifdef} directive
3095 Assembles the following section of code if the specified @var{symbol}
3100 @cindex @code{ifeqs} directive
3101 Not yet implemented.
3104 @item .ifndef @var{symbol}
3105 @itemx ifnotdef @var{symbol}
3106 @cindex @code{ifndef} directive
3107 @cindex @code{ifnotdef} directive
3108 Assembles the following section of code if the specified @var{symbol}
3109 has not been defined. Both spelling variants are equivalent.
3113 Not yet implemented.
3118 @section @code{.include "@var{file}"}
3120 @cindex @code{include} directive
3121 @cindex supporting files, including
3122 @cindex files, including
3123 This directive provides a way to include supporting files at specified
3124 points in your source program. The code from @var{file} is assembled as
3125 if it followed the point of the @code{.include}; when the end of the
3126 included file is reached, assembly of the original file continues. You
3127 can control the search paths used with the @samp{-I} command-line option
3128 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
3132 @section @code{.int @var{expressions}}
3134 @cindex @code{int} directive
3135 @cindex integers, 32-bit
3136 Expect zero or more @var{expressions}, of any section, separated by commas.
3137 For each expression, emit a number that, at run time, is the value of that
3138 expression. The byte order and bit size of the number depends on what kind
3139 of target the assembly is for.
3143 On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
3144 integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits
3150 @section @code{.lcomm @var{symbol} , @var{length}}
3152 @cindex @code{lcomm} directive
3153 @cindex local common symbols
3154 @cindex symbols, local common
3155 Reserve @var{length} (an absolute expression) bytes for a local common
3156 denoted by @var{symbol}. The section and value of @var{symbol} are
3157 those of the new local common. The addresses are allocated in the bss
3158 section, so that at run-time the bytes start off zeroed. @var{Symbol}
3159 is not declared global (@pxref{Global,,@code{.global}}), so is normally
3160 not visible to @code{@value{LD}}.
3163 The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
3164 @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
3168 @section @code{.lflags}
3170 @cindex @code{lflags} directive (ignored)
3171 @code{@value{AS}} accepts this directive, for compatibility with other
3172 assemblers, but ignores it.
3174 @ifclear no-line-dir
3176 @section @code{.line @var{line-number}}
3178 @cindex @code{line} directive
3182 @section @code{.ln @var{line-number}}
3184 @cindex @code{ln} directive
3186 @cindex logical line number
3188 Change the logical line number. @var{line-number} must be an absolute
3189 expression. The next line has that logical line number. Therefore any other
3190 statements on the current line (after a statement separator character) are
3191 reported as on logical line number @var{line-number} @minus{} 1. One day
3192 @code{@value{AS}} will no longer support this directive: it is recognized only
3193 for compatibility with existing assembler programs.
3197 @emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
3198 not available; use the synonym @code{.ln} in that context.
3203 @ifclear no-line-dir
3204 Even though this is a directive associated with the @code{a.out} or
3205 @code{b.out} object-code formats, @code{@value{AS}} still recognizes it
3206 when producing COFF output, and treats @samp{.line} as though it
3207 were the COFF @samp{.ln} @emph{if} it is found outside a
3208 @code{.def}/@code{.endef} pair.
3210 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
3211 used by compilers to generate auxiliary symbol information for
3216 @section @code{.ln @var{line-number}}
3218 @cindex @code{ln} directive
3219 @ifclear no-line-dir
3220 @samp{.ln} is a synonym for @samp{.line}.
3223 Tell @code{@value{AS}} to change the logical line number. @var{line-number}
3224 must be an absolute expression. The next line has that logical
3225 line number, so any other statements on the current line (after a
3226 statement separator character @code{;}) are reported as on logical
3227 line number @var{line-number} @minus{} 1.
3230 This directive is accepted, but ignored, when @code{@value{AS}} is
3231 configured for @code{b.out}; its effect is only associated with COFF
3237 @section @code{.list}
3239 @cindex @code{list} directive
3240 @cindex listing control, turning on
3241 Control (in conjunction with the @code{.nolist} directive) whether or
3242 not assembly listings are generated. These two directives maintain an
3243 internal counter (which is zero initially). @code{.list} increments the
3244 counter, and @code{.nolist} decrements it. Assembly listings are
3245 generated whenever the counter is greater than zero.
3247 By default, listings are disabled. When you enable them (with the
3248 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
3249 the initial value of the listing counter is one.
3252 @section @code{.long @var{expressions}}
3254 @cindex @code{long} directive
3255 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
3258 @c no one seems to know what this is for or whether this description is
3259 @c what it really ought to do
3261 @section @code{.lsym @var{symbol}, @var{expression}}
3263 @cindex @code{lsym} directive
3264 @cindex symbol, not referenced in assembly
3265 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
3266 the hash table, ensuring it cannot be referenced by name during the
3267 rest of the assembly. This sets the attributes of the symbol to be
3268 the same as the expression value:
3270 @var{other} = @var{descriptor} = 0
3271 @var{type} = @r{(section of @var{expression})}
3272 @var{value} = @var{expression}
3275 The new symbol is not flagged as external.
3279 @section @code{.nolist}
3281 @cindex @code{nolist} directive
3282 @cindex listing control, turning off
3283 Control (in conjunction with the @code{.list} directive) whether or
3284 not assembly listings are generated. These two directives maintain an
3285 internal counter (which is zero initially). @code{.list} increments the
3286 counter, and @code{.nolist} decrements it. Assembly listings are
3287 generated whenever the counter is greater than zero.
3290 @section @code{.octa @var{bignums}}
3292 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
3293 @cindex @code{octa} directive
3294 @cindex integer, 16-byte
3295 @cindex sixteen byte integer
3296 This directive expects zero or more bignums, separated by commas. For each
3297 bignum, it emits a 16-byte integer.
3299 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
3300 hence @emph{octa}-word for 16 bytes.
3303 @section @code{.org @var{new-lc} , @var{fill}}
3305 @cindex @code{org} directive
3306 @cindex location counter, advancing
3307 @cindex advancing location counter
3308 @cindex current address, advancing
3309 Advance the location counter of the current section to
3310 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3311 expression with the same section as the current subsection. That is,
3312 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3313 wrong section, the @code{.org} directive is ignored. To be compatible
3314 with former assemblers, if the section of @var{new-lc} is absolute,
3315 @code{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
3316 is the same as the current subsection.
3318 @code{.org} may only increase the location counter, or leave it
3319 unchanged; you cannot use @code{.org} to move the location counter
3322 @c double negative used below "not undefined" because this is a specific
3323 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3324 @c section. pesch@cygnus.com 18feb91
3325 Because @code{@value{AS}} tries to assemble programs in one pass @var{new-lc}
3326 may not be undefined. If you really detest this restriction we eagerly await
3327 a chance to share your improved assembler.
3329 Beware that the origin is relative to the start of the section, not
3330 to the start of the subsection. This is compatible with other
3331 people's assemblers.
3333 When the location counter (of the current subsection) is advanced, the
3334 intervening bytes are filled with @var{fill} which should be an
3335 absolute expression. If the comma and @var{fill} are omitted,
3336 @var{fill} defaults to zero.
3339 @section @code{.psize @var{lines} , @var{columns}}
3341 @cindex @code{psize} directive
3342 @cindex listing control: paper size
3343 @cindex paper size, for listings
3344 Use this directive to declare the number of lines---and, optionally, the
3345 number of columns---to use for each page, when generating listings.
3347 If you do not use @code{.psize}, listings use a default line-count
3348 of 60. You may omit the comma and @var{columns} specification; the
3349 default width is 200 columns.
3351 @code{@value{AS}} generates formfeeds whenever the specified number of
3352 lines is exceeded (or whenever you explicitly request one, using
3355 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3356 those explicitly specified with @code{.eject}.
3359 @section @code{.quad @var{bignums}}
3361 @cindex @code{quad} directive
3362 @code{.quad} expects zero or more bignums, separated by commas. For
3363 each bignum, it emits
3365 an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
3366 warning message; and just takes the lowest order 8 bytes of the bignum.
3367 @cindex eight-byte integer
3368 @cindex integer, 8-byte
3370 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3371 hence @emph{quad}-word for 8 bytes.
3374 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3375 warning message; and just takes the lowest order 16 bytes of the bignum.
3376 @cindex sixteen-byte integer
3377 @cindex integer, 16-byte
3381 @section @code{.sbttl "@var{subheading}"}
3383 @cindex @code{sbttl} directive
3384 @cindex subtitles for listings
3385 @cindex listing control: subtitle
3386 Use @var{subheading} as the title (third line, immediately after the
3387 title line) when generating assembly listings.
3389 This directive affects subsequent pages, as well as the current page if
3390 it appears within ten lines of the top of a page.
3394 @section @code{.scl @var{class}}
3396 @cindex @code{scl} directive
3397 @cindex symbol storage class (COFF)
3398 @cindex COFF symbol storage class
3399 Set the storage-class value for a symbol. This directive may only be
3400 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3401 whether a symbol is static or external, or it may record further
3402 symbolic debugging information.
3405 The @samp{.scl} directive is primarily associated with COFF output; when
3406 configured to generate @code{b.out} output format, @code{@value{AS}}
3407 accepts this directive but ignores it.
3413 @section @code{.section @var{name}, @var{subsection}}
3415 @cindex @code{section} directive
3416 @cindex named section (COFF)
3417 @cindex COFF named section
3418 Assemble the following code into end of subsection numbered
3419 @var{subsection} in the COFF named section @var{name}. If you omit
3420 @var{subsection}, @code{@value{AS}} uses subsection number zero.
3421 @samp{.section .text} is equivalent to the @code{.text} directive;
3422 @samp{.section .data} is equivalent to the @code{.data} directive.
3426 @section @code{.set @var{symbol}, @var{expression}}
3428 @cindex @code{set} directive
3429 @cindex symbol value, setting
3430 Set the value of @var{symbol} to @var{expression}. This
3431 changes @var{symbol}'s value and type to conform to
3432 @var{expression}. If @var{symbol} was flagged as external, it remains
3433 flagged. (@xref{Symbol Attributes}.)
3435 You may @code{.set} a symbol many times in the same assembly.
3436 If the expression's section is unknowable during pass 1, a second
3437 pass over the source program is necessary. The second pass is
3438 currently not implemented. @code{@value{AS}} aborts with an error
3439 message if one is required.
3441 If you @code{.set} a global symbol, the value stored in the object
3442 file is the last value stored into it.
3445 The syntax for @code{set} on the HPPA is
3446 @samp{@var{symbol} .set @var{expression}}.
3450 @section @code{.short @var{expressions}}
3452 @cindex @code{short} directive
3454 @code{.short} is normally the same as @samp{.word}.
3455 @xref{Word,,@code{.word}}.
3457 In some configurations, however, @code{.short} and @code{.word} generate
3458 numbers of different lengths; @pxref{Machine Dependencies}.
3462 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3465 This expects zero or more @var{expressions}, and emits
3466 a 16 bit number for each.
3471 @section @code{.single @var{flonums}}
3473 @cindex @code{single} directive
3474 @cindex floating point numbers (single)
3475 This directive assembles zero or more flonums, separated by commas. It
3476 has the same effect as @code{.float}.
3478 The exact kind of floating point numbers emitted depends on how
3479 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
3483 On the @value{TARGET} family, @code{.single} emits 32-bit floating point
3484 numbers in @sc{ieee} format.
3490 @section @code{.size}
3492 @cindex @code{size} directive
3493 This directive is generated by compilers to include auxiliary debugging
3494 information in the symbol table. It is only permitted inside
3495 @code{.def}/@code{.endef} pairs.
3498 @samp{.size} is only meaningful when generating COFF format output; when
3499 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3504 @ifclear no-space-dir
3506 @section @code{.space @var{size} , @var{fill}}
3508 @cindex @code{space} directive
3509 @cindex filling memory
3510 This directive emits @var{size} bytes, each of value @var{fill}. Both
3511 @var{size} and @var{fill} are absolute expressions. If the comma
3512 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3516 @emph{Warning:} @code{.space} has a completely different meaning for HPPA
3517 targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800
3518 Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the
3519 @code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives},
3528 @section @code{.space}
3529 @cindex @code{space} directive
3531 On the AMD 29K, this directive is ignored; it is accepted for
3532 compatibility with other AMD 29K assemblers.
3535 @emph{Warning:} In most versions of the GNU assembler, the directive
3536 @code{.space} has the effect of @code{.block} @xref{Machine Dependencies}.
3542 @section @code{.stabd, .stabn, .stabs}
3544 @cindex symbolic debuggers, information for
3545 @cindex @code{stab@var{x}} directives
3546 There are three directives that begin @samp{.stab}.
3547 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3548 The symbols are not entered in the @code{@value{AS}} hash table: they
3549 cannot be referenced elsewhere in the source file.
3550 Up to five fields are required:
3554 This is the symbol's name. It may contain any character except
3555 @samp{\000}, so is more general than ordinary symbol names. Some
3556 debuggers used to code arbitrarily complex structures into symbol names
3560 An absolute expression. The symbol's type is set to the low 8 bits of
3561 this expression. Any bit pattern is permitted, but @code{@value{LD}}
3562 and debuggers choke on silly bit patterns.
3565 An absolute expression. The symbol's ``other'' attribute is set to the
3566 low 8 bits of this expression.
3569 An absolute expression. The symbol's descriptor is set to the low 16
3570 bits of this expression.
3573 An absolute expression which becomes the symbol's value.
3576 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3577 or @code{.stabs} statement, the symbol has probably already been created;
3578 you get a half-formed symbol in your object file. This is
3579 compatible with earlier assemblers!
3582 @cindex @code{stabd} directive
3583 @item .stabd @var{type} , @var{other} , @var{desc}
3585 The ``name'' of the symbol generated is not even an empty string.
3586 It is a null pointer, for compatibility. Older assemblers used a
3587 null pointer so they didn't waste space in object files with empty
3590 The symbol's value is set to the location counter,
3591 relocatably. When your program is linked, the value of this symbol
3592 is the address of the location counter when the @code{.stabd} was
3595 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3596 @cindex @code{stabn} directive
3597 The name of the symbol is set to the empty string @code{""}.
3599 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3600 @cindex @code{stabs} directive
3601 All five fields are specified.
3607 @section @code{.string} "@var{str}"
3609 @cindex string, copying to object file
3610 @cindex @code{string} directive
3612 Copy the characters in @var{str} to the object file. You may specify more than
3613 one string to copy, separated by commas. Unless otherwise specified for a
3614 particular machine, the assembler marks the end of each string with a 0 byte.
3615 You can use any of the escape sequences described in @ref{Strings,,Strings}.
3619 @section @code{.tag @var{structname}}
3621 @cindex COFF structure debugging
3622 @cindex structure debugging, COFF
3623 @cindex @code{tag} directive
3624 This directive is generated by compilers to include auxiliary debugging
3625 information in the symbol table. It is only permitted inside
3626 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3627 definitions in the symbol table with instances of those structures.
3630 @samp{.tag} is only used when generating COFF format output; when
3631 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3637 @section @code{.text @var{subsection}}
3639 @cindex @code{text} directive
3640 Tells @code{@value{AS}} to assemble the following statements onto the end of
3641 the text subsection numbered @var{subsection}, which is an absolute
3642 expression. If @var{subsection} is omitted, subsection number zero
3646 @section @code{.title "@var{heading}"}
3648 @cindex @code{title} directive
3649 @cindex listing control: title line
3650 Use @var{heading} as the title (second line, immediately after the
3651 source file name and pagenumber) when generating assembly listings.
3653 This directive affects subsequent pages, as well as the current page if
3654 it appears within ten lines of the top of a page.
3658 @section @code{.type @var{int}}
3660 @cindex COFF symbol type
3661 @cindex symbol type, COFF
3662 @cindex @code{type} directive
3663 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3664 records the integer @var{int} as the type attribute of a symbol table entry.
3667 @samp{.type} is associated only with COFF format output; when
3668 @code{@value{AS}} is configured for @code{b.out} output, it accepts this
3669 directive but ignores it.
3675 @section @code{.val @var{addr}}
3677 @cindex @code{val} directive
3678 @cindex COFF value attribute
3679 @cindex value attribute, COFF
3680 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3681 records the address @var{addr} as the value attribute of a symbol table
3685 @samp{.val} is used only for COFF output; when @code{@value{AS}} is
3686 configured for @code{b.out}, it accepts this directive but ignores it.
3691 @section @code{.word @var{expressions}}
3693 @cindex @code{word} directive
3694 This directive expects zero or more @var{expressions}, of any section,
3695 separated by commas.
3698 For each expression, @code{@value{AS}} emits a 32-bit number.
3701 For each expression, @code{@value{AS}} emits a 16-bit number.
3706 The size of the number emitted, and its byte order,
3707 depend on what target computer the assembly is for.
3710 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3711 @c happen---32-bit addressability, period; no long/short jumps.
3712 @ifset DIFF-TBL-KLUGE
3713 @cindex difference tables altered
3714 @cindex altered difference tables
3716 @emph{Warning: Special Treatment to support Compilers}
3720 Machines with a 32-bit address space, but that do less than 32-bit
3721 addressing, require the following special treatment. If the machine of
3722 interest to you does 32-bit addressing (or doesn't require it;
3723 @pxref{Machine Dependencies}), you can ignore this issue.
3726 In order to assemble compiler output into something that works,
3727 @code{@value{AS}} occasionlly does strange things to @samp{.word} directives.
3728 Directives of the form @samp{.word sym1-sym2} are often emitted by
3729 compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a
3730 directive of the form @samp{.word sym1-sym2}, and the difference between
3731 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}}
3732 creates a @dfn{secondary jump table}, immediately before the next label.
3733 This secondary jump table is preceded by a short-jump to the
3734 first byte after the secondary table. This short-jump prevents the flow
3735 of control from accidentally falling into the new table. Inside the
3736 table is a long-jump to @code{sym2}. The original @samp{.word}
3737 contains @code{sym1} minus the address of the long-jump to
3740 If there were several occurrences of @samp{.word sym1-sym2} before the
3741 secondary jump table, all of them are adjusted. If there was a
3742 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3743 long-jump to @code{sym4} is included in the secondary jump table,
3744 and the @code{.word} directives are adjusted to contain @code{sym3}
3745 minus the address of the long-jump to @code{sym4}; and so on, for as many
3746 entries in the original jump table as necessary.
3749 @emph{This feature may be disabled by compiling @code{@value{AS}} with the
3750 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3751 assembly language programmers.
3754 @c end DIFF-TBL-KLUGE
3757 @section Deprecated Directives
3759 @cindex deprecated directives
3760 @cindex obsolescent directives
3761 One day these directives won't work.
3762 They are included for compatibility with older assemblers.
3770 @node Machine Dependencies
3771 @chapter Machine Dependent Features
3773 @cindex machine dependencies
3774 The machine instruction sets are (almost by definition) different on
3775 each machine where @code{@value{AS}} runs. Floating point representations
3776 vary as well, and @code{@value{AS}} often supports a few additional
3777 directives or command-line options for compatibility with other
3778 assemblers on a particular platform. Finally, some versions of
3779 @code{@value{AS}} support special pseudo-instructions for branch
3782 This chapter discusses most of these differences, though it does not
3783 include details on any machine's instruction set. For details on that
3784 subject, see the hardware manufacturer's manual.
3788 * Vax-Dependent:: VAX Dependent Features
3791 * AMD29K-Dependent:: AMD 29K Dependent Features
3794 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
3797 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
3800 * HPPA-Dependent:: HPPA Dependent Features
3803 * SH-Dependent:: Hitachi SH Dependent Features
3806 * i960-Dependent:: Intel 80960 Dependent Features
3809 * M68K-Dependent:: M680x0 Dependent Features
3812 * Sparc-Dependent:: SPARC Dependent Features
3815 * Z8000-Dependent:: Z8000 Dependent Features
3818 * MIPS-Dependent:: MIPS Dependent Features
3821 * i386-Dependent:: 80386 Dependent Features
3828 @c The following major nodes are *sections* in the GENERIC version, *chapters*
3829 @c in single-cpu versions. This is mainly achieved by @lowersections. There is a
3830 @c peculiarity: to preserve cross-references, there must be a node called
3831 @c "Machine Dependencies". Hence the conditional nodenames in each
3832 @c major node below. Node defaulting in makeinfo requires adjacency of
3833 @c node and sectioning commands; hence the repetition of @chapter BLAH
3834 @c in both conditional blocks.
3839 @chapter VAX Dependent Features
3844 @node Machine Dependencies
3845 @chapter VAX Dependent Features
3851 * Vax-Opts:: VAX Command-Line Options
3852 * VAX-float:: VAX Floating Point
3853 * VAX-directives:: Vax Machine Directives
3854 * VAX-opcodes:: VAX Opcodes
3855 * VAX-branch:: VAX Branch Improvement
3856 * VAX-operands:: VAX Operands
3857 * VAX-no:: Not Supported on VAX
3862 @section VAX Command-Line Options
3864 @cindex command-line options ignored, VAX
3865 @cindex VAX command-line options ignored
3866 The Vax version of @code{@value{AS}} accepts any of the following options,
3867 gives a warning message that the option was ignored and proceeds.
3868 These options are for compatibility with scripts designed for other
3869 people's assemblers.
3872 @item @code{-D} (Debug)
3873 @itemx @code{-S} (Symbol Table)
3874 @itemx @code{-T} (Token Trace)
3875 @cindex @code{-D}, ignored on VAX
3876 @cindex @code{-S}, ignored on VAX
3877 @cindex @code{-T}, ignored on VAX
3878 These are obsolete options used to debug old assemblers.
3880 @item @code{-d} (Displacement size for JUMPs)
3881 @cindex @code{-d}, VAX option
3882 This option expects a number following the @samp{-d}. Like options
3883 that expect filenames, the number may immediately follow the
3884 @samp{-d} (old standard) or constitute the whole of the command line
3885 argument that follows @samp{-d} (GNU standard).
3887 @item @code{-V} (Virtualize Interpass Temporary File)
3888 @cindex @code{-V}, redundant on VAX
3889 Some other assemblers use a temporary file. This option
3890 commanded them to keep the information in active memory rather
3891 than in a disk file. @code{@value{AS}} always does this, so this
3892 option is redundant.
3894 @item @code{-J} (JUMPify Longer Branches)
3895 @cindex @code{-J}, ignored on VAX
3896 Many 32-bit computers permit a variety of branch instructions
3897 to do the same job. Some of these instructions are short (and
3898 fast) but have a limited range; others are long (and slow) but
3899 can branch anywhere in virtual memory. Often there are 3
3900 flavors of branch: short, medium and long. Some other
3901 assemblers would emit short and medium branches, unless told by
3902 this option to emit short and long branches.
3904 @item @code{-t} (Temporary File Directory)
3905 @cindex @code{-t}, ignored on VAX
3906 Some other assemblers may use a temporary file, and this option
3907 takes a filename being the directory to site the temporary
3908 file. Since @code{@value{AS}} does not use a temporary disk file, this
3909 option makes no difference. @samp{-t} needs exactly one
3913 @cindex VMS (VAX) options
3914 @cindex options for VAX/VMS
3915 @cindex VAX/VMS options
3916 @cindex @code{-h} option, VAX/VMS
3917 @cindex @code{-+} option, VAX/VMS
3918 @cindex Vax-11 C compatibility
3919 @cindex symbols with lowercase, VAX/VMS
3920 @c FIXME! look into "I think" below, correct if needed, delete.
3921 The Vax version of the assembler accepts two options when
3922 compiled for VMS. They are @samp{-h}, and @samp{-+}. The
3923 @samp{-h} option prevents @code{@value{AS}} from modifying the
3924 symbol-table entries for symbols that contain lowercase
3925 characters (I think). The @samp{-+} option causes @code{@value{AS}} to
3926 print warning messages if the FILENAME part of the object file,
3927 or any symbol name is larger than 31 characters. The @samp{-+}
3928 option also inserts some code following the @samp{_main}
3929 symbol so that the object file is compatible with Vax-11
3933 @section VAX Floating Point
3935 @cindex VAX floating point
3936 @cindex floating point, VAX
3937 Conversion of flonums to floating point is correct, and
3938 compatible with previous assemblers. Rounding is
3939 towards zero if the remainder is exactly half the least significant bit.
3941 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
3944 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
3945 are rendered correctly. Again, rounding is towards zero in the
3948 @cindex @code{float} directive, VAX
3949 @cindex @code{double} directive, VAX
3950 The @code{.float} directive produces @code{f} format numbers.
3951 The @code{.double} directive produces @code{d} format numbers.
3953 @node VAX-directives
3954 @section Vax Machine Directives
3956 @cindex machine directives, VAX
3957 @cindex VAX machine directives
3958 The Vax version of the assembler supports four directives for
3959 generating Vax floating point constants. They are described in the
3962 @cindex wide floating point directives, VAX
3965 @cindex @code{dfloat} directive, VAX
3966 This expects zero or more flonums, separated by commas, and
3967 assembles Vax @code{d} format 64-bit floating point constants.
3970 @cindex @code{ffloat} directive, VAX
3971 This expects zero or more flonums, separated by commas, and
3972 assembles Vax @code{f} format 32-bit floating point constants.
3975 @cindex @code{gfloat} directive, VAX
3976 This expects zero or more flonums, separated by commas, and
3977 assembles Vax @code{g} format 64-bit floating point constants.
3980 @cindex @code{hfloat} directive, VAX
3981 This expects zero or more flonums, separated by commas, and
3982 assembles Vax @code{h} format 128-bit floating point constants.
3987 @section VAX Opcodes
3989 @cindex VAX opcode mnemonics
3990 @cindex opcode mnemonics, VAX
3991 @cindex mnemonics for opcodes, VAX
3992 All DEC mnemonics are supported. Beware that @code{case@dots{}}
3993 instructions have exactly 3 operands. The dispatch table that
3994 follows the @code{case@dots{}} instruction should be made with
3995 @code{.word} statements. This is compatible with all unix
3996 assemblers we know of.
3999 @section VAX Branch Improvement
4001 @cindex VAX branch improvement
4002 @cindex branch improvement, VAX
4003 @cindex pseudo-ops for branch, VAX
4004 Certain pseudo opcodes are permitted. They are for branch
4005 instructions. They expand to the shortest branch instruction that
4006 reaches the target. Generally these mnemonics are made by
4007 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
4008 This feature is included both for compatibility and to help
4009 compilers. If you do not need this feature, avoid these
4010 opcodes. Here are the mnemonics, and the code they can expand into.
4014 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
4016 @item (byte displacement)
4018 @item (word displacement)
4020 @item (long displacement)
4025 Unconditional branch.
4027 @item (byte displacement)
4029 @item (word displacement)
4031 @item (long displacement)
4035 @var{COND} may be any one of the conditional branches
4036 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
4037 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
4038 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
4039 @var{COND} may also be one of the bit tests
4040 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
4041 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
4042 @var{NOTCOND} is the opposite condition to @var{COND}.
4044 @item (byte displacement)
4045 @kbd{b@var{COND} @dots{}}
4046 @item (word displacement)
4047 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
4048 @item (long displacement)
4049 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
4052 @var{X} may be one of @code{b d f g h l w}.
4054 @item (word displacement)
4055 @kbd{@var{OPCODE} @dots{}}
4056 @item (long displacement)
4058 @var{OPCODE} @dots{}, foo ;
4065 @var{YYY} may be one of @code{lss leq}.
4067 @var{ZZZ} may be one of @code{geq gtr}.
4069 @item (byte displacement)
4070 @kbd{@var{OPCODE} @dots{}}
4071 @item (word displacement)
4073 @var{OPCODE} @dots{}, foo ;
4075 foo: brw @var{destination} ;
4078 @item (long displacement)
4080 @var{OPCODE} @dots{}, foo ;
4082 foo: jmp @var{destination} ;
4091 @item (byte displacement)
4092 @kbd{@var{OPCODE} @dots{}}
4093 @item (word displacement)
4095 @var{OPCODE} @dots{}, foo ;
4097 foo: brw @var{destination} ;
4100 @item (long displacement)
4102 @var{OPCODE} @dots{}, foo ;
4104 foo: jmp @var{destination} ;
4111 @section VAX Operands
4113 @cindex VAX operand notation
4114 @cindex operand notation, VAX
4115 @cindex immediate character, VAX
4116 @cindex VAX immediate character
4117 The immediate character is @samp{$} for Unix compatibility, not
4118 @samp{#} as DEC writes it.
4120 @cindex indirect character, VAX
4121 @cindex VAX indirect character
4122 The indirect character is @samp{*} for Unix compatibility, not
4123 @samp{@@} as DEC writes it.
4125 @cindex displacement sizing character, VAX
4126 @cindex VAX displacement sizing character
4127 The displacement sizing character is @samp{`} (an accent grave) for
4128 Unix compatibility, not @samp{^} as DEC writes it. The letter
4129 preceding @samp{`} may have either case. @samp{G} is not
4130 understood, but all other letters (@code{b i l s w}) are understood.
4132 @cindex register names, VAX
4133 @cindex VAX register names
4134 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
4135 pc}. Upper and lower case letters are equivalent.
4142 Any expression is permitted in an operand. Operands are comma
4145 @c There is some bug to do with recognizing expressions
4146 @c in operands, but I forget what it is. It is
4147 @c a syntax clash because () is used as an address mode
4148 @c and to encapsulate sub-expressions.
4151 @section Not Supported on VAX
4153 @cindex VAX bitfields not supported
4154 @cindex bitfields, not supported on VAX
4155 Vax bit fields can not be assembled with @code{@value{AS}}. Someone
4156 can add the required code if they really need it.
4162 @node AMD29K-Dependent
4163 @chapter AMD 29K Dependent Features
4166 @node Machine Dependencies
4167 @chapter AMD 29K Dependent Features
4170 @cindex AMD 29K support
4173 * AMD29K Options:: Options
4174 * AMD29K Syntax:: Syntax
4175 * AMD29K Floating Point:: Floating Point
4176 * AMD29K Directives:: AMD 29K Machine Directives
4177 * AMD29K Opcodes:: Opcodes
4180 @node AMD29K Options
4182 @cindex AMD 29K options (none)
4183 @cindex options for AMD29K (none)
4184 @code{@value{AS}} has no additional command-line options for the AMD
4190 * AMD29K-Chars:: Special Characters
4191 * AMD29K-Regs:: Register Names
4195 @subsection Special Characters
4197 @cindex line comment character, AMD 29K
4198 @cindex AMD 29K line comment character
4199 @samp{;} is the line comment character.
4201 @cindex line separator, AMD 29K
4202 @cindex AMD 29K line separator
4203 @cindex statement separator, AMD 29K
4204 @cindex AMD 29K statement separator
4205 @samp{@@} can be used instead of a newline to separate statements.
4207 @cindex identifiers, AMD 29K
4208 @cindex AMD 29K identifiers
4209 The character @samp{?} is permitted in identifiers (but may not begin
4213 @subsection Register Names
4215 @cindex AMD 29K register names
4216 @cindex register names, AMD 29K
4217 General-purpose registers are represented by predefined symbols of the
4218 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
4219 (for local registers), where @var{nnn} represents a number between
4220 @code{0} and @code{127}, written with no leading zeros. The leading
4221 letters may be in either upper or lower case; for example, @samp{gr13}
4222 and @samp{LR7} are both valid register names.
4224 You may also refer to general-purpose registers by specifying the
4225 register number as the result of an expression (prefixed with @samp{%%}
4226 to flag the expression as a register number):
4231 ---where @var{expression} must be an absolute expression evaluating to a
4232 number between @code{0} and @code{255}. The range [0, 127] refers to
4233 global registers, and the range [128, 255] to local registers.
4235 @cindex special purpose registers, AMD 29K
4236 @cindex AMD 29K special purpose registers
4237 @cindex protected registers, AMD 29K
4238 @cindex AMD 29K protected registers
4239 In addition, @code{@value{AS}} understands the following protected
4240 special-purpose register names for the AMD 29K family:
4250 These unprotected special-purpose register names are also recognized:
4258 @node AMD29K Floating Point
4259 @section Floating Point
4261 @cindex floating point, AMD 29K (@sc{ieee})
4262 @cindex AMD 29K floating point (@sc{ieee})
4263 The AMD 29K family uses @sc{ieee} floating-point numbers.
4265 @node AMD29K Directives
4266 @section AMD 29K Machine Directives
4268 @cindex machine directives, AMD 29K
4269 @cindex AMD 29K machine directives
4271 @item .block @var{size} , @var{fill}
4272 @cindex @code{block} directive, AMD 29K
4273 This directive emits @var{size} bytes, each of value @var{fill}. Both
4274 @var{size} and @var{fill} are absolute expressions. If the comma
4275 and @var{fill} are omitted, @var{fill} is assumed to be zero.
4277 In other versions of the GNU assembler, this directive is called
4283 @cindex @code{cputype} directive, AMD 29K
4284 This directive is ignored; it is accepted for compatibility with other
4288 @cindex @code{file} directive, AMD 29K
4289 This directive is ignored; it is accepted for compatibility with other
4293 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
4294 used for the directive called @code{.app-file} in the AMD 29K support.
4298 @cindex @code{line} directive, AMD 29K
4299 This directive is ignored; it is accepted for compatibility with other
4303 @c since we're ignoring .lsym...
4304 @item .reg @var{symbol}, @var{expression}
4305 @cindex @code{reg} directive, AMD 29K
4306 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
4310 @cindex @code{sect} directive, AMD 29K
4311 This directive is ignored; it is accepted for compatibility with other
4314 @item .use @var{section name}
4315 @cindex @code{use} directive, AMD 29K
4316 Establishes the section and subsection for the following code;
4317 @var{section name} may be one of @code{.text}, @code{.data},
4318 @code{.data1}, or @code{.lit}. With one of the first three @var{section
4319 name} options, @samp{.use} is equivalent to the machine directive
4320 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
4324 @node AMD29K Opcodes
4327 @cindex AMD 29K opcodes
4328 @cindex opcodes for AMD 29K
4329 @code{@value{AS}} implements all the standard AMD 29K opcodes. No
4330 additional pseudo-instructions are needed on this family.
4332 For information on the 29K machine instruction set, see @cite{Am29000
4333 User's Manual}, Advanced Micro Devices, Inc.
4338 @node Machine Dependencies
4339 @chapter Machine Dependent Features
4341 The machine instruction sets are different on each Hitachi chip family,
4342 and there are also some syntax differences among the families. This
4343 chapter describes the specific @code{@value{AS}} features for each
4347 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
4348 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
4349 * SH-Dependent:: Hitachi SH Dependent Features
4359 @node H8/300-Dependent
4360 @chapter H8/300 Dependent Features
4362 @cindex H8/300 support
4364 * H8/300 Options:: Options
4365 * H8/300 Syntax:: Syntax
4366 * H8/300 Floating Point:: Floating Point
4367 * H8/300 Directives:: H8/300 Machine Directives
4368 * H8/300 Opcodes:: Opcodes
4371 @node H8/300 Options
4374 @cindex H8/300 options (none)
4375 @cindex options, H8/300 (none)
4376 @code{@value{AS}} has no additional command-line options for the Hitachi
4382 * H8/300-Chars:: Special Characters
4383 * H8/300-Regs:: Register Names
4384 * H8/300-Addressing:: Addressing Modes
4388 @subsection Special Characters
4390 @cindex line comment character, H8/300
4391 @cindex H8/300 line comment character
4392 @samp{;} is the line comment character.
4394 @cindex line separator, H8/300
4395 @cindex statement separator, H8/300
4396 @cindex H8/300 line separator
4397 @samp{$} can be used instead of a newline to separate statements.
4398 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4401 @subsection Register Names
4403 @cindex H8/300 registers
4404 @cindex register names, H8/300
4405 You can use predefined symbols of the form @samp{r@var{n}h} and
4406 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4407 general-purpose registers. @var{n} is a digit from @samp{0} to
4408 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4411 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4412 to the H8/300 registers as 16-bit registers (you must use this form for
4415 On the H8/300H, you can also use the eight predefined symbols
4416 @samp{er@var{n}} (@samp{er0} @dots{} @samp{er7}) to refer to the 32-bit
4417 general purpose registers.
4419 The two control registers are called @code{pc} (program counter; a
4420 16-bit register, except on the H8/300H where it is 24 bits) and
4421 @code{ccr} (condition code register; an 8-bit register). @code{r7} is
4422 used as the stack pointer, and can also be called @code{sp}.
4424 @node H8/300-Addressing
4425 @subsection Addressing Modes
4427 @cindex addressing modes, H8/300
4428 @cindex H8/300 addressing modes
4429 @value{AS} understands the following addressing modes for the H8/300:
4437 @item @@(@var{d}, r@var{n})
4438 @itemx @@(@var{d}:16, r@var{n})
4439 @itemx @@(@var{d}:24, r@var{n})
4440 Register indirect: 16-bit or 24-bit displacement @var{d} from register
4441 @var{n}. (24-bit displacements are only meaningful on the H8/300H.)
4444 Register indirect with post-increment
4447 Register indirect with pre-decrement
4449 @item @code{@@}@var{aa}
4450 @itemx @code{@@}@var{aa}:8
4451 @itemx @code{@@}@var{aa}:16
4452 @itemx @code{@@}@var{aa}:24
4453 Absolute address @code{aa}. (The address size @samp{:24} only makes
4454 sense on the H8/300H.)
4460 Immediate data @var{xx}. You may specify the @samp{:8}, @samp{:16}, or
4461 @samp{:32} for clarity, if you wish; but @code{@value{AS}} neither
4462 requires this nor uses it---the data size required is taken from
4465 @item @code{@@}@code{@@}@var{aa}
4466 @itemx @code{@@}@code{@@}@var{aa}:8
4467 Memory indirect. You may specify the @samp{:8} for clarity, if you
4468 wish; but @code{@value{AS}} neither requires this nor uses it.
4471 @node H8/300 Floating Point
4472 @section Floating Point
4474 @cindex floating point, H8/300 (@sc{ieee})
4475 @cindex H8/300 floating point (@sc{ieee})
4476 The H8/300 family has no hardware floating point, but the @code{.float}
4477 directive generates @sc{ieee} floating-point numbers for compatibility
4478 with other development tools.
4481 @node H8/300 Directives
4482 @section H8/300 Machine Directives
4484 @cindex H8/300 machine directives (none)
4485 @cindex machine directives, H8/300 (none)
4486 @cindex @code{word} directive, H8/300
4487 @cindex @code{int} directive, H8/300
4488 @code{@value{AS}} has only one machine-dependent directive for the
4493 @cindex H8/300H, assembling for
4494 Recognize and emit additional instructions for the H8/300H variant, and
4495 also make @code{.int} emit 32-bit numbers rather than the usual (16-bit)
4496 for the H8/300 family.
4499 On the H8/300 family (including the H8/300H) @samp{.word} directives
4500 generate 16-bit numbers.
4502 @node H8/300 Opcodes
4505 @cindex H8/300 opcode summary
4506 @cindex opcode summary, H8/300
4507 @cindex mnemonics, H8/300
4508 @cindex instruction summary, H8/300
4509 For detailed information on the H8/300 machine instruction set, see
4510 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025). For
4511 information specific to the H8/300H, see @cite{H8/300H Series
4512 Programming Manual} (Hitachi).
4514 @code{@value{AS}} implements all the standard H8/300 opcodes. No additional
4515 pseudo-instructions are needed on this family.
4518 @c this table, due to the multi-col faking and hardcoded order, looks silly
4519 @c except in smallbook. See comments below "@set SMALL" near top of this file.
4521 The following table summarizes the H8/300 opcodes, and their arguments.
4522 Entries marked @samp{*} are opcodes used only on the H8/300H.
4525 @c Using @group seems to use the normal baselineskip, not the smallexample
4526 @c baselineskip; looks approx doublespaced.
4528 Rs @r{source register}
4529 Rd @r{destination register}
4530 abs @r{absolute address}
4531 imm @r{immediate data}
4532 disp:N @r{N-bit displacement from a register}
4533 pcrel:N @r{N-bit displacement relative to program counter}
4535 add.b #imm,rd * andc #imm,ccr
4536 add.b rs,rd band #imm,rd
4537 add.w rs,rd band #imm,@@rd
4538 * add.w #imm,rd band #imm,@@abs:8
4539 * add.l rs,rd bra pcrel:8
4540 * add.l #imm,rd * bra pcrel:16
4541 adds #imm,rd bt pcrel:8
4542 addx #imm,rd * bt pcrel:16
4543 addx rs,rd brn pcrel:8
4544 and.b #imm,rd * brn pcrel:16
4545 and.b rs,rd bf pcrel:8
4546 * and.w rs,rd * bf pcrel:16
4547 * and.w #imm,rd bhi pcrel:8
4548 * and.l #imm,rd * bhi pcrel:16
4549 * and.l rs,rd bls pcrel:8
4551 * bls pcrel:16 bld #imm,rd
4552 bcc pcrel:8 bld #imm,@@rd
4553 * bcc pcrel:16 bld #imm,@@abs:8
4554 bhs pcrel:8 bnot #imm,rd
4555 * bhs pcrel:16 bnot #imm,@@rd
4556 bcs pcrel:8 bnot #imm,@@abs:8
4557 * bcs pcrel:16 bnot rs,rd
4558 blo pcrel:8 bnot rs,@@rd
4559 * blo pcrel:16 bnot rs,@@abs:8
4560 bne pcrel:8 bor #imm,rd
4561 * bne pcrel:16 bor #imm,@@rd
4562 beq pcrel:8 bor #imm,@@abs:8
4563 * beq pcrel:16 bset #imm,rd
4564 bvc pcrel:8 bset #imm,@@rd
4565 * bvc pcrel:16 bset #imm,@@abs:8
4566 bvs pcrel:8 bset rs,rd
4567 * bvs pcrel:16 bset rs,@@rd
4568 bpl pcrel:8 bset rs,@@abs:8
4569 * bpl pcrel:16 bsr pcrel:8
4570 bmi pcrel:8 bsr pcrel:16
4571 * bmi pcrel:16 bst #imm,rd
4572 bge pcrel:8 bst #imm,@@rd
4573 * bge pcrel:16 bst #imm,@@abs:8
4574 blt pcrel:8 btst #imm,rd
4575 * blt pcrel:16 btst #imm,@@rd
4576 bgt pcrel:8 btst #imm,@@abs:8
4577 * bgt pcrel:16 btst rs,rd
4578 ble pcrel:8 btst rs,@@rd
4579 * ble pcrel:16 btst rs,@@abs:8
4580 bclr #imm,rd bxor #imm,rd
4581 bclr #imm,@@rd bxor #imm,@@rd
4582 bclr #imm,@@abs:8 bxor #imm,@@abs:8
4583 bclr rs,rd cmp.b #imm,rd
4584 bclr rs,@@rd cmp.b rs,rd
4585 bclr rs,@@abs:8 cmp.w rs,rd
4586 biand #imm,rd cmp.w rs,rd
4587 biand #imm,@@rd * cmp.w #imm,rd
4588 biand #imm,@@abs:8 * cmp.l #imm,rd
4589 bild #imm,rd * cmp.l rs,rd
4590 bild #imm,@@rd daa rs
4591 bild #imm,@@abs:8 das rs
4592 bior #imm,rd dec.b rs
4593 bior #imm,@@rd * dec.w #imm,rd
4594 bior #imm,@@abs:8 * dec.l #imm,rd
4595 bist #imm,rd divxu.b rs,rd
4596 bist #imm,@@rd * divxu.w rs,rd
4597 bist #imm,@@abs:8 * divxs.b rs,rd
4598 bixor #imm,rd * divxs.w rs,rd
4599 bixor #imm,@@rd eepmov
4600 bixor #imm,@@abs:8 * eepmovw
4602 * exts.w rd mov.w rs,@@abs:16
4603 * exts.l rd * mov.l #imm,rd
4604 * extu.w rd * mov.l rs,rd
4605 * extu.l rd * mov.l @@rs,rd
4606 inc rs * mov.l @@(disp:16,rs),rd
4607 * inc.w #imm,rd * mov.l @@(disp:24,rs),rd
4608 * inc.l #imm,rd * mov.l @@rs+,rd
4609 jmp @@rs * mov.l @@abs:16,rd
4610 jmp abs * mov.l @@abs:24,rd
4611 jmp @@@@abs:8 * mov.l rs,@@rd
4612 jsr @@rs * mov.l rs,@@(disp:16,rd)
4613 jsr abs * mov.l rs,@@(disp:24,rd)
4614 jsr @@@@abs:8 * mov.l rs,@@-rd
4615 ldc #imm,ccr * mov.l rs,@@abs:16
4616 ldc rs,ccr * mov.l rs,@@abs:24
4617 * ldc @@abs:16,ccr movfpe @@abs:16,rd
4618 * ldc @@abs:24,ccr movtpe rs,@@abs:16
4619 * ldc @@(disp:16,rs),ccr mulxu.b rs,rd
4620 * ldc @@(disp:24,rs),ccr * mulxu.w rs,rd
4621 * ldc @@rs+,ccr * mulxs.b rs,rd
4622 * ldc @@rs,ccr * mulxs.w rs,rd
4623 * mov.b @@(disp:24,rs),rd neg.b rs
4624 * mov.b rs,@@(disp:24,rd) * neg.w rs
4625 mov.b @@abs:16,rd * neg.l rs
4627 mov.b @@abs:8,rd not.b rs
4628 mov.b rs,@@abs:8 * not.w rs
4629 mov.b rs,rd * not.l rs
4630 mov.b #imm,rd or.b #imm,rd
4631 mov.b @@rs,rd or.b rs,rd
4632 mov.b @@(disp:16,rs),rd * or.w #imm,rd
4633 mov.b @@rs+,rd * or.w rs,rd
4634 mov.b @@abs:8,rd * or.l #imm,rd
4635 mov.b rs,@@rd * or.l rs,rd
4636 mov.b rs,@@(disp:16,rd) orc #imm,ccr
4637 mov.b rs,@@-rd pop.w rs
4638 mov.b rs,@@abs:8 * pop.l rs
4639 mov.w rs,@@rd push.w rs
4640 * mov.w @@(disp:24,rs),rd * push.l rs
4641 * mov.w rs,@@(disp:24,rd) rotl.b rs
4642 * mov.w @@abs:24,rd * rotl.w rs
4643 * mov.w rs,@@abs:24 * rotl.l rs
4644 mov.w rs,rd rotr.b rs
4645 mov.w #imm,rd * rotr.w rs
4646 mov.w @@rs,rd * rotr.l rs
4647 mov.w @@(disp:16,rs),rd rotxl.b rs
4648 mov.w @@rs+,rd * rotxl.w rs
4649 mov.w @@abs:16,rd * rotxl.l rs
4650 mov.w rs,@@(disp:16,rd) rotxr.b rs
4651 mov.w rs,@@-rd * rotxr.w rs
4653 * rotxr.l rs * stc ccr,@@(disp:24,rd)
4655 rte * stc ccr,@@abs:16
4656 rts * stc ccr,@@abs:24
4657 shal.b rs sub.b rs,rd
4658 * shal.w rs sub.w rs,rd
4659 * shal.l rs * sub.w #imm,rd
4660 shar.b rs * sub.l rs,rd
4661 * shar.w rs * sub.l #imm,rd
4662 * shar.l rs subs #imm,rd
4663 shll.b rs subx #imm,rd
4664 * shll.w rs subx rs,rd
4665 * shll.l rs * trapa #imm
4666 shlr.b rs xor #imm,rd
4667 * shlr.w rs xor rs,rd
4668 * shlr.l rs * xor.w #imm,rd
4670 stc ccr,rd * xor.l #imm,rd
4671 * stc ccr,@@rs * xor.l rs,rd
4672 * stc ccr,@@(disp:16,rd) xorc #imm,ccr
4676 @cindex size suffixes, H8/300
4677 @cindex H8/300 size suffixes
4678 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4679 @code{sub}) are defined with variants using the suffixes @samp{.b},
4680 @samp{.w}, and @samp{.l} to specify the size of a memory operand.
4681 @code{@value{AS}} supports these suffixes, but does not require them;
4682 since one of the operands is always a register, @code{@value{AS}} can
4683 deduce the correct size.
4685 For example, since @code{r0} refers to a 16-bit register,
4688 @exdent is equivalent to
4692 If you use the size suffixes, @code{@value{AS}} issues a warning when
4693 the suffix and the register size do not match.
4698 @node H8/500-Dependent
4699 @chapter H8/500 Dependent Features
4701 @cindex H8/500 support
4703 * H8/500 Options:: Options
4704 * H8/500 Syntax:: Syntax
4705 * H8/500 Floating Point:: Floating Point
4706 * H8/500 Directives:: H8/500 Machine Directives
4707 * H8/500 Opcodes:: Opcodes
4710 @node H8/500 Options
4713 @cindex H8/500 options (none)
4714 @cindex options, H8/500 (none)
4715 @code{@value{AS}} has no additional command-line options for the Hitachi
4722 * H8/500-Chars:: Special Characters
4723 * H8/500-Regs:: Register Names
4724 * H8/500-Addressing:: Addressing Modes
4728 @subsection Special Characters
4730 @cindex line comment character, H8/500
4731 @cindex H8/500 line comment character
4732 @samp{!} is the line comment character.
4734 @cindex line separator, H8/500
4735 @cindex statement separator, H8/500
4736 @cindex H8/500 line separator
4737 @samp{;} can be used instead of a newline to separate statements.
4739 @cindex symbol names, @samp{$} in
4740 @cindex @code{$} in symbol names
4741 Since @samp{$} has no special meaning, you may use it in symbol names.
4744 @subsection Register Names
4746 @cindex H8/500 registers
4747 @cindex registers, H8/500
4748 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
4749 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, and @samp{r7} to refer to
4750 the H8/500 registers.
4752 The H8/500 also has these control registers:
4774 condition code register
4777 All registers are 16 bits long. To represent 32 bit numbers, use two
4778 adjacent registers; for distant memory addresses, use one of the segment
4779 pointers (@code{cp} for the program counter; @code{dp} for
4780 @code{r0}--@code{r3}; @code{ep} for @code{r4} and @code{r5}; and
4781 @code{tp} for @code{r6} and @code{r7}.
4783 @node H8/500-Addressing
4784 @subsection Addressing Modes
4786 @cindex addressing modes, H8/500
4787 @cindex H8/500 addressing modes
4788 @value{AS} understands the following addressing modes for the H8/500:
4796 @item @@(d:8, R@var{n})
4797 Register indirect with 8 bit signed displacement
4799 @item @@(d:16, R@var{n})
4800 Register indirect with 16 bit signed displacement
4803 Register indirect with pre-decrement
4806 Register indirect with post-increment
4809 8 bit absolute address
4812 16 bit absolute address
4821 @node H8/500 Floating Point
4822 @section Floating Point
4824 @cindex floating point, H8/500 (@sc{ieee})
4825 @cindex H8/500 floating point (@sc{ieee})
4826 The H8/500 family uses @sc{ieee} floating-point numbers.
4828 @node H8/500 Directives
4829 @section H8/500 Machine Directives
4831 @cindex H8/500 machine directives (none)
4832 @cindex machine directives, H8/500 (none)
4833 @cindex @code{word} directive, H8/500
4834 @cindex @code{int} directive, H8/500
4835 @code{@value{AS}} has no machine-dependent directives for the H8/500.
4836 However, on this platform the @samp{.int} and @samp{.word} directives
4837 generate 16-bit numbers.
4839 @node H8/500 Opcodes
4842 @cindex H8/500 opcode summary
4843 @cindex opcode summary, H8/500
4844 @cindex mnemonics, H8/500
4845 @cindex instruction summary, H8/500
4846 For detailed information on the H8/500 machine instruction set, see
4847 @cite{H8/500 Series Programming Manual} (Hitachi M21T001).
4849 @code{@value{AS}} implements all the standard H8/500 opcodes. No additional
4850 pseudo-instructions are needed on this family.
4853 @c this table, due to the multi-col faking and hardcoded order, looks silly
4854 @c except in smallbook. See comments below "@set SMALL" near top of this file.
4856 The following table summarizes H8/500 opcodes and their operands:
4858 @c Use @group if it ever works, instead of @page
4862 abs8 @r{8-bit absolute address}
4863 abs16 @r{16-bit absolute address}
4864 abs24 @r{24-bit absolute address}
4865 crb @r{@code{ccr}, @code{br}, @code{ep}, @code{dp}, @code{tp}, @code{dp}}
4866 disp8 @r{8-bit displacement}
4867 ea @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4868 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16},}
4869 @r{@code{#xx:8}, @code{#xx:16}}
4870 ea_mem @r{@code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4871 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4872 ea_noimm @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4873 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4875 imm4 @r{4-bit immediate data}
4876 imm8 @r{8-bit immediate data}
4877 imm16 @r{16-bit immediate data}
4878 pcrel8 @r{8-bit offset from program counter}
4879 pcrel16 @r{16-bit offset from program counter}
4880 qim @r{@code{-2}, @code{-1}, @code{1}, @code{2}}
4882 rs @r{a register distinct from rd}
4883 rlist @r{comma-separated list of registers in parentheses;}
4884 @r{register ranges @code{rd-rs} are allowed}
4885 sp @r{stack pointer (@code{r7})}
4886 sr @r{status register}
4887 sz @r{size; @samp{.b} or @samp{.w}. If omitted, default @samp{.w}}
4889 ldc[.b] ea,crb bcc[.w] pcrel16
4890 ldc[.w] ea,sr bcc[.b] pcrel8
4891 add[:q] sz qim,ea_noimm bhs[.w] pcrel16
4892 add[:g] sz ea,rd bhs[.b] pcrel8
4893 adds sz ea,rd bcs[.w] pcrel16
4894 addx sz ea,rd bcs[.b] pcrel8
4895 and sz ea,rd blo[.w] pcrel16
4896 andc[.b] imm8,crb blo[.b] pcrel8
4897 andc[.w] imm16,sr bne[.w] pcrel16
4899 bra[.w] pcrel16 beq[.w] pcrel16
4900 bra[.b] pcrel8 beq[.b] pcrel8
4901 bt[.w] pcrel16 bvc[.w] pcrel16
4902 bt[.b] pcrel8 bvc[.b] pcrel8
4903 brn[.w] pcrel16 bvs[.w] pcrel16
4904 brn[.b] pcrel8 bvs[.b] pcrel8
4905 bf[.w] pcrel16 bpl[.w] pcrel16
4906 bf[.b] pcrel8 bpl[.b] pcrel8
4907 bhi[.w] pcrel16 bmi[.w] pcrel16
4908 bhi[.b] pcrel8 bmi[.b] pcrel8
4909 bls[.w] pcrel16 bge[.w] pcrel16
4910 bls[.b] pcrel8 bge[.b] pcrel8
4912 blt[.w] pcrel16 mov[:g][.b] imm8,ea_mem
4913 blt[.b] pcrel8 mov[:g][.w] imm16,ea_mem
4914 bgt[.w] pcrel16 movfpe[.b] ea,rd
4915 bgt[.b] pcrel8 movtpe[.b] rs,ea_noimm
4916 ble[.w] pcrel16 mulxu sz ea,rd
4917 ble[.b] pcrel8 neg sz ea
4918 bclr sz imm4,ea_noimm nop
4919 bclr sz rs,ea_noimm not sz ea
4920 bnot sz imm4,ea_noimm or sz ea,rd
4921 bnot sz rs,ea_noimm orc[.b] imm8,crb
4922 bset sz imm4,ea_noimm orc[.w] imm16,sr
4923 bset sz rs,ea_noimm pjmp abs24
4924 bsr[.b] pcrel8 pjmp @@rd
4925 bsr[.w] pcrel16 pjsr abs24
4926 btst sz imm4,ea_noimm pjsr @@rd
4927 btst sz rs,ea_noimm prtd imm8
4928 clr sz ea prtd imm16
4929 cmp[:e][.b] imm8,rd prts
4930 cmp[:i][.w] imm16,rd rotl sz ea
4931 cmp[:g].b imm8,ea_noimm rotr sz ea
4932 cmp[:g][.w] imm16,ea_noimm rotxl sz ea
4933 Cmp[:g] sz ea,rd rotxr sz ea
4935 divxu sz ea,rd rtd imm16
4937 exts[.b] rd scb/f rs,pcrel8
4938 extu[.b] rd scb/ne rs,pcrel8
4939 jmp @@rd scb/eq rs,pcrel8
4940 jmp @@(imm8,rd) shal sz ea
4941 jmp @@(imm16,rd) shar sz ea
4942 jmp abs16 shll sz ea
4944 jsr @@(imm8,rd) sleep
4945 jsr @@(imm16,rd) stc[.b] crb,ea_noimm
4946 jsr abs16 stc[.w] sr,ea_noimm
4947 ldm @@sp+,(rlist) stm (rlist),@@-sp
4948 link fp,imm8 sub sz ea,rd
4949 link fp,imm16 subs sz ea,rd
4950 mov[:e][.b] imm8,rd subx sz ea,rd
4951 mov[:i][.w] imm16,rd swap[.b] rd
4952 mov[:l][.w] abs8,rd tas[.b] ea
4953 mov[:l].b abs8,rd trapa imm4
4954 mov[:s][.w] rs,abs8 trap/vs
4955 mov[:s].b rs,abs8 tst sz ea
4956 mov[:f][.w] @@(disp8,fp),rd unlk fp
4957 mov[:f][.w] rs,@@(disp8,fp) xch[.w] rs,rd
4958 mov[:f].b @@(disp8,fp),rd xor sz ea,rd
4959 mov[:f].b rs,@@(disp8,fp) xorc.b imm8,crb
4960 mov[:g] sz rs,ea_mem xorc.w imm16,sr
4968 @node HPPA-Dependent
4969 @chapter HPPA Dependent Features
4973 * HPPA Notes:: Notes
4974 * HPPA Options:: Options
4975 * HPPA Syntax:: Syntax
4976 * HPPA Floating Point:: Floating Point
4977 * HPPA Directives:: HPPA Machine Directives
4978 * HPPA Opcodes:: Opcodes
4983 As a back end for GNU CC @code{@value{AS}} has been throughly tested and should
4984 work extremely well. We have tested it only minimally on hand written assembly
4985 code and no one has tested it much on the assembly output from the HP
4988 The format of the debugging sections has changed since the original
4989 @code{@value{AS}} port (version 1.3X) was released; therefore,
4990 you must rebuild all HPPA objects and libraries with the new
4991 assembler so that you can debug the final executable.
4993 The HPPA @code{@value{AS}} port generates a small subset of the relocations
4994 available in the SOM and ELF object file formats. Additional relocation
4995 support will be added as it becomes necessary.
4999 @code{@value{AS}} has no machine-dependent command-line options for the HPPA.
5004 The assembler syntax closely follows the HPPA instruction set
5005 reference manual; assembler directives and general syntax closely follow the
5006 HPPA assembly language reference manual, with a few noteworthy differences.
5008 First, a colon may immediately follow a label definition. This is
5009 simply for compatibility with how most assembly language programmers
5012 Some obscure expression parsing problems may affect hand written code which
5013 uses the @code{spop} instructions, or code which makes significant
5014 use of the @code{!} line separator.
5016 @code{@value{AS}} is much less forgiving about missing arguments and other
5017 similar oversights than the HP assembler. @code{@value{AS}} notifies you
5018 of missing arguments as syntax errors; this is regarded as a feature, not a
5021 Finally, @code{@value{AS}} allows you to use an external symbol without
5022 explicitly importing the symbol. @emph{Warning:} in the future this will be
5023 an error for HPPA targets.
5025 Special characters for HPPA targets include:
5027 @samp{;} is the line comment character.
5029 @samp{!} can be used instead of a newline to separate statements.
5031 Since @samp{$} has no special meaning, you may use it in symbol names.
5033 @node HPPA Floating Point
5034 @section Floating Point
5035 @cindex floating point, HPPA (@sc{ieee})
5036 @cindex HPPA floating point (@sc{ieee})
5037 The HPPA family uses @sc{ieee} floating-point numbers.
5039 @node HPPA Directives
5040 @section HPPA Assembler Directives
5042 @code{@value{AS}} for the HPPA supports many additional directives for
5043 compatibility with the native assembler. This section describes them only
5044 briefly. For detailed information on HPPA-specific assembler directives, see
5045 @cite{HP9000 Series 800 Assembly Language Reference Manual} (HP 92432-90001).
5047 @cindex HPPA directives not supported
5048 @code{@value{AS}} does @emph{not} support the following assembler directives
5049 described in the HP manual:
5058 @cindex @code{.param} on HPPA
5059 Beyond those implemented for compatibility, @code{@value{AS}} supports one
5060 additional assembler directive for the HPPA: @code{.param}. It conveys
5061 register argument locations for static functions. Its syntax closely follows
5062 the @code{.export} directive.
5064 @cindex HPPA-only directives
5065 These are the additional directives in @code{@value{AS}} for the HPPA:
5068 @item .block @var{n}
5069 @itemx .blockz @var{n}
5070 Reserve @var{n} bytes of storage, and initialize them to zero.
5073 Mark the beginning of a procedure call. Only the special case with @emph{no
5074 arguments} is allowed.
5076 @item .callinfo [ @var{param}=@var{value}, @dots{} ] [ @var{flag}, @dots{} ]
5077 Specify a number of parameters and flags that define the environment for a
5080 @var{param} may be any of @samp{frame} (frame size), @samp{entry_gr} (end of
5081 general register range), @samp{entry_fr} (end of float register range),
5082 @samp{entry_sr} (end of space register range).
5084 The values for @var{flag} are @samp{calls} or @samp{caller} (proc has
5085 subroutines), @samp{no_calls} (proc does not call subroutines), @samp{save_rp}
5086 (preserve return pointer), @samp{save_sp} (proc preserves stack pointer),
5087 @samp{no_unwind} (do not unwind this proc), @samp{hpux_int} (proc is interrupt
5091 Assemble into the standard section called @samp{$TEXT$}, subsection
5095 @item .copyright "@var{string}"
5096 In the SOM object format, insert @var{string} into the object code, marked as a
5101 @item .copyright "@var{string}"
5102 In the ELF object format, insert @var{string} into the object code, marked as a
5107 Not yet supported; the assembler rejects programs containing this directive.
5110 Mark the beginning of a procedure.
5113 Mark the end of a procedure.
5115 @item .export @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5116 Make a procedure @var{name} available to callers. @var{typ}, if present, must
5117 be one of @samp{absolute}, @samp{code} (ELF only, not SOM), @samp{data},
5118 @samp{entry}, @samp{data}, @samp{entry}, @samp{millicode}, @samp{plabel},
5119 @samp{pri_prog}, or @samp{sec_prog}.
5121 @var{param}, if present, provides either relocation information for the
5122 procedure arguments and result, or a privilege level. @var{param} may be
5123 @samp{argw@var{n}} (where @var{n} ranges from @code{0} to @code{3}, and
5124 indicates one of four one-word arguments); @samp{rtnval} (the procedure's
5125 result); or @samp{priv_lev} (privilege level). For arguments or the result,
5126 @var{r} specifies how to relocate, and must be one of @samp{no} (not
5127 relocatable), @samp{gr} (argument is in general register), @samp{fr} (in
5128 floating point register), or @samp{fu} (upper half of float register).
5129 For @samp{priv_lev}, @var{r} is an integer.
5132 Define a two-byte integer constant @var{n}; synonym for the portable
5133 @code{@value{AS}} directive @code{.short}.
5135 @item .import @var{name} [ ,@var{typ} ]
5136 Converse of @code{.export}; make a procedure available to call. The arguments
5137 use the same conventions as the first two arguments for @code{.export}.
5139 @item .label @var{name}
5140 Define @var{name} as a label for the current assembly location.
5143 Not yet supported; the assembler rejects programs containing this directive.
5145 @item .origin @var{lc}
5146 Advance location counter to @var{lc}. Synonym for the @code{@value{as}}
5147 portable directive @code{.org}.
5149 @item .param @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5150 @c Not in HP manual; GNU HPPA extension
5151 Similar to @code{.export}, but used for static procedures.
5154 Use preceding the first statement of a procedure.
5157 Use following the last statement of a procedure.
5159 @item @var{label} .reg @var{expr}
5160 @c ?? Not in HP manual (Jan 1988 vn)
5161 Synonym for @code{.equ}; define @var{label} with the absolute expression
5162 @var{expr} as its value.
5164 @item .space @var{secname} [ ,@var{params} ]
5165 Switch to section @var{secname}, creating a new section by that name if
5166 necessary. You may only use @var{params} when creating a new section, not
5167 when switching to an existing one. @var{secname} may identify a section by
5168 number rather than by name.
5170 If specified, the list @var{params} declares attributes of the section,
5171 identified by keywords. The keywords recognized are @samp{spnum=@var{exp}}
5172 (identify this section by the number @var{exp}, an absolute expression),
5173 @samp{sort=@var{exp}} (order sections according to this sort key when linking;
5174 @var{exp} is an absolute expression), @samp{unloadable} (section contains no
5175 loadable data), @samp{notdefined} (this section defined elsewhere), and
5176 @samp{private} (data in this section not available to other programs).
5178 @item .spnum @var{secnam}
5179 @c ?? Not in HP manual (Jan 1988)
5180 Allocate four bytes of storage, and initialize them with the section number of
5181 the section named @var{secnam}. (You can define the section number with the
5182 HPPA @code{.space} directive.)
5184 @item .string "@var{str}"
5185 @cindex @code{string} directive on HPPA
5186 Copy the characters in the string @var{str} to the object file.
5187 @xref{Strings,,Strings}, for information on escape sequences you can use in
5188 @code{@value{AS}} strings.
5190 @emph{Warning!} The HPPA version of @code{.string} differs from the
5191 usual @code{@value{AS}} definition: it does @emph{not} write a zero byte
5192 after copying @var{str}.
5194 @item .stringz "@var{str}"
5195 Like @code{.string}, but appends a zero byte after copying @var{str} to object
5198 @item .subspa @var{name} [ ,@var{params} ]
5199 Similar to @code{.space}, but selects a subsection @var{name} within the
5200 current section. You may only specify @var{params} when you create a
5201 subsection (in the first instance of @code{.subspa} for this @var{name}).
5203 If specified, the list @var{params} declares attributes of the subsection,
5204 identified by keywords. The keywords recognized are @samp{quad=@var{expr}}
5205 (``quadrant'' for this subsection), @samp{align=@var{expr}} (alignment for
5206 beginning of this subsection; a power of two), @samp{access=@var{expr}} (value
5207 for ``access rights'' field), @samp{sort=@var{expr}} (sorting order for this
5208 subspace in link), @samp{code_only} (subsection contains only code),
5209 @samp{unloadable} (subsection cannot be loaded into memory), @samp{common}
5210 (subsection is common block), @samp{dup_comm} (initialized data may have
5211 duplicate names), or @samp{zero} (subsection is all zeros, do not write in
5214 @item .version "@var{str}"
5215 Write @var{str} as version identifier in object code.
5220 For detailed information on the HPPA machine instruction set, see
5221 @cite{PA-RISC Architecture and Instruction Set Reference Manual}
5228 @chapter Hitachi SH Dependent Features
5232 * SH Options:: Options
5233 * SH Syntax:: Syntax
5234 * SH Floating Point:: Floating Point
5235 * SH Directives:: SH Machine Directives
5236 * SH Opcodes:: Opcodes
5242 @cindex SH options (none)
5243 @cindex options, SH (none)
5244 @code{@value{AS}} has no additional command-line options for the Hitachi
5251 * SH-Chars:: Special Characters
5252 * SH-Regs:: Register Names
5253 * SH-Addressing:: Addressing Modes
5257 @subsection Special Characters
5259 @cindex line comment character, SH
5260 @cindex SH line comment character
5261 @samp{!} is the line comment character.
5263 @cindex line separator, SH
5264 @cindex statement separator, SH
5265 @cindex SH line separator
5266 You can use @samp{;} instead of a newline to separate statements.
5268 @cindex symbol names, @samp{$} in
5269 @cindex @code{$} in symbol names
5270 Since @samp{$} has no special meaning, you may use it in symbol names.
5273 @subsection Register Names
5275 @cindex SH registers
5276 @cindex registers, SH
5277 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
5278 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, @samp{r7}, @samp{r8},
5279 @samp{r9}, @samp{r10}, @samp{r11}, @samp{r12}, @samp{r13}, @samp{r14},
5280 and @samp{r15} to refer to the SH registers.
5282 The SH also has these control registers:
5286 procedure register (holds return address)
5293 high and low multiply accumulator registers
5299 global base register
5302 vector base register (for interrupt vectors)
5306 @subsection Addressing Modes
5308 @cindex addressing modes, SH
5309 @cindex SH addressing modes
5310 @code{@value{AS}} understands the following addressing modes for the SH.
5311 @code{R@var{n}} in the following refers to any of the numbered
5312 registers, but @emph{not} the control registers.
5322 Register indirect with pre-decrement
5325 Register indirect with post-increment
5327 @item @@(@var{disp}, R@var{n})
5328 Register indirect with displacement
5330 @item @@(R0, R@var{n})
5333 @item @@(@var{disp}, GBR)
5340 @itemx @@(@var{disp}, PC)
5341 PC relative address (for branch or for addressing memory). The
5342 @code{@value{AS}} implementation allows you to use the simpler form
5343 @var{addr} anywhere a PC relative address is called for; the alternate
5344 form is supported for compatibility with other assemblers.
5350 @node SH Floating Point
5351 @section Floating Point
5353 @cindex floating point, SH (@sc{ieee})
5354 @cindex SH floating point (@sc{ieee})
5355 The SH family uses @sc{ieee} floating-point numbers.
5358 @section SH Machine Directives
5360 @cindex SH machine directives (none)
5361 @cindex machine directives, SH (none)
5362 @cindex @code{word} directive, SH
5363 @cindex @code{int} directive, SH
5364 @code{@value{AS}} has no machine-dependent directives for the SH.
5369 @cindex SH opcode summary
5370 @cindex opcode summary, SH
5371 @cindex mnemonics, SH
5372 @cindex instruction summary, SH
5373 For detailed information on the SH machine instruction set, see
5374 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
5376 @code{@value{AS}} implements all the standard SH opcodes. No additional
5377 pseudo-instructions are needed on this family. Note, however, that
5378 because @code{@value{AS}} supports a simpler form of PC-relative
5379 addressing, you may simply write (for example)
5386 where other assemblers might require an explicit displacement to
5387 @code{bar} from the program counter:
5390 mov.l @@(@var{disp}, PC)
5394 @c this table, due to the multi-col faking and hardcoded order, looks silly
5395 @c except in smallbook. See comments below "@set SMALL" near top of this file.
5397 Here is a summary of SH opcodes:
5402 Rn @r{a numbered register}
5403 Rm @r{another numbered register}
5404 #imm @r{immediate data}
5405 disp @r{displacement}
5406 disp8 @r{8-bit displacement}
5407 disp12 @r{12-bit displacement}
5409 add #imm,Rn lds.l @@Rn+,PR
5410 add Rm,Rn mac.w @@Rm+,@@Rn+
5411 addc Rm,Rn mov #imm,Rn
5412 addv Rm,Rn mov Rm,Rn
5413 and #imm,R0 mov.b Rm,@@(R0,Rn)
5414 and Rm,Rn mov.b Rm,@@-Rn
5415 and.b #imm,@@(R0,GBR) mov.b Rm,@@Rn
5416 bf disp8 mov.b @@(disp,Rm),R0
5417 bra disp12 mov.b @@(disp,GBR),R0
5418 bsr disp12 mov.b @@(R0,Rm),Rn
5419 bt disp8 mov.b @@Rm+,Rn
5420 clrmac mov.b @@Rm,Rn
5421 clrt mov.b R0,@@(disp,Rm)
5422 cmp/eq #imm,R0 mov.b R0,@@(disp,GBR)
5423 cmp/eq Rm,Rn mov.l Rm,@@(disp,Rn)
5424 cmp/ge Rm,Rn mov.l Rm,@@(R0,Rn)
5425 cmp/gt Rm,Rn mov.l Rm,@@-Rn
5426 cmp/hi Rm,Rn mov.l Rm,@@Rn
5427 cmp/hs Rm,Rn mov.l @@(disp,Rn),Rm
5428 cmp/pl Rn mov.l @@(disp,GBR),R0
5429 cmp/pz Rn mov.l @@(disp,PC),Rn
5430 cmp/str Rm,Rn mov.l @@(R0,Rm),Rn
5431 div0s Rm,Rn mov.l @@Rm+,Rn
5433 div1 Rm,Rn mov.l R0,@@(disp,GBR)
5434 exts.b Rm,Rn mov.w Rm,@@(R0,Rn)
5435 exts.w Rm,Rn mov.w Rm,@@-Rn
5436 extu.b Rm,Rn mov.w Rm,@@Rn
5437 extu.w Rm,Rn mov.w @@(disp,Rm),R0
5438 jmp @@Rn mov.w @@(disp,GBR),R0
5439 jsr @@Rn mov.w @@(disp,PC),Rn
5440 ldc Rn,GBR mov.w @@(R0,Rm),Rn
5441 ldc Rn,SR mov.w @@Rm+,Rn
5442 ldc Rn,VBR mov.w @@Rm,Rn
5443 ldc.l @@Rn+,GBR mov.w R0,@@(disp,Rm)
5444 ldc.l @@Rn+,SR mov.w R0,@@(disp,GBR)
5445 ldc.l @@Rn+,VBR mova @@(disp,PC),R0
5447 lds Rn,MACL muls Rm,Rn
5448 lds Rn,PR mulu Rm,Rn
5449 lds.l @@Rn+,MACH neg Rm,Rn
5450 lds.l @@Rn+,MACL negc Rm,Rn
5453 not Rm,Rn stc.l GBR,@@-Rn
5454 or #imm,R0 stc.l SR,@@-Rn
5455 or Rm,Rn stc.l VBR,@@-Rn
5456 or.b #imm,@@(R0,GBR) sts MACH,Rn
5457 rotcl Rn sts MACL,Rn
5459 rotl Rn sts.l MACH,@@-Rn
5460 rotr Rn sts.l MACL,@@-Rn
5465 shar Rn swap.b Rm,Rn
5466 shll Rn swap.w Rm,Rn
5467 shll16 Rn tas.b @@Rn
5469 shll8 Rn tst #imm,R0
5471 shlr16 Rn tst.b #imm,@@(R0,GBR)
5472 shlr2 Rn xor #imm,R0
5474 sleep xor.b #imm,@@(R0,GBR)
5475 stc GBR,Rn xtrct Rm,Rn
5490 @node i960-Dependent
5491 @chapter Intel 80960 Dependent Features
5494 @node Machine Dependencies
5495 @chapter Intel 80960 Dependent Features
5498 @cindex i960 support
5500 * Options-i960:: i960 Command-line Options
5501 * Floating Point-i960:: Floating Point
5502 * Directives-i960:: i960 Machine Directives
5503 * Opcodes for i960:: i960 Opcodes
5506 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
5507 @c long as they're not turned on for other machines than 960.
5511 @section i960 Command-line Options
5513 @cindex i960 options
5514 @cindex options, i960
5517 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
5518 @cindex i960 architecture options
5519 @cindex architecture options, i960
5520 @cindex @code{-A} options, i960
5521 Select the 80960 architecture. Instructions or features not supported
5522 by the selected architecture cause fatal errors.
5524 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
5525 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
5527 If none of these options is specified, @code{@value{AS}} generates code for any
5528 instruction or feature that is supported by @emph{some} version of the
5529 960 (even if this means mixing architectures!). In principle,
5530 @code{@value{AS}} attempts to deduce the minimal sufficient processor
5531 type if none is specified; depending on the object code format, the
5532 processor type may be recorded in the object file. If it is critical
5533 that the @code{@value{AS}} output match a specific architecture, specify that
5534 architecture explicitly.
5537 @cindex @code{-b} option, i960
5538 @cindex branch recording, i960
5539 @cindex i960 branch recording
5540 Add code to collect information about conditional branches taken, for
5541 later optimization using branch prediction bits. (The conditional branch
5542 instructions have branch prediction bits in the CA, CB, and CC
5543 architectures.) If @var{BR} represents a conditional branch instruction,
5544 the following represents the code generated by the assembler when
5545 @samp{-b} is specified:
5548 call @var{increment routine}
5549 .word 0 # pre-counter
5551 call @var{increment routine}
5552 .word 0 # post-counter
5555 The counter following a branch records the number of times that branch
5556 was @emph{not} taken; the differenc between the two counters is the
5557 number of times the branch @emph{was} taken.
5559 @cindex @code{gbr960}, i960 postprocessor
5560 @cindex branch statistics table, i960
5561 A table of every such @code{Label} is also generated, so that the
5562 external postprocessor @code{gbr960} (supplied by Intel) can locate all
5563 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
5564 this is a local symbol to permit collecting statistics for many separate
5565 object files. The table is word aligned, and begins with a two-word
5566 header. The first word, initialized to 0, is used in maintaining linked
5567 lists of branch tables. The second word is a count of the number of
5568 entries in the table, which follow immediately: each is a word, pointing
5569 to one of the labels illustrated above.
5573 @c END TEXI2ROFF-KILL
5575 +------------+------------+------------+ ... +------------+
5577 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
5579 +------------+------------+------------+ ... +------------+
5581 __BRANCH_TABLE__ layout
5587 \line{\leftskip=0pt\hskip\tableindent
5588 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
5589 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
5590 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
5592 @c END TEXI2ROFF-KILL
5594 The first word of the header is used to locate multiple branch tables,
5595 since each object file may contain one. Normally the links are
5596 maintained with a call to an initialization routine, placed at the
5597 beginning of each function in the file. The GNU C compiler
5598 generates these calls automatically when you give it a @samp{-b} option.
5599 For further details, see the documentation of @samp{gbr960}.
5602 @cindex @code{-norelax} option, i960
5603 Normally, Compare-and-Branch instructions with targets that require
5604 displacements greater than 13 bits (or that have external targets) are
5605 replaced with the corresponding compare (or @samp{chkbit}) and branch
5606 instructions. You can use the @samp{-norelax} option to specify that
5607 @code{@value{AS}} should generate errors instead, if the target displacement
5608 is larger than 13 bits.
5610 This option does not affect the Compare-and-Jump instructions; the code
5611 emitted for them is @emph{always} adjusted when necessary (depending on
5612 displacement size), regardless of whether you use @samp{-norelax}.
5615 @node Floating Point-i960
5616 @section Floating Point
5618 @cindex floating point, i960 (@sc{ieee})
5619 @cindex i960 floating point (@sc{ieee})
5620 @code{@value{AS}} generates @sc{ieee} floating-point numbers for the directives
5621 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
5623 @node Directives-i960
5624 @section i960 Machine Directives
5626 @cindex machine directives, i960
5627 @cindex i960 machine directives
5630 @cindex @code{bss} directive, i960
5631 @item .bss @var{symbol}, @var{length}, @var{align}
5632 Reserve @var{length} bytes in the bss section for a local @var{symbol},
5633 aligned to the power of two specified by @var{align}. @var{length} and
5634 @var{align} must be positive absolute expressions. This directive
5635 differs from @samp{.lcomm} only in that it permits you to specify
5636 an alignment. @xref{Lcomm,,@code{.lcomm}}.
5640 @item .extended @var{flonums}
5641 @cindex @code{extended} directive, i960
5642 @code{.extended} expects zero or more flonums, separated by commas; for
5643 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
5644 floating-point number.
5646 @item .leafproc @var{call-lab}, @var{bal-lab}
5647 @cindex @code{leafproc} directive, i960
5648 You can use the @samp{.leafproc} directive in conjunction with the
5649 optimized @code{callj} instruction to enable faster calls of leaf
5650 procedures. If a procedure is known to call no other procedures, you
5651 may define an entry point that skips procedure prolog code (and that does
5652 not depend on system-supplied saved context), and declare it as the
5653 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
5654 entry point that goes through the normal prolog, you can specify that
5655 entry point as @var{call-lab}.
5657 A @samp{.leafproc} declaration is meant for use in conjunction with the
5658 optimized call instruction @samp{callj}; the directive records the data
5659 needed later to choose between converting the @samp{callj} into a
5660 @code{bal} or a @code{call}.
5662 @var{call-lab} is optional; if only one argument is present, or if the
5663 two arguments are identical, the single argument is assumed to be the
5664 @code{bal} entry point.
5666 @item .sysproc @var{name}, @var{index}
5667 @cindex @code{sysproc} directive, i960
5668 The @samp{.sysproc} directive defines a name for a system procedure.
5669 After you define it using @samp{.sysproc}, you can use @var{name} to
5670 refer to the system procedure identified by @var{index} when calling
5671 procedures with the optimized call instruction @samp{callj}.
5673 Both arguments are required; @var{index} must be between 0 and 31
5677 @node Opcodes for i960
5678 @section i960 Opcodes
5680 @cindex opcodes, i960
5681 @cindex i960 opcodes
5682 All Intel 960 machine instructions are supported;
5683 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
5684 selecting the instruction subset for a particular 960
5685 architecture.@refill
5687 Some opcodes are processed beyond simply emitting a single corresponding
5688 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
5689 instructions with target displacements larger than 13 bits.
5692 * callj-i960:: @code{callj}
5693 * Compare-and-branch-i960:: Compare-and-Branch
5697 @subsection @code{callj}
5699 @cindex @code{callj}, i960 pseudo-opcode
5700 @cindex i960 @code{callj} pseudo-opcode
5701 You can write @code{callj} to have the assembler or the linker determine
5702 the most appropriate form of subroutine call: @samp{call},
5703 @samp{bal}, or @samp{calls}. If the assembly source contains
5704 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
5705 defining the operand---then @code{@value{AS}} translates the
5706 @code{callj}; if not, it simply emits the @code{callj}, leaving it
5707 for the linker to resolve.
5709 @node Compare-and-branch-i960
5710 @subsection Compare-and-Branch
5712 @cindex i960 compare/branch instructions
5713 @cindex compare/branch instructions, i960
5714 The 960 architectures provide combined Compare-and-Branch instructions
5715 that permit you to store the branch target in the lower 13 bits of the
5716 instruction word itself. However, if you specify a branch target far
5717 enough away that its address won't fit in 13 bits, the assembler can
5718 either issue an error, or convert your Compare-and-Branch instruction
5719 into separate instructions to do the compare and the branch.
5721 @cindex compare and jump expansions, i960
5722 @cindex i960 compare and jump expansions
5723 Whether @code{@value{AS}} gives an error or expands the instruction depends
5724 on two choices you can make: whether you use the @samp{-norelax} option,
5725 and whether you use a ``Compare and Branch'' instruction or a ``Compare
5726 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
5727 expanded if necessary; the ``Branch'' instructions are expanded when
5728 necessary @emph{unless} you specify @code{-norelax}---in which case
5729 @code{@value{AS}} gives an error instead.
5731 These are the Compare-and-Branch instructions, their ``Jump'' variants,
5732 and the instruction pairs they may expand into:
5736 @c END TEXI2ROFF-KILL
5739 Branch Jump Expanded to
5740 ------ ------ ------------
5743 cmpibe cmpije cmpi; be
5744 cmpibg cmpijg cmpi; bg
5745 cmpibge cmpijge cmpi; bge
5746 cmpibl cmpijl cmpi; bl
5747 cmpible cmpijle cmpi; ble
5748 cmpibno cmpijno cmpi; bno
5749 cmpibne cmpijne cmpi; bne
5750 cmpibo cmpijo cmpi; bo
5751 cmpobe cmpoje cmpo; be
5752 cmpobg cmpojg cmpo; bg
5753 cmpobge cmpojge cmpo; bge
5754 cmpobl cmpojl cmpo; bl
5755 cmpoble cmpojle cmpo; ble
5756 cmpobne cmpojne cmpo; bne
5762 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
5763 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
5764 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
5765 bbc& & chkbit; bno\cr
5766 bbs& & chkbit; bo\cr
5767 cmpibe& cmpije& cmpi; be\cr
5768 cmpibg& cmpijg& cmpi; bg\cr
5769 cmpibge& cmpijge& cmpi; bge\cr
5770 cmpibl& cmpijl& cmpi; bl\cr
5771 cmpible& cmpijle& cmpi; ble\cr
5772 cmpibno& cmpijno& cmpi; bno\cr
5773 cmpibne& cmpijne& cmpi; bne\cr
5774 cmpibo& cmpijo& cmpi; bo\cr
5775 cmpobe& cmpoje& cmpo; be\cr
5776 cmpobg& cmpojg& cmpo; bg\cr
5777 cmpobge& cmpojge& cmpo; bge\cr
5778 cmpobl& cmpojl& cmpo; bl\cr
5779 cmpoble& cmpojle& cmpo; ble\cr
5780 cmpobne& cmpojne& cmpo; bne\cr}
5782 @c END TEXI2ROFF-KILL
5788 @node M68K-Dependent
5789 @chapter M680x0 Dependent Features
5792 @node Machine Dependencies
5793 @chapter M680x0 Dependent Features
5796 @cindex M680x0 support
5798 * M68K-Opts:: M680x0 Options
5799 * M68K-Syntax:: Syntax
5800 * M68K-Moto-Syntax:: Motorola Syntax
5801 * M68K-Float:: Floating Point
5802 * M68K-Directives:: 680x0 Machine Directives
5803 * M68K-opcodes:: Opcodes
5807 @section M680x0 Options
5809 @cindex options, M680x0
5810 @cindex M680x0 options
5811 The Motorola 680x0 version of @code{@value{AS}} has two machine dependent options.
5812 One shortens undefined references from 32 to 16 bits, while the
5813 other is used to tell @code{@value{AS}} what kind of machine it is
5816 @cindex @code{-l} option, M680x0
5817 You can use the @samp{-l} option to shorten the size of references to undefined
5818 symbols. If you do not use the @samp{-l} option, references to undefined
5819 symbols are wide enough for a full @code{long} (32 bits). (Since
5820 @code{@value{AS}} cannot know where these symbols end up, @code{@value{AS}} can
5821 only allocate space for the linker to fill in later. Since @code{@value{AS}}
5822 doesn't know how far away these symbols are, it allocates as much space as it
5823 can.) If you use this option, the references are only one word wide (16 bits).
5824 This may be useful if you want the object file to be as small as possible, and
5825 you know that the relevant symbols are always less than 17 bits away.
5827 @cindex @code{-m68000} and related options
5828 @cindex architecture options, M680x0
5829 @cindex M680x0 architecture options
5830 The 680x0 version of @code{@value{AS}} is most frequently used to assemble
5831 programs for the Motorola MC68020 microprocessor. Occasionally it is
5832 used to assemble programs for the mostly similar, but slightly different
5833 MC68000 or MC68010 microprocessors. You can give @code{@value{AS}} the options
5834 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
5835 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
5842 This syntax for the Motorola 680x0 was developed at @sc{mit}.
5844 @cindex M680x0 syntax
5845 @cindex syntax, M680x0
5846 @cindex M680x0 size modifiers
5847 @cindex size modifiers, M680x0
5848 The 680x0 version of @code{@value{AS}} uses syntax compatible with the Sun
5849 assembler. Intervening periods are ignored; for example, @samp{movl} is
5850 equivalent to @samp{move.l}.
5853 If @code{@value{AS}} is compiled with SUN_ASM_SYNTAX defined, it
5854 also allows Sun-style local labels of the form @samp{1$} through
5858 In the following table @dfn{apc} stands for any of the address
5859 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
5860 Program Counter (@samp{pc}), or the zero-address relative to the
5861 program counter (@samp{zpc}).
5863 @cindex M680x0 addressing modes
5864 @cindex addressing modes, M680x0
5865 The following addressing modes are understood:
5868 @samp{#@var{digits}}
5871 @samp{d0} through @samp{d7}
5873 @item Address Register
5874 @samp{a0} through @samp{a7}@*
5875 @samp{a7} is also known as @samp{sp}, i.e. the Stack Pointer. @code{a6}
5876 is also known as @samp{fp}, the Frame Pointer.
5878 @item Address Register Indirect
5879 @samp{a0@@} through @samp{a7@@}
5881 @item Address Register Postincrement
5882 @samp{a0@@+} through @samp{a7@@+}
5884 @item Address Register Predecrement
5885 @samp{a0@@-} through @samp{a7@@-}
5887 @item Indirect Plus Offset
5888 @samp{@var{apc}@@(@var{digits})}
5891 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
5893 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
5896 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
5898 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
5901 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5903 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5905 @item Memory Indirect
5906 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
5909 @samp{@var{symbol}}, or @samp{@var{digits}}
5911 @c pesch@cygnus.com: gnu, rich concur the following needs careful
5912 @c research before documenting.
5913 , or either of the above followed
5914 by @samp{:b}, @samp{:w}, or @samp{:l}.
5918 For some configurations, especially those where the compiler normally
5919 does not prepend an underscore to the names of user variables, the
5920 assembler requires a @samp{%} before any use of a register name. This
5921 is intended to let the assembler distinguish between user variables and
5922 registers named @samp{a0} through @samp{a7}, and so on. The @samp{%} is
5923 always accepted, but is only required for some configurations, notably
5926 @node M68K-Moto-Syntax
5927 @section Motorola Syntax
5929 @cindex Motorola syntax for the 680x0
5930 @cindex alternate syntax for the 680x0
5932 The standard Motorola syntax for this chip differs from the syntax
5933 already discussed (@pxref{M68K-Syntax,,Syntax}). @code{@value{AS}} can
5934 accept both kinds of syntax, even within a single instruction. The
5935 two kinds of syntax are fully compatible.
5937 @c FIXME! I can't figure out what this means. Surely the "always" is in some
5938 @c restricted context, for instance. It's not necessary for the preceding text
5939 @c to explain this, so just ignore it for now; re-enable someday when someone
5940 @c has time to explain it better.
5941 , because the Motorola syntax never uses
5942 the @samp{@@} character and the @sc{mit} syntax always does, except in
5943 cases where the syntaxes are identical.
5946 @cindex M680x0 syntax
5947 @cindex syntax, M680x0
5948 In particular, you may write or generate M68K assembler with the
5949 following conventions:
5951 (In the following table @dfn{apc} stands for any of the address
5952 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
5953 Program Counter (@samp{pc}), or the zero-address relative to the
5954 program counter (@samp{zpc}).)
5956 @cindex M680x0 addressing modes
5957 @cindex addressing modes, M680x0
5958 The following additional addressing modes are understood:
5960 @item Address Register Indirect
5961 @samp{a0} through @samp{a7}@*
5962 @samp{a7} is also known as @samp{sp}, i.e. the Stack Pointer. @code{a6}
5963 is also known as @samp{fp}, the Frame Pointer.
5965 @item Address Register Postincrement
5966 @samp{(a0)+} through @samp{(a7)+}
5968 @item Address Register Predecrement
5969 @samp{-(a0)} through @samp{-(a7)}
5971 @item Indirect Plus Offset
5972 @samp{@var{digits}(@var{apc})}
5975 @samp{@var{digits}(@var{apc},(@var{register}.@var{size}*@var{scale})}@*
5976 or @samp{(@var{apc},@var{register}.@var{size}*@var{scale})}@*
5977 In either case, @var{size} and @var{scale} are optional
5978 (@var{scale} defaults to @samp{1}, @var{size} defaults to @samp{l}).
5979 @var{scale} can be @samp{1}, @samp{2}, @samp{4}, or @samp{8}.
5980 @var{size} can be @samp{w} or @samp{l}. @var{scale} is only supported
5981 on the 68020 and greater.
5985 @section Floating Point
5987 @cindex floating point, M680x0
5988 @cindex M680x0 floating point
5989 @c FIXME is this "not too well tested" crud STILL true?
5990 The floating point code is not too well tested, and may have
5993 Packed decimal (P) format floating literals are not supported.
5994 Feel free to add the code!
5996 The floating point formats generated by directives are these.
6000 @cindex @code{float} directive, M680x0
6001 @code{Single} precision floating point constants.
6004 @cindex @code{double} directive, M680x0
6005 @code{Double} precision floating point constants.
6008 There is no directive to produce regions of memory holding
6009 extended precision numbers, however they can be used as
6010 immediate operands to floating-point instructions. Adding a
6011 directive to create extended precision numbers would not be
6012 hard, but it has not yet seemed necessary.
6014 @node M68K-Directives
6015 @section 680x0 Machine Directives
6017 @cindex M680x0 directives
6018 @cindex directives, M680x0
6019 In order to be compatible with the Sun assembler the 680x0 assembler
6020 understands the following directives.
6024 @cindex @code{data1} directive, M680x0
6025 This directive is identical to a @code{.data 1} directive.
6028 @cindex @code{data2} directive, M680x0
6029 This directive is identical to a @code{.data 2} directive.
6032 @cindex @code{even} directive, M680x0
6033 This directive is identical to a @code{.align 1} directive.
6034 @c Is this true? does it work???
6037 @cindex @code{skip} directive, M680x0
6038 This directive is identical to a @code{.space} directive.
6045 @cindex M680x0 opcodes
6046 @cindex opcodes, M680x0
6047 @cindex instruction set, M680x0
6048 @c pesch@cygnus.com: I don't see any point in the following
6049 @c paragraph. Bugs are bugs; how does saying this
6052 Danger: Several bugs have been found in the opcode table (and
6053 fixed). More bugs may exist. Be careful when using obscure
6058 * M68K-Branch:: Branch Improvement
6059 * M68K-Chars:: Special Characters
6063 @subsection Branch Improvement
6065 @cindex pseudo-opcodes, M680x0
6066 @cindex M680x0 pseudo-opcodes
6067 @cindex branch improvement, M680x0
6068 @cindex M680x0 branch improvement
6069 Certain pseudo opcodes are permitted for branch instructions.
6070 They expand to the shortest branch instruction that reach the
6071 target. Generally these mnemonics are made by substituting @samp{j} for
6072 @samp{b} at the start of a Motorola mnemonic.
6074 The following table summarizes the pseudo-operations. A @code{*} flags
6075 cases that are more fully described after the table:
6079 +-------------------------------------------------
6081 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
6082 +-------------------------------------------------
6083 jbsr |bsrs bsr bsrl jsr jsr
6084 jra |bras bra bral jmp jmp
6085 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
6086 * dbXX |dbXX dbXX dbXX; bra; jmpl
6087 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
6090 NX: negative of condition XX
6093 @center @code{*}---see full description below
6098 These are the simplest jump pseudo-operations; they always map to one
6099 particular machine instruction, depending on the displacement to the
6103 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
6104 where @var{XX} is a conditional branch or condition-code test. The full
6105 list of pseudo-ops in this family is:
6107 jhi jls jcc jcs jne jeq jvc
6108 jvs jpl jmi jge jlt jgt jle
6111 For the cases of non-PC relative displacements and long displacements on
6112 the 68000 or 68010, @code{@value{AS}} issues a longer code fragment in terms of
6113 @var{NX}, the opposite condition to @var{XX}. For example, for the
6114 non-PC relative case:
6126 The full family of pseudo-operations covered here is
6128 dbhi dbls dbcc dbcs dbne dbeq dbvc
6129 dbvs dbpl dbmi dbge dblt dbgt dble
6133 Other than for word and byte displacements, when the source reads
6134 @samp{db@var{XX} foo}, @code{@value{AS}} emits
6143 This family includes
6145 fjne fjeq fjge fjlt fjgt fjle fjf
6146 fjt fjgl fjgle fjnge fjngl fjngle fjngt
6147 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
6148 fjor fjseq fjsf fjsne fjst fjueq fjuge
6149 fjugt fjule fjult fjun
6152 For branch targets that are not PC relative, @code{@value{AS}} emits
6158 when it encounters @samp{fj@var{XX} foo}.
6163 @subsection Special Characters
6165 @cindex special characters, M680x0
6166 @cindex M680x0 immediate character
6167 @cindex immediate character, M680x0
6168 @cindex M680x0 line comment character
6169 @cindex line comment character, M680x0
6170 @cindex comments, M680x0
6171 The immediate character is @samp{#} for Sun compatibility. The
6172 line-comment character is @samp{|}. If a @samp{#} appears at the
6173 beginning of a line, it is treated as a comment unless it looks like
6174 @samp{# line file}, in which case it is treated normally.
6178 @c FIXME! Stop ignoring when filled in.
6183 The 32x32 version of @code{@value{AS}} accepts a @samp{-m32032} option to
6184 specify thiat it is compiling for a 32032 processor, or a
6185 @samp{-m32532} to specify that it is compiling for a 32532 option.
6186 The default (if neither is specified) is chosen when the assembler
6190 I don't know anything about the 32x32 syntax assembled by
6191 @code{@value{AS}}. Someone who undersands the processor (I've never seen
6192 one) and the possible syntaxes should write this section.
6194 @section Floating Point
6195 The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{AS}}
6196 only creates single or double precision values. I don't know if the
6197 32x32 understands extended precision numbers.
6199 @section 32x32 Machine Directives
6200 The 32x32 has no machine dependent directives.
6206 @node Sparc-Dependent
6207 @chapter SPARC Dependent Features
6210 @node Machine Dependencies
6211 @chapter SPARC Dependent Features
6214 @cindex SPARC support
6216 * Sparc-Opts:: Options
6217 * Sparc-Float:: Floating Point
6218 * Sparc-Directives:: Sparc Machine Directives
6224 @cindex options for SPARC
6225 @cindex SPARC options
6226 @cindex architectures, SPARC
6227 @cindex SPARC architectures
6228 The SPARC chip family includes several successive levels (or other
6229 variants) of chip, using the same core instruction set, but including
6230 a few additional instructions at each level.
6232 By default, @code{@value{AS}} assumes the core instruction set (SPARC
6233 v6), but ``bumps'' the architecture level as needed: it switches to
6234 successively higher architectures as it encounters instructions that
6235 only exist in the higher levels.
6238 @item -Av6 | -Av7 | -Av8 | -Asparclite
6243 Use one of the @samp{-A} options to select one of the SPARC
6244 architectures explicitly. If you select an architecture explicitly,
6245 @code{@value{AS}} reports a fatal error if it encounters an instruction
6246 or feature requiring a higher level.
6249 Permit the assembler to ``bump'' the architecture level as required, but
6250 warn whenever it is necessary to switch to another level.
6254 @c FIXME: (sparc) Fill in "syntax" section!
6255 @c subsection syntax
6256 I don't know anything about Sparc syntax. Someone who does
6257 will have to write this section.
6261 @section Floating Point
6263 @cindex floating point, SPARC (@sc{ieee})
6264 @cindex SPARC floating point (@sc{ieee})
6265 The Sparc uses @sc{ieee} floating-point numbers.
6267 @node Sparc-Directives
6268 @section Sparc Machine Directives
6270 @cindex SPARC machine directives
6271 @cindex machine directives, SPARC
6272 The Sparc version of @code{@value{AS}} supports the following additional
6277 @cindex @code{common} directive, SPARC
6278 This must be followed by a symbol name, a positive number, and
6279 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
6280 syntax is different.
6283 @cindex @code{half} directive, SPARC
6284 This is functionally identical to @code{.short}.
6287 @cindex @code{proc} directive, SPARC
6288 This directive is ignored. Any text following it on the same
6289 line is also ignored.
6292 @cindex @code{reserve} directive, SPARC
6293 This must be followed by a symbol name, a positive number, and
6294 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
6295 syntax is different.
6298 @cindex @code{seg} directive, SPARC
6299 This must be followed by @code{"text"}, @code{"data"}, or
6300 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
6304 @cindex @code{skip} directive, SPARC
6305 This is functionally identical to the @code{.space} directive.
6308 @cindex @code{word} directive, SPARC
6309 On the Sparc, the .word directive produces 32 bit values,
6310 instead of the 16 bit values it produces on many other machines.
6317 @node i386-Dependent
6318 @chapter 80386 Dependent Features
6321 @node Machine Dependencies
6322 @chapter 80386 Dependent Features
6325 @cindex i386 support
6326 @cindex i80306 support
6328 * i386-Options:: Options
6329 * i386-Syntax:: AT&T Syntax versus Intel Syntax
6330 * i386-Opcodes:: Opcode Naming
6331 * i386-Regs:: Register Naming
6332 * i386-prefixes:: Opcode Prefixes
6333 * i386-Memory:: Memory References
6334 * i386-jumps:: Handling of Jump Instructions
6335 * i386-Float:: Floating Point
6336 * i386-Notes:: Notes
6342 @cindex options for i386 (none)
6343 @cindex i386 options (none)
6344 The 80386 has no machine dependent options.
6347 @section AT&T Syntax versus Intel Syntax
6349 @cindex i386 syntax compatibility
6350 @cindex syntax compatibility, i386
6351 In order to maintain compatibility with the output of @code{@value{GCC}},
6352 @code{@value{AS}} supports AT&T System V/386 assembler syntax. This is quite
6353 different from Intel syntax. We mention these differences because
6354 almost all 80386 documents used only Intel syntax. Notable differences
6355 between the two syntaxes are:
6359 @cindex immediate operands, i386
6360 @cindex i386 immediate operands
6361 @cindex register operands, i386
6362 @cindex i386 register operands
6363 @cindex jump/call operands, i386
6364 @cindex i386 jump/call operands
6365 @cindex operand delimiters, i386
6366 AT&T immediate operands are preceded by @samp{$}; Intel immediate
6367 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
6368 AT&T register operands are preceded by @samp{%}; Intel register operands
6369 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
6370 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
6373 @cindex i386 source, destination operands
6374 @cindex source, destination operands; i386
6375 AT&T and Intel syntax use the opposite order for source and destination
6376 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
6377 @samp{source, dest} convention is maintained for compatibility with
6378 previous Unix assemblers.
6381 @cindex opcode suffixes, i386
6382 @cindex sizes operands, i386
6383 @cindex i386 size suffixes
6384 In AT&T syntax the size of memory operands is determined from the last
6385 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
6386 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
6387 memory references. Intel syntax accomplishes this by prefixes memory
6388 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
6389 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
6390 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
6393 @cindex return instructions, i386
6394 @cindex i386 jump, call, return
6395 Immediate form long jumps and calls are
6396 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
6398 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
6400 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
6401 @samp{ret far @var{stack-adjust}}.
6404 @cindex sections, i386
6405 @cindex i386 sections
6406 The AT&T assembler does not provide support for multiple section
6407 programs. Unix style systems expect all programs to be single sections.
6411 @section Opcode Naming
6413 @cindex i386 opcode naming
6414 @cindex opcode naming, i386
6415 Opcode names are suffixed with one character modifiers which specify the
6416 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
6417 byte, word, and long operands. If no suffix is specified by an
6418 instruction and it contains no memory operands then @code{@value{AS}} tries to
6419 fill in the missing suffix based on the destination register operand
6420 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
6421 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
6422 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
6423 assembler which assumes that a missing opcode suffix implies long
6424 operand size. (This incompatibility does not affect compiler output
6425 since compilers always explicitly specify the opcode suffix.)
6427 Almost all opcodes have the same names in AT&T and Intel format. There
6428 are a few exceptions. The sign extend and zero extend instructions need
6429 two sizes to specify them. They need a size to sign/zero extend
6430 @emph{from} and a size to zero extend @emph{to}. This is accomplished
6431 by using two opcode suffixes in AT&T syntax. Base names for sign extend
6432 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
6433 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
6434 suffixes are tacked on to this base name, the @emph{from} suffix before
6435 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
6436 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
6437 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
6438 and @samp{wl} (from word to long).
6440 @cindex conversion instructions, i386
6441 @cindex i386 conversion instructions
6442 The Intel-syntax conversion instructions
6446 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
6449 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
6452 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
6455 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
6459 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
6460 AT&T naming. @code{@value{AS}} accepts either naming for these instructions.
6462 @cindex jump instructions, i386
6463 @cindex call instructions, i386
6464 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
6465 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
6469 @section Register Naming
6471 @cindex i386 registers
6472 @cindex registers, i386
6473 Register operands are always prefixes with @samp{%}. The 80386 registers
6478 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
6479 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
6480 frame pointer), and @samp{%esp} (the stack pointer).
6483 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
6484 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
6487 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
6488 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
6489 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
6490 @samp{%cx}, and @samp{%dx})
6493 the 6 section registers @samp{%cs} (code section), @samp{%ds}
6494 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
6498 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
6502 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
6503 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
6506 the 2 test registers @samp{%tr6} and @samp{%tr7}.
6509 the 8 floating point register stack @samp{%st} or equivalently
6510 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
6511 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
6515 @section Opcode Prefixes
6517 @cindex i386 opcode prefixes
6518 @cindex opcode prefixes, i386
6519 @cindex prefixes, i386
6520 Opcode prefixes are used to modify the following opcode. They are used
6521 to repeat string instructions, to provide section overrides, to perform
6522 bus lock operations, and to give operand and address size (16-bit
6523 operands are specified in an instruction by prefixing what would
6524 normally be 32-bit operands with a ``operand size'' opcode prefix).
6525 Opcode prefixes are usually given as single-line instructions with no
6526 operands, and must directly precede the instruction they act upon. For
6527 example, the @samp{scas} (scan string) instruction is repeated with:
6533 Here is a list of opcode prefixes:
6537 @cindex section override prefixes, i386
6538 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
6539 @samp{fs}, @samp{gs}. These are automatically added by specifying
6540 using the @var{section}:@var{memory-operand} form for memory references.
6543 @cindex size prefixes, i386
6544 Operand/Address size prefixes @samp{data16} and @samp{addr16}
6545 change 32-bit operands/addresses into 16-bit operands/addresses. Note
6546 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
6547 are not supported (yet).
6550 @cindex bus lock prefixes, i386
6551 @cindex inhibiting interrupts, i386
6552 The bus lock prefix @samp{lock} inhibits interrupts during
6553 execution of the instruction it precedes. (This is only valid with
6554 certain instructions; see a 80386 manual for details).
6557 @cindex coprocessor wait, i386
6558 The wait for coprocessor prefix @samp{wait} waits for the
6559 coprocessor to complete the current instruction. This should never be
6560 needed for the 80386/80387 combination.
6563 @cindex repeat prefixes, i386
6564 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
6565 to string instructions to make them repeat @samp{%ecx} times.
6569 @section Memory References
6571 @cindex i386 memory references
6572 @cindex memory references, i386
6573 An Intel syntax indirect memory reference of the form
6576 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
6580 is translated into the AT&T syntax
6583 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
6587 where @var{base} and @var{index} are the optional 32-bit base and
6588 index registers, @var{disp} is the optional displacement, and
6589 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
6590 to calculate the address of the operand. If no @var{scale} is
6591 specified, @var{scale} is taken to be 1. @var{section} specifies the
6592 optional section register for the memory operand, and may override the
6593 default section register (see a 80386 manual for section register
6594 defaults). Note that section overrides in AT&T syntax @emph{must} have
6595 be preceded by a @samp{%}. If you specify a section override which
6596 coincides with the default section register, @code{@value{AS}} does @emph{not}
6597 output any section register override prefixes to assemble the given
6598 instruction. Thus, section overrides can be specified to emphasize which
6599 section register is used for a given memory operand.
6601 Here are some examples of Intel and AT&T style memory references:
6604 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
6605 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
6606 missing, and the default section is used (@samp{%ss} for addressing with
6607 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
6609 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
6610 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
6611 @samp{foo}. All other fields are missing. The section register here
6612 defaults to @samp{%ds}.
6614 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
6615 This uses the value pointed to by @samp{foo} as a memory operand.
6616 Note that @var{base} and @var{index} are both missing, but there is only
6617 @emph{one} @samp{,}. This is a syntactic exception.
6619 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
6620 This selects the contents of the variable @samp{foo} with section
6621 register @var{section} being @samp{%gs}.
6624 Absolute (as opposed to PC relative) call and jump operands must be
6625 prefixed with @samp{*}. If no @samp{*} is specified, @code{@value{AS}}
6626 always chooses PC relative addressing for jump/call labels.
6628 Any instruction that has a memory operand @emph{must} specify its size (byte,
6629 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
6633 @section Handling of Jump Instructions
6635 @cindex jump optimization, i386
6636 @cindex i386 jump optimization
6637 Jump instructions are always optimized to use the smallest possible
6638 displacements. This is accomplished by using byte (8-bit) displacement
6639 jumps whenever the target is sufficiently close. If a byte displacement
6640 is insufficient a long (32-bit) displacement is used. We do not support
6641 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
6642 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
6643 @samp{%eip} to 16 bits after the word displacement is added.
6645 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
6646 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in byte
6647 displacements, so that if you use these instructions (@code{@value{GCC}} does
6648 not use them) you may get an error message (and incorrect code). The AT&T
6649 80386 assembler tries to get around this problem by expanding @samp{jcxz foo}
6660 @section Floating Point
6662 @cindex i386 floating point
6663 @cindex floating point, i386
6664 All 80387 floating point types except packed BCD are supported.
6665 (BCD support may be added without much difficulty). These data
6666 types are 16-, 32-, and 64- bit integers, and single (32-bit),
6667 double (64-bit), and extended (80-bit) precision floating point.
6668 Each supported type has an opcode suffix and a constructor
6669 associated with it. Opcode suffixes specify operand's data
6670 types. Constructors build these data types into memory.
6674 @cindex @code{float} directive, i386
6675 @cindex @code{single} directive, i386
6676 @cindex @code{double} directive, i386
6677 @cindex @code{tfloat} directive, i386
6678 Floating point constructors are @samp{.float} or @samp{.single},
6679 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
6680 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
6681 @samp{t} stands for temporary real, and that the 80387 only supports
6682 this format via the @samp{fldt} (load temporary real to stack top) and
6683 @samp{fstpt} (store temporary real and pop stack) instructions.
6686 @cindex @code{word} directive, i386
6687 @cindex @code{long} directive, i386
6688 @cindex @code{int} directive, i386
6689 @cindex @code{quad} directive, i386
6690 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
6691 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
6692 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
6693 (quad). As with the temporary real format the 64-bit @samp{q} format is
6694 only present in the @samp{fildq} (load quad integer to stack top) and
6695 @samp{fistpq} (store quad integer and pop stack) instructions.
6698 Register to register operations do not require opcode suffixes,
6699 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
6701 @cindex i386 @code{fwait} instruction
6702 @cindex @code{fwait instruction}, i386
6703 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
6704 instructions are almost never needed (this is not the case for the
6705 80286/80287 and 8086/8087 combinations). Therefore, @code{@value{AS}} suppresses
6706 the @samp{fwait} instruction whenever it is implicitly selected by one
6707 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
6708 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
6709 instructions are made equivalent to @samp{f@dots{}} instructions. If
6710 @samp{fwait} is desired it must be explicitly coded.
6715 @cindex i386 @code{mul}, @code{imul} instructions
6716 @cindex @code{mul} instruction, i386
6717 @cindex @code{imul} instruction, i386
6718 There is some trickery concerning the @samp{mul} and @samp{imul}
6719 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
6720 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
6721 for @samp{imul}) can be output only in the one operand form. Thus,
6722 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
6723 the expanding multiply would clobber the @samp{%edx} register, and this
6724 would confuse @code{@value{GCC}} output. Use @samp{imul %ebx} to get the
6725 64-bit product in @samp{%edx:%eax}.
6727 We have added a two operand form of @samp{imul} when the first operand
6728 is an immediate mode expression and the second operand is a register.
6729 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
6730 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
6737 @node Z8000-Dependent
6738 @chapter Z8000 Dependent Features
6741 @node Machine Dependencies
6742 @chapter Z8000 Dependent Features
6745 @cindex Z8000 support
6746 The Z8000 @value{AS} supports both members of the Z8000 family: the
6747 unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with
6750 When the assembler is in unsegmented mode (specified with the
6751 @code{unsegm} directive), an address takes up one word (16 bit)
6752 sized register. When the assembler is in segmented mode (specified with
6753 the @code{segm} directive), a 24-bit address takes up a long (32 bit)
6754 register. @xref{Z8000 Directives,,Assembler Directives for the Z8000},
6755 for a list of other Z8000 specific assembler directives.
6758 * Z8000 Options:: No special command-line options for Z8000
6759 * Z8000 Syntax:: Assembler syntax for the Z8000
6760 * Z8000 Directives:: Special directives for the Z8000
6761 * Z8000 Opcodes:: Opcodes
6767 @cindex Z8000 options
6768 @cindex options, Z8000
6769 @code{@value{AS}} has no additional command-line options for the Zilog
6775 * Z8000-Chars:: Special Characters
6776 * Z8000-Regs:: Register Names
6777 * Z8000-Addressing:: Addressing Modes
6781 @subsection Special Characters
6783 @cindex line comment character, Z8000
6784 @cindex Z8000 line comment character
6785 @samp{!} is the line comment character.
6787 @cindex line separator, Z8000
6788 @cindex statement separator, Z8000
6789 @cindex Z8000 line separator
6790 You can use @samp{;} instead of a newline to separate statements.
6793 @subsection Register Names
6795 @cindex Z8000 registers
6796 @cindex registers, Z8000
6797 The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer
6798 to different sized groups of registers by register number, with the
6799 prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and
6800 @samp{rq} for 64 bit registers. You can also refer to the contents of
6801 the first eight (of the sixteen 16 bit registers) by bytes. They are
6802 named @samp{r@var{n}h} and @samp{r@var{n}l}.
6805 @exdent @emph{byte registers}
6806 r0l r0h r1h r1l r2h r2l r3h r3l
6807 r4h r4l r5h r5l r6h r6l r7h r7l
6809 @exdent @emph{word registers}
6810 r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15
6812 @exdent @emph{long word registers}
6813 rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14
6815 @exdent @emph{quad word registers}
6819 @node Z8000-Addressing
6820 @subsection Addressing Modes
6822 @cindex addressing modes, Z8000
6823 @cindex Z800 addressing modes
6824 @value{AS} understands the following addressing modes for the Z8000:
6834 Direct: the 16 bit or 24 bit address (depending on whether the assembler
6835 is in segmented or unsegmented mode) of the operand is in the instruction.
6837 @item address(r@var{n})
6838 Indexed: the 16 or 24 bit address is added to the 16 bit register to produce
6839 the final address in memory of the operand.
6841 @item r@var{n}(#@var{imm})
6842 Base Address: the 16 or 24 bit register is added to the 16 bit sign
6843 extended immediate displacement to produce the final address in memory
6846 @item r@var{n}(r@var{m})
6847 Base Index: the 16 or 24 bit register r@var{n} is added to the sign
6848 extended 16 bit index register r@var{m} to produce the final address in
6849 memory of the operand.
6852 Immediate data @var{xx}.
6855 @node Z8000 Directives
6856 @section Assembler Directives for the Z8000
6858 @cindex Z8000 directives
6859 @cindex directives, Z8000
6860 The Z8000 port of @value{AS} includes these additional assembler directives,
6861 for compatibility with other Z8000 assemblers. As shown, these do not
6862 begin with @samp{.} (unlike the ordinary @value{AS} directives).
6867 Generates code for the segmented Z8001.
6871 Generates code for the unsegmented Z8002.
6875 Synonym for @code{.file}
6879 Synonum for @code{.global}
6883 Synonym for @code{.word}
6887 Synonym for @code{.long}
6891 Synonym for @code{.byte}
6895 Assemble a string. @code{sval} expects one string literal, delimited by
6896 single quotes. It assembles each byte of the string into consecutive
6897 addresses. You can use the escape sequence @samp{%@var{xx}} (where
6898 @var{xx} represents a two-digit hexadecimal number) to represent the
6899 character whose @sc{ascii} value is @var{xx}. Use this feature to
6900 describe single quote and other characters that may not appear in string
6901 literals as themselves. For example, the C statement @w{@samp{char *a =
6902 "he said \"it's 50% off\"";}} is represented in Z8000 assembly language
6903 (shown with the assembler output in hex at the left) as
6907 @let@nonarrowing=@comment
6910 68652073 sval 'he said %22it%27s 50%25 off%22%00'
6923 synonym for @code{.section}
6927 synonym for @code{.space}
6931 synonym for @code{.align 1}
6937 @cindex Z8000 opcode summary
6938 @cindex opcode summary, Z8000
6939 @cindex mnemonics, Z8000
6940 @cindex instruction summary, Z8000
6941 For detailed information on the Z8000 machine instruction set, see
6942 @cite{Z8000 Technical Manual}.
6945 @c this table, due to the multi-col faking and hardcoded order, looks silly
6946 @c except in smallbook. See comments below "@set SMALL" near top of this file.
6948 The following table summarizes the opcodes and their arguments:
6951 @let@nonarrowing=@comment
6955 rs @r{16 bit source register}
6956 rd @r{16 bit destination register}
6957 rbs @r{8 bit source register}
6958 rbd @r{8 bit destination register}
6959 rrs @r{32 bit source register}
6960 rrd @r{32 bit destination register}
6961 rqs @r{64 bit source register}
6962 rqd @r{64 bit destination register}
6963 addr @r{16/24 bit address}
6964 imm @r{immediate data}
6966 adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc
6967 adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc
6968 add rd,@@rs clrb rbd dab rbd
6969 add rd,addr com @@rd dbjnz rbd,disp7
6970 add rd,addr(rs) com addr dec @@rd,imm4m1
6971 add rd,imm16 com addr(rd) dec addr(rd),imm4m1
6972 add rd,rs com rd dec addr,imm4m1
6973 addb rbd,@@rs comb @@rd dec rd,imm4m1
6974 addb rbd,addr comb addr decb @@rd,imm4m1
6975 addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1
6976 addb rbd,imm8 comb rbd decb addr,imm4m1
6977 addb rbd,rbs comflg flags decb rbd,imm4m1
6978 addl rrd,@@rs cp @@rd,imm16 di i2
6979 addl rrd,addr cp addr(rd),imm16 div rrd,@@rs
6980 addl rrd,addr(rs) cp addr,imm16 div rrd,addr
6981 addl rrd,imm32 cp rd,@@rs div rrd,addr(rs)
6982 addl rrd,rrs cp rd,addr div rrd,imm16
6983 and rd,@@rs cp rd,addr(rs) div rrd,rs
6984 and rd,addr cp rd,imm16 divl rqd,@@rs
6985 and rd,addr(rs) cp rd,rs divl rqd,addr
6986 and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs)
6987 and rd,rs cpb addr(rd),imm8 divl rqd,imm32
6988 andb rbd,@@rs cpb addr,imm8 divl rqd,rrs
6989 andb rbd,addr cpb rbd,@@rs djnz rd,disp7
6990 andb rbd,addr(rs) cpb rbd,addr ei i2
6991 andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs
6992 andb rbd,rbs cpb rbd,imm8 ex rd,addr
6993 bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs)
6994 bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs
6995 bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs
6996 bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr
6997 bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs)
6998 bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs
6999 bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8
7000 bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8
7001 bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8
7002 bitb rbd,rs cpl rrd,@@rs ext8f imm8
7003 bpt cpl rrd,addr exts rrd
7004 call @@rd cpl rrd,addr(rs) extsb rd
7005 call addr cpl rrd,imm32 extsl rqd
7006 call addr(rd) cpl rrd,rrs halt
7007 calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs
7008 clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16
7009 clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs
7010 clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16
7011 clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1
7012 clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1
7013 inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs)
7014 inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16
7015 incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs
7016 incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs
7017 incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr
7018 incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs)
7019 ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32
7020 indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs
7021 inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd
7022 inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr
7023 iret ldib @@rd,@@rs,rr neg addr(rd)
7024 jp cc,@@rd ldir @@rd,@@rs,rr neg rd
7025 jp cc,addr ldirb @@rd,@@rs,rr negb @@rd
7026 jp cc,addr(rd) ldk rd,imm4 negb addr
7027 jr cc,disp8 ldl @@rd,rrs negb addr(rd)
7028 ld @@rd,imm16 ldl addr(rd),rrs negb rbd
7029 ld @@rd,rs ldl addr,rrs nop
7030 ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs
7031 ld addr(rd),rs ldl rd(rx),rrs or rd,addr
7032 ld addr,imm16 ldl rrd,@@rs or rd,addr(rs)
7033 ld addr,rs ldl rrd,addr or rd,imm16
7034 ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs
7035 ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs
7036 ld rd,@@rs ldl rrd,rrs orb rbd,addr
7037 ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs)
7038 ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8
7039 ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs
7040 ld rd,rs ldm addr(rd),rs,n out @@rd,rs
7041 ld rd,rs(imm16) ldm addr,rs,n out imm16,rs
7042 ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs
7043 lda rd,addr ldm rd,addr(rs),n outb imm16,rbs
7044 lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra
7045 lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba
7046 lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra
7047 ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra
7048 ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs
7049 ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs
7050 ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs
7051 ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs
7052 ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs
7053 ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs
7054 ldb rbd,@@rs mbit popl addr,@@rs
7055 ldb rbd,addr mreq rd popl rrd,@@rs
7056 ldb rbd,addr(rs) mres push @@rd,@@rs
7057 ldb rbd,imm8 mset push @@rd,addr
7058 ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs)
7059 ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16
7060 push @@rd,rs set addr,imm4 subl rrd,imm32
7061 pushl @@rd,@@rs set rd,imm4 subl rrd,rrs
7062 pushl @@rd,addr set rd,rs tcc cc,rd
7063 pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd
7064 pushl @@rd,rrs setb addr(rd),imm4 test @@rd
7065 res @@rd,imm4 setb addr,imm4 test addr
7066 res addr(rd),imm4 setb rbd,imm4 test addr(rd)
7067 res addr,imm4 setb rbd,rs test rd
7068 res rd,imm4 setflg imm4 testb @@rd
7069 res rd,rs sinb rbd,imm16 testb addr
7070 resb @@rd,imm4 sinb rd,imm16 testb addr(rd)
7071 resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd
7072 resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd
7073 resb rbd,imm4 sinib @@rd,@@rs,ra testl addr
7074 resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd)
7075 resflg imm4 sla rd,imm8 testl rrd
7076 ret cc slab rbd,imm8 trdb @@rd,@@rs,rba
7077 rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba
7078 rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr
7079 rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr
7080 rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr
7081 rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr
7082 rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr
7083 rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr
7084 rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd
7085 rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr
7086 rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd)
7087 rsvd36 sra rd,imm8 tset rd
7088 rsvd38 srab rbd,imm8 tsetb @@rd
7089 rsvd78 sral rrd,imm8 tsetb addr
7090 rsvd7e srl rd,imm8 tsetb addr(rd)
7091 rsvd9d srlb rbd,imm8 tsetb rbd
7092 rsvd9f srll rrd,imm8 xor rd,@@rs
7093 rsvdb9 sub rd,@@rs xor rd,addr
7094 rsvdbf sub rd,addr xor rd,addr(rs)
7095 sbc rd,rs sub rd,addr(rs) xor rd,imm16
7096 sbcb rbd,rbs sub rd,imm16 xor rd,rs
7097 sc imm8 sub rd,rs xorb rbd,@@rs
7098 sda rd,rs subb rbd,@@rs xorb rbd,addr
7099 sdab rbd,rs subb rbd,addr xorb rbd,addr(rs)
7100 sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8
7101 sdl rd,rs subb rbd,imm8 xorb rbd,rbs
7102 sdlb rbd,rs subb rbd,rbs xorb rbd,rbs
7103 sdll rrd,rs subl rrd,@@rs
7104 set @@rd,imm4 subl rrd,addr
7105 set addr(rd),imm4 subl rrd,addr(rs)
7117 @node MIPS-Dependent
7118 @chapter MIPS Dependent Features
7121 @node Machine Dependencies
7122 @chapter MIPS Dependent Features
7129 @sc{gnu} @code{@value{AS}} for @sc{mips} architectures supports the @sc{mips}
7130 @sc{r2000}, @sc{r3000}, @sc{r4000} and @sc{r6000} processors. For information
7131 about the @sc{mips} instruction set, see @cite{MIPS RISC Architecture}, by Kane
7132 and Heindrich (Prentice-Hall).
7135 * MIPS Opts:: Assembler options
7136 * MIPS Object:: ECOFF object code
7137 * MIPS Stabs:: Directives for debugging information
7138 * MIPS ISA:: Directives to override the ISA level
7142 @section Assembler options
7144 The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support three
7145 special options, and accept one other for command-line compatibility.
7148 @cindex @code{-G} option (MIPS)
7150 This option sets the largest size of an object that can be referenced
7151 implicitly with the @code{gp} register. It is only accepted for targets
7152 that use @sc{ecoff} format. The default value is 8.
7154 @cindex @code{-EB} option (MIPS)
7155 @cindex @code{-EL} option (MIPS)
7156 @cindex MIPS big-endian output
7157 @cindex MIPS little-endian output
7158 @cindex big-endian output, MIPS
7159 @cindex little-endian output, MIPS
7162 Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or
7163 little-endian output at run time (unlike the other @sc{gnu} development
7164 tools, which must be configured for one or the other). Use @samp{-EB}
7165 to select big-endian output, and @samp{-EL} for little-endian.
7167 @cindex @code{-nocpp} ignored (MIPS)
7169 This option is ignored. It is accepted for command-line compatibility with
7170 other assemblers, which use it to turn off C style preprocessing. With
7171 @sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the
7172 @sc{gnu} assembler itself never runs the C preprocessor.
7176 @section MIPS ECOFF object code
7178 @cindex ECOFF sections
7179 @cindex MIPS ECOFF sections
7180 Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections
7181 besides the usual @code{.text}, @code{.data} and @code{.bss}. The
7182 additional sections are @code{.rdata}, used for read-only data,
7183 @code{.sdata}, used for small data, and @code{.sbss}, used for small
7186 @cindex small objects, MIPS ECOFF
7187 @cindex @code{gp} register, MIPS
7188 When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28})
7189 register to form the address of a ``small object''. Any object in the
7190 @code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense.
7191 For external objects, or for objects in the @code{.bss} section, you can use
7192 the @sc{gcc} @samp{-G} option to control the size of objects addressed via
7193 @code{$gp}; the default value is 8, meaning that a reference to any object
7194 eight bytes or smaller uses @code{$gp}. Passing @samp{-G 0} to
7195 @code{@value{AS}} prevents it from using the @code{$gp} register on the basis
7196 of object size (but the assembler uses @code{$gp} for objects in @code{.sdata}
7197 or @code{sbss} in any case). The size of an object in the @code{.bss} section
7198 is set by the @code{.comm} or @code{.lcomm} directive that defines it. The
7199 size of an external object may be set with the @code{.extern} directive. For
7200 example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes
7201 in length, whie leaving @code{sym} otherwise undefined.
7203 Using small @sc{ecoff} objects requires linker support, and assumes that the
7204 @code{$gp} register is correctly initialized (normally done automatically by
7205 the startup code). @sc{mips} @sc{ecoff} assembly code must not modify the
7206 @code{$gp} register.
7209 @section Directives for debugging information
7211 @cindex MIPS debugging directives
7212 @sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for
7213 generating debugging information which are not support by traditional @sc{mips}
7214 assemblers. These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file},
7215 @code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val},
7216 @code{.stabd}, @code{.stabn}, and @code{.stabs}. The debugging information
7217 generated by the three @code{.stab} directives can only be read by @sc{gdb},
7218 not by traditional @sc{mips} debuggers (this enhancement is required to fully
7219 support C++ debugging). These directives are primarily used by compilers, not
7220 assembly language programmers!
7223 @section Directives to override the ISA level
7225 @cindex MIPS ISA override
7226 @sc{mips} @code{@value{AS}} supports an additional directive to change the
7227 @sc{mips} Instruction Set Architecture level on the fly. This is not supported
7228 by traditional @sc{mips} assemblers. The directive is @code{.set mips@var{N}}.
7229 @var{N} should be a number from 0 to 3. A value from 1 to 3 will cause gas to
7230 start accepting instructions for the given ISA level; this affects not only
7231 which instructions are permitted, but also how certain macros are expanded.
7232 @code{.set mips0} will set the ISA level back to that set by the command line
7233 options, if any, or otherwise to the default for the configuration. This
7234 feature may be used to permit specific r4000 instructions while assembling in
7235 32 bit mode. It must be used with care.
7240 @c reverse effect of @down at top of generic Machine-Dep chapter
7244 @node Acknowledgements
7245 @chapter Acknowledgements
7247 If you have contributed to @code{@value{AS}} and your name isn't listed here,
7248 it is not meant as a slight. We just don't know about it. Send mail to the
7249 maintainer, and we'll correct the situation. Currently (January 1994), the
7250 maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
7252 Dean Elsner wrote the original GNU assembler for the VAX.@footnote{Any more
7255 Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
7256 information and the 68k series machines, most of the preprocessing pass, and
7257 extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}.
7259 K. Richard Pixley maintained GAS for a while, adding various enhancements and
7260 many bug fixes, including merging support for several processors, breaking GAS
7261 up to handle multiple object file format back ends (including heavy rewrite,
7262 testing, an integration of the coff and b.out back ends), adding configuration
7263 including heavy testing and verification of cross assemblers and file splits
7264 and renaming, converted GAS to strictly ANSI C including full prototypes, added
7265 support for m680[34]0 and cpu32, did considerable work on i960 including a COFF
7266 port (including considerable amounts of reverse engineering), a SPARC opcode
7267 file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know''
7268 assertions and made them work, much other reorganization, cleanup, and lint.
7270 Ken Raeburn wrote the high-level BFD interface code to replace most of the code
7271 in format-specific I/O modules.
7273 The original VMS support was contributed by David L. Kashtan. Eric Youngdale
7274 has done much work with it since.
7276 The Intel 80386 machine description was written by Eliot Dresselhaus.
7278 Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
7280 The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
7281 University and Torbjorn Granlund of the Swedish Institute of Computer Science.
7283 Keith Knowles at the Open Software Foundation wrote the original MIPS back end
7284 (@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support
7285 (which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to
7286 support a.out format.
7288 Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k,
7289 tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
7290 Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
7291 use BFD for some low-level operations, for use with the H8/300 and AMD 29k
7294 John Gilmore built the AMD 29000 support, added @code{.include} support, and
7295 simplified the configuration of which versions accept which directives. He
7296 updated the 68k machine description so that Motorola's opcodes always produced
7297 fixed-size instructions (e.g. @code{jsr}), while synthetic instructions
7298 remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested
7299 cross-compilation support, and one bug in relaxation that took a week and
7300 required the proverbial one-bit fix.
7302 Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
7303 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
7304 added support for MIPS ECOFF and ELF targets, and made a few other minor
7307 Steve Chamberlain made @code{@value{AS}} able to generate listings.
7309 Hewlett-Packard contributed support for the HP9000/300.
7311 Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
7312 along with a fairly extensive HPPA testsuite (for both SOM and ELF object
7313 formats). This work was supported by both the Center for Software Science at
7314 the University of Utah and Cygnus Support.
7316 Support for ELF format files has been worked on by Mark Eichin of Cygnus
7317 Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
7318 Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
7319 Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
7320 and some initial 64-bit support).
7322 Several engineers at Cygnus Support have also provided many small bug fixes and
7323 configuration enhancements.
7325 Many others have contributed large or small bugfixes and enhancements. If
7326 you have contributed significant work and are not mentioned on this list, and
7327 want to be, let us know. Some of the history has been lost; we are not
7328 intentionally leaving anyone out.