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 asconfig.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.
74 * As: (as). The GNU assembler.
83 This file documents the GNU Assembler "@value{AS}".
85 Copyright (C) 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
87 Permission is granted to make and distribute verbatim copies of
88 this manual provided the copyright notice and this permission notice
89 are preserved on all copies.
92 Permission is granted to process this file through Tex and print the
93 results, provided the printed document carries copying permission
94 notice identical to this one except for the removal of this paragraph
95 (this paragraph not being relevant to the printed manual).
98 Permission is granted to copy and distribute modified versions of this manual
99 under the conditions for verbatim copying, provided that the entire resulting
100 derived work is distributed under the terms of a permission notice identical to
103 Permission is granted to copy and distribute translations of this manual
104 into another language, under the above conditions for modified versions.
108 @title Using @value{AS}
109 @subtitle The GNU Assembler
111 @subtitle for the @value{TARGET} family
114 @subtitle January 1994
117 The Free Software Foundation Inc. thanks The Nice Computer
118 Company of Australia for loaning Dean Elsner to write the
119 first (Vax) version of @code{as} for Project GNU.
120 The proprietors, management and staff of TNCCA thank FSF for
121 distracting the boss while they got some work
124 @author Dean Elsner, Jay Fenlason & friends
128 \hfill {\it Using {\tt @value{AS}}}\par
129 \hfill Edited by Roland Pesch for Cygnus Support\par
131 %"boxit" macro for figures:
132 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
133 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
134 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
135 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
136 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
139 @vskip 0pt plus 1filll
140 Copyright @copyright{} 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
142 Permission is granted to make and distribute verbatim copies of
143 this manual provided the copyright notice and this permission notice
144 are preserved on all copies.
146 Permission is granted to copy and distribute modified versions of this manual
147 under the conditions for verbatim copying, provided that the entire resulting
148 derived work is distributed under the terms of a permission notice identical to
151 Permission is granted to copy and distribute translations of this manual
152 into another language, under the above conditions for modified versions.
157 @top Using @value{AS}
159 This file is a user guide to the @sc{gnu} assembler @code{@value{AS}}.
161 This version of the file describes @code{@value{AS}} configured to generate
162 code for @value{TARGET} architectures.
165 * Overview:: Overview
166 * Invoking:: Command-Line Options
168 * Sections:: Sections and Relocation
170 * Expressions:: Expressions
171 * Pseudo Ops:: Assembler Directives
172 * Machine Dependencies:: Machine Dependent Features
173 * Acknowledgements:: Who Did What
181 This manual is a user guide to the @sc{gnu} assembler @code{@value{AS}}.
183 This version of the manual describes @code{@value{AS}} configured to generate
184 code for @value{TARGET} architectures.
188 @cindex invocation summary
189 @cindex option summary
190 @cindex summary of options
191 Here is a brief summary of how to invoke @code{@value{AS}}. For details,
192 @pxref{Invoking,,Comand-Line Options}.
194 @c We don't use deffn and friends for the following because they seem
195 @c to be limited to one line for the header.
197 @value{AS} [ -a[dhlns] ] [ -D ] [ -f ] [ --help ]
198 [ -I @var{dir} ] [ -J ] [ -K ] [ -L ] [ -o @var{objfile} ]
199 [ -R ] [ --statistics ] [ -v ] [ -version ] [ --version ]
200 [ -W ] [ -w ] [ -x ] [ -Z ]
202 @c am29k has no machine-dependent assembler options
204 @c start-sanitize-arc
206 [ -mbig-endian | -mlittle-endian ]
210 @c Hitachi family chips have no machine-dependent assembler options
213 @c HPPA has no machine-dependent assembler options (yet).
216 [ -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite | -bump ]
219 @c Z8000 has no machine-dependent assembler options
222 @c see md_parse_option in tc-i960.c
223 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
227 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
230 [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ]
231 [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ]
232 [ --trap ] [ --break ]
234 [ -- | @var{files} @dots{} ]
239 Turn on listings, in any of a variety of ways:
243 omit debugging directives
246 include high-level source
252 omit forms processing
258 You may combine these options; for example, use @samp{-aln} for assembly
259 listing without forms processing. By itself, @samp{-a} defaults to
260 @samp{-ahls}---that is, all listings turned on.
263 Ignored. This option is accepted for script compatibility with calls to
267 ``fast''---skip whitespace and comment preprocessing (assume source is
271 Print a summary of the command line options and exit.
274 Add directory @var{dir} to the search list for @code{.include} directives.
277 Don't warn about signed overflow.
280 @ifclear DIFF-TBL-KLUGE
281 This option is accepted but has no effect on the @value{TARGET} family.
283 @ifset DIFF-TBL-KLUGE
284 Issue warnings when difference tables altered for long displacements.
288 Keep (in the symbol table) local symbols, starting with @samp{L}.
290 @item -o @var{objfile}
291 Name the object-file output from @code{@value{AS}} @var{objfile}.
294 Fold the data section into the text section.
297 Print the maximum space (in bytes) and total time (in seconds) used by
302 Print the @code{as} version.
305 Print the @code{as} version and exit.
308 Suppress warning messages.
317 Generate an object file even after errors.
319 @item -- | @var{files} @dots{}
320 Standard input, or source files to assemble.
325 The following options are available when @value{AS} is configured for
330 @cindex ARC endianness
331 @cindex endianness, ARC
332 @cindex big endian output, ARC
334 Generate ``big endian'' format output.
336 @cindex little endian output, ARC
337 @item -mlittle-endian
338 Generate ``little endian'' format output.
344 The following options are available when @value{AS} is configured for the
345 Intel 80960 processor.
348 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
349 Specify which variant of the 960 architecture is the target.
352 Add code to collect statistics about branches taken.
355 Do not alter compare-and-branch instructions for long displacements;
362 The following options are available when @value{AS} is configured for the
363 Motorola 68000 series.
368 Shorten references to undefined symbols, to one word instead of two.
370 @item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040
371 @itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32
372 Specify what processor in the 68000 family is the target. The default
373 is normally the 68020, but this can be changed at configuration time.
375 @item -m68881 | -m68882 | -mno-68881 | -mno-68882
376 The target machine does (or does not) have a floating-point coprocessor.
377 The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
378 the basic 68000 is not compatible with the 68881, a combination of the
379 two can be specified, since it's possible to do emulation of the
380 coprocessor instructions with the main processor.
382 @item -m68851 | -mno-68851
383 The target machine does (or does not) have a memory-management
384 unit coprocessor. The default is to assume an MMU for 68020 and up.
390 The following options are available when @code{@value{AS}} is configured
391 for the SPARC architecture:
394 @item -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite
395 Explicitly select a variant of the SPARC architecture.
398 Warn when the assembler switches to another architecture.
403 The following options are available when @value{AS} is configured for
408 This option sets the largest size of an object that can be referenced
409 implicitly with the @code{gp} register. It is only accepted for targets that
410 use ECOFF format, such as a DECstation running Ultrix. The default value is 8.
412 @cindex MIPS endianness
413 @cindex endianness, MIPS
414 @cindex big endian output, MIPS
416 Generate ``big endian'' format output.
418 @cindex little endian output, MIPS
420 Generate ``little endian'' format output.
426 Generate code for a particular MIPS Instruction Set Architecture level.
427 @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
428 @samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000}
433 Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept
434 the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
435 instructions around accesses to the @samp{HI} and @samp{LO} registers.
436 @samp{-no-m4650} turns off this option.
438 @item -mcpu=@var{CPU}
439 Generate code for a particular MIPS cpu. This has little effect on the
440 assembler, but it is passed by @code{@value{GCC}}.
443 @code{@value{AS}} ignores this option. It is accepted for compatibility with
450 Control how to deal with multiplication overflow and division by zero.
451 @samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception
452 (and only work for Instruction Set Architecture level 2 and higher);
453 @samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a
459 * Manual:: Structure of this Manual
460 * GNU Assembler:: @value{AS}, the GNU Assembler
461 * Object Formats:: Object File Formats
462 * Command Line:: Command Line
463 * Input Files:: Input Files
464 * Object:: Output (Object) File
465 * Errors:: Error and Warning Messages
469 @section Structure of this Manual
471 @cindex manual, structure and purpose
472 This manual is intended to describe what you need to know to use
473 @sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including
474 notation for symbols, constants, and expressions; the directives that
475 @code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}.
478 We also cover special features in the @value{TARGET}
479 configuration of @code{@value{AS}}, including assembler directives.
482 This manual also describes some of the machine-dependent features of
483 various flavors of the assembler.
486 @cindex machine instructions (not covered)
487 On the other hand, this manual is @emph{not} intended as an introduction
488 to programming in assembly language---let alone programming in general!
489 In a similar vein, we make no attempt to introduce the machine
490 architecture; we do @emph{not} describe the instruction set, standard
491 mnemonics, registers or addressing modes that are standard to a
492 particular architecture.
494 You may want to consult the manufacturer's
495 machine architecture manual for this information.
499 For information on the H8/300 machine instruction set, see @cite{H8/300
500 Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H,
501 see @cite{H8/300H Series Programming Manual} (Hitachi).
504 For information on the H8/500 machine instruction set, see @cite{H8/500
505 Series Programming Manual} (Hitachi M21T001).
508 For information on the Hitachi SH machine instruction set, see
509 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
512 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
516 @c I think this is premature---pesch@cygnus.com, 17jan1991
518 Throughout this manual, we assume that you are running @dfn{GNU},
519 the portable operating system from the @dfn{Free Software
520 Foundation, Inc.}. This restricts our attention to certain kinds of
521 computer (in particular, the kinds of computers that @sc{gnu} can run on);
522 once this assumption is granted examples and definitions need less
525 @code{@value{AS}} is part of a team of programs that turn a high-level
526 human-readable series of instructions into a low-level
527 computer-readable series of instructions. Different versions of
528 @code{@value{AS}} are used for different kinds of computer.
531 @c There used to be a section "Terminology" here, which defined
532 @c "contents", "byte", "word", and "long". Defining "word" to any
533 @c particular size is confusing when the .word directive may generate 16
534 @c bits on one machine and 32 bits on another; in general, for the user
535 @c version of this manual, none of these terms seem essential to define.
536 @c They were used very little even in the former draft of the manual;
537 @c this draft makes an effort to avoid them (except in names of
541 @section @value{AS}, the GNU Assembler
543 @sc{gnu} @code{as} is really a family of assemblers.
545 This manual describes @code{@value{AS}}, a member of that family which is
546 configured for the @value{TARGET} architectures.
548 If you use (or have used) the @sc{gnu} assembler on one architecture, you
549 should find a fairly similar environment when you use it on another
550 architecture. Each version has much in common with the others,
551 including object file formats, most assembler directives (often called
552 @dfn{pseudo-ops}) and assembler syntax.@refill
554 @cindex purpose of @sc{gnu} @code{@value{AS}}
555 @code{@value{AS}} is primarily intended to assemble the output of the
556 @sc{gnu} C compiler @code{@value{GCC}} for use by the linker
557 @code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}}
558 assemble correctly everything that other assemblers for the same
559 machine would assemble.
561 Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
564 @c This remark should appear in generic version of manual; assumption
565 @c here is that generic version sets M680x0.
566 This doesn't mean @code{@value{AS}} always uses the same syntax as another
567 assembler for the same architecture; for example, we know of several
568 incompatible versions of 680x0 assembly language syntax.
571 Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
572 program in one pass of the source file. This has a subtle impact on the
573 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
576 @section Object File Formats
578 @cindex object file format
579 The @sc{gnu} assembler can be configured to produce several alternative
580 object file formats. For the most part, this does not affect how you
581 write assembly language programs; but directives for debugging symbols
582 are typically different in different file formats. @xref{Symbol
583 Attributes,,Symbol Attributes}.
586 On the @value{TARGET}, @code{@value{AS}} is configured to produce
587 @value{OBJ-NAME} format object files.
589 @c The following should exhaust all configs that set MULTI-OBJ, ideally
591 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
592 @code{a.out} or COFF format object files.
595 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
596 @code{b.out} or COFF format object files.
599 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
600 SOM or ELF format object files.
605 @section Command Line
607 @cindex command line conventions
608 After the program name @code{@value{AS}}, the command line may contain
609 options and file names. Options may appear in any order, and may be
610 before, after, or between file names. The order of file names is
613 @cindex standard input, as input file
615 @file{--} (two hyphens) by itself names the standard input file
616 explicitly, as one of the files for @code{@value{AS}} to assemble.
618 @cindex options, command line
619 Except for @samp{--} any command line argument that begins with a
620 hyphen (@samp{-}) is an option. Each option changes the behavior of
621 @code{@value{AS}}. No option changes the way another option works. An
622 option is a @samp{-} followed by one or more letters; the case of
623 the letter is important. All options are optional.
625 Some options expect exactly one file name to follow them. The file
626 name may either immediately follow the option's letter (compatible
627 with older assemblers) or it may be the next command argument (@sc{gnu}
628 standard). These two command lines are equivalent:
631 @value{AS} -o my-object-file.o mumble.s
632 @value{AS} -omy-object-file.o mumble.s
639 @cindex source program
641 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
642 describe the program input to one run of @code{@value{AS}}. The program may
643 be in one or more files; how the source is partitioned into files
644 doesn't change the meaning of the source.
646 @c I added "con" prefix to "catenation" just to prove I can overcome my
647 @c APL training... pesch@cygnus.com
648 The source program is a concatenation of the text in all the files, in the
651 Each time you run @code{@value{AS}} it assembles exactly one source
652 program. The source program is made up of one or more files.
653 (The standard input is also a file.)
655 You give @code{@value{AS}} a command line that has zero or more input file
656 names. The input files are read (from left file name to right). A
657 command line argument (in any position) that has no special meaning
658 is taken to be an input file name.
660 If you give @code{@value{AS}} no file names it attempts to read one input file
661 from the @code{@value{AS}} standard input, which is normally your terminal. You
662 may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program
665 Use @samp{--} if you need to explicitly name the standard input file
666 in your command line.
668 If the source is empty, @code{@value{AS}} produces a small, empty object
671 @subheading Filenames and Line-numbers
673 @cindex input file linenumbers
674 @cindex line numbers, in input files
675 There are two ways of locating a line in the input file (or files) and
676 either may be used in reporting error messages. One way refers to a line
677 number in a physical file; the other refers to a line number in a
678 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
680 @dfn{Physical files} are those files named in the command line given
681 to @code{@value{AS}}.
683 @dfn{Logical files} are simply names declared explicitly by assembler
684 directives; they bear no relation to physical files. Logical file names
685 help error messages reflect the original source file, when @code{@value{AS}}
686 source is itself synthesized from other files.
687 @xref{App-File,,@code{.app-file}}.
690 @section Output (Object) File
696 Every time you run @code{@value{AS}} it produces an output file, which is
697 your assembly language program translated into numbers. This file
698 is the object file. Its default name is
706 @code{b.out} when @code{@value{AS}} is configured for the Intel 80960.
708 You can give it another name by using the @code{-o} option. Conventionally,
709 object file names end with @file{.o}. The default name is used for historical
710 reasons: older assemblers were capable of assembling self-contained programs
711 directly into a runnable program. (For some formats, this isn't currently
712 possible, but it can be done for the @code{a.out} format.)
716 The object file is meant for input to the linker @code{@value{LD}}. It contains
717 assembled program code, information to help @code{@value{LD}} integrate
718 the assembled program into a runnable file, and (optionally) symbolic
719 information for the debugger.
721 @c link above to some info file(s) like the description of a.out.
722 @c don't forget to describe GNU info as well as Unix lossage.
725 @section Error and Warning Messages
727 @cindex error messsages
728 @cindex warning messages
729 @cindex messages from @code{@value{AS}}
730 @code{@value{AS}} may write warnings and error messages to the standard error
731 file (usually your terminal). This should not happen when a compiler
732 runs @code{@value{AS}} automatically. Warnings report an assumption made so
733 that @code{@value{AS}} could keep assembling a flawed program; errors report a
734 grave problem that stops the assembly.
736 @cindex format of warning messages
737 Warning messages have the format
740 file_name:@b{NNN}:Warning Message Text
744 @cindex line numbers, in warnings/errors
745 (where @b{NNN} is a line number). If a logical file name has been given
746 (@pxref{App-File,,@code{.app-file}}) it is used for the filename,
747 otherwise the name of the current input file is used. If a logical line
750 (@pxref{Line,,@code{.line}})
754 (@pxref{Line,,@code{.line}})
757 (@pxref{Ln,,@code{.ln}})
760 then it is used to calculate the number printed,
761 otherwise the actual line in the current source file is printed. The
762 message text is intended to be self explanatory (in the grand Unix
765 @cindex format of error messages
766 Error messages have the format
768 file_name:@b{NNN}:FATAL:Error Message Text
770 The file name and line number are derived as for warning
771 messages. The actual message text may be rather less explanatory
772 because many of them aren't supposed to happen.
775 @chapter Command-Line Options
777 @cindex options, all versions of @code{@value{AS}}
778 This chapter describes command-line options available in @emph{all}
779 versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific
781 to the @value{TARGET}.
784 to particular machine architectures.
787 If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2), you
788 can use the @samp{-Wa} option to pass arguments through to the
789 assembler. The assembler arguments must be separated from each other
790 (and the @samp{-Wa}) by commas. For example:
793 gcc -c -g -O -Wa,-alh,-L file.c
797 emits a listing to standard output with high-level
800 Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
801 command-line options are automatically passed to the assembler by the compiler.
802 (You can call the @sc{gnu} compiler driver with the @samp{-v} option to see
803 precisely what options it passes to each compilation pass, including the
807 * a:: -a[dhlns] enable listings
808 * D:: -D for compatibility
809 * f:: -f to work faster
810 * I:: -I for .include search path
811 @ifclear DIFF-TBL-KLUGE
812 * K:: -K for compatibility
814 @ifset DIFF-TBL-KLUGE
815 * K:: -K for difference tables
818 * L:: -L to retain local labels
819 * o:: -o to name the object file
820 * R:: -R to join data and text sections
821 * statistics:: --statistics to see statistics about assembly
822 * v:: -v to announce version
823 * W:: -W to suppress warnings
824 * Z:: -Z to make object file even after errors
828 @section Enable Listings: @code{-a[dhlns]}
836 @cindex listings, enabling
837 @cindex assembly listings, enabling
839 These options enable listing output from the assembler. By itself,
840 @samp{-a} requests high-level, assembly, and symbols listing.
841 You can use other letters to select specific options for the list:
842 @samp{-ah} requests a high-level language listing,
843 @samp{-al} requests an output-program assembly listing, and
844 @samp{-as} requests a symbol table listing.
845 High-level listings require that a compiler debugging option like
846 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
849 Use the @samp{-ad} option to omit debugging directives from the
852 Once you have specified one of these options, you can further control
853 listing output and its appearance using the directives @code{.list},
854 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
856 The @samp{-an} option turns off all forms processing.
857 If you do not request listing output with one of the @samp{-a} options, the
858 listing-control directives have no effect.
860 The letters after @samp{-a} may be combined into one option,
861 @emph{e.g.}, @samp{-aln}.
867 This option has no effect whatsoever, but it is accepted to make it more
868 likely that scripts written for other assemblers also work with
872 @section Work Faster: @code{-f}
875 @cindex trusted compiler
876 @cindex faster processing (@code{-f})
877 @samp{-f} should only be used when assembling programs written by a
878 (trusted) compiler. @samp{-f} stops the assembler from doing whitespace
879 and comment preprocessing on
880 the input file(s) before assembling them. @xref{Preprocessing,
884 @emph{Warning:} if you use @samp{-f} when the files actually need to be
885 preprocessed (if they contain comments, for example), @code{@value{AS}} does
890 @section @code{.include} search path: @code{-I} @var{path}
892 @kindex -I @var{path}
893 @cindex paths for @code{.include}
894 @cindex search path for @code{.include}
895 @cindex @code{include} directive search path
896 Use this option to add a @var{path} to the list of directories
897 @code{@value{AS}} searches for files specified in @code{.include}
898 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
899 many times as necessary to include a variety of paths. The current
900 working directory is always searched first; after that, @code{@value{AS}}
901 searches any @samp{-I} directories in the same order as they were
902 specified (left to right) on the command line.
905 @section Difference Tables: @code{-K}
908 @ifclear DIFF-TBL-KLUGE
909 On the @value{TARGET} family, this option is allowed, but has no effect. It is
910 permitted for compatibility with the @sc{gnu} assembler on other platforms,
911 where it can be used to warn when the assembler alters the machine code
912 generated for @samp{.word} directives in difference tables. The @value{TARGET}
913 family does not have the addressing limitations that sometimes lead to this
914 alteration on other platforms.
917 @ifset DIFF-TBL-KLUGE
918 @cindex difference tables, warning
919 @cindex warning for altered difference tables
920 @code{@value{AS}} sometimes alters the code emitted for directives of the form
921 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
922 You can use the @samp{-K} option if you want a warning issued when this
927 @section Include Local Labels: @code{-L}
930 @cindex local labels, retaining in output
931 Labels beginning with @samp{L} (upper case only) are called @dfn{local
932 labels}. @xref{Symbol Names}. Normally you do not see such labels when
933 debugging, because they are intended for the use of programs (like
934 compilers) that compose assembler programs, not for your notice.
935 Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not
936 normally debug with them.
938 This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols
939 in the object file. Usually if you do this you also tell the linker
940 @code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
942 By default, a local label is any label beginning with @samp{L}, but each
943 target is allowed to redefine the local label prefix.
945 On the HPPA local labels begin with @samp{L$}.
947 @c start-sanitize-arc
949 On the ARC local labels begin with @samp{.L}.
954 @section Name the Object File: @code{-o}
957 @cindex naming object file
958 @cindex object file name
959 There is always one object file output when you run @code{@value{AS}}. By
960 default it has the name
963 @file{a.out} (or @file{b.out}, for Intel 960 targets only).
977 You use this option (which takes exactly one filename) to give the
978 object file a different name.
980 Whatever the object file is called, @code{@value{AS}} overwrites any
981 existing file of the same name.
984 @section Join Data and Text Sections: @code{-R}
987 @cindex data and text sections, joining
988 @cindex text and data sections, joining
989 @cindex joining text and data sections
990 @cindex merging text and data sections
991 @code{-R} tells @code{@value{AS}} to write the object file as if all
992 data-section data lives in the text section. This is only done at
993 the very last moment: your binary data are the same, but data
994 section parts are relocated differently. The data section part of
995 your object file is zero bytes long because all its bytes are
996 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
998 When you specify @code{-R} it would be possible to generate shorter
999 address displacements (because we do not have to cross between text and
1000 data section). We refrain from doing this simply for compatibility with
1001 older versions of @code{@value{AS}}. In future, @code{-R} may work this way.
1004 When @code{@value{AS}} is configured for COFF output,
1005 this option is only useful if you use sections named @samp{.text} and
1010 @code{-R} is not supported for any of the HPPA targets. Using
1011 @code{-R} generates a warning from @code{@value{AS}}.
1015 @section Display Assembly Statistics: @code{--statistics}
1017 @kindex --statistics
1018 @cindex statistics, about assembly
1019 @cindex time, total for assembly
1020 @cindex space used, maximum for assembly
1021 Use @samp{--statistics} to display two statistics about the resources used by
1022 @code{@value{AS}}: the maximum amount of space allocated during the assembly
1023 (in bytes), and the total execution time taken for the assembly (in @sc{cpu}
1027 @section Announce Version: @code{-v}
1031 @cindex @code{@value{AS}} version
1032 @cindex version of @code{@value{AS}}
1033 You can find out what version of as is running by including the
1034 option @samp{-v} (which you can also spell as @samp{-version}) on the
1038 @section Suppress Warnings: @code{-W}
1041 @cindex suppressing warnings
1042 @cindex warnings, suppressing
1043 @code{@value{AS}} should never give a warning or error message when
1044 assembling compiler output. But programs written by people often
1045 cause @code{@value{AS}} to give a warning that a particular assumption was
1046 made. All such warnings are directed to the standard error file.
1047 If you use this option, no warnings are issued. This option only
1048 affects the warning messages: it does not change any particular of how
1049 @code{@value{AS}} assembles your file. Errors, which stop the assembly, are
1053 @section Generate Object File in Spite of Errors: @code{-Z}
1054 @cindex object file, after errors
1055 @cindex errors, continuing after
1056 After an error message, @code{@value{AS}} normally produces no output. If for
1057 some reason you are interested in object file output even after
1058 @code{@value{AS}} gives an error message on your program, use the @samp{-Z}
1059 option. If there are any errors, @code{@value{AS}} continues anyways, and
1060 writes an object file after a final warning message of the form @samp{@var{n}
1061 errors, @var{m} warnings, generating bad object file.}
1066 @cindex machine-independent syntax
1067 @cindex syntax, machine-independent
1068 This chapter describes the machine-independent syntax allowed in a
1069 source file. @code{@value{AS}} syntax is similar to what many other
1070 assemblers use; it is inspired by the BSD 4.2
1075 assembler, except that @code{@value{AS}} does not assemble Vax bit-fields.
1079 * Preprocessing:: Preprocessing
1080 * Whitespace:: Whitespace
1081 * Comments:: Comments
1082 * Symbol Intro:: Symbols
1083 * Statements:: Statements
1084 * Constants:: Constants
1088 @section Preprocessing
1090 @cindex preprocessing
1091 The @code{@value{AS}} internal preprocessor:
1093 @cindex whitespace, removed by preprocessor
1095 adjusts and removes extra whitespace. It leaves one space or tab before
1096 the keywords on a line, and turns any other whitespace on the line into
1099 @cindex comments, removed by preprocessor
1101 removes all comments, replacing them with a single space, or an
1102 appropriate number of newlines.
1104 @cindex constants, converted by preprocessor
1106 converts character constants into the appropriate numeric values.
1109 It does not do macro processing, include file handling, or
1110 anything else you may get from your C compiler's preprocessor. You can
1111 do include file processing with the @code{.include} directive
1112 (@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver
1113 to get other ``CPP'' style preprocessing, by giving the input file a
1114 @samp{.S} suffix. @xref{Overall Options,, Options Controlling the Kind of
1115 Output, gcc.info, Using GNU CC}.
1117 Excess whitespace, comments, and character constants
1118 cannot be used in the portions of the input text that are not
1121 @cindex turning preprocessing on and off
1122 @cindex preprocessing, turning on and off
1125 If the first line of an input file is @code{#NO_APP} or if you use the
1126 @samp{-f} option, whitespace and comments are not removed from the input file.
1127 Within an input file, you can ask for whitespace and comment removal in
1128 specific portions of the by putting a line that says @code{#APP} before the
1129 text that may contain whitespace or comments, and putting a line that says
1130 @code{#NO_APP} after this text. This feature is mainly intend to support
1131 @code{asm} statements in compilers whose output is otherwise free of comments
1138 @dfn{Whitespace} is one or more blanks or tabs, in any order.
1139 Whitespace is used to separate symbols, and to make programs neater for
1140 people to read. Unless within character constants
1141 (@pxref{Characters,,Character Constants}), any whitespace means the same
1142 as exactly one space.
1148 There are two ways of rendering comments to @code{@value{AS}}. In both
1149 cases the comment is equivalent to one space.
1151 Anything from @samp{/*} through the next @samp{*/} is a comment.
1152 This means you may not nest these comments.
1156 The only way to include a newline ('\n') in a comment
1157 is to use this sort of comment.
1160 /* This sort of comment does not nest. */
1163 @cindex line comment character
1164 Anything from the @dfn{line comment} character to the next newline
1165 is considered a comment and is ignored. The line comment character is
1166 @c start-sanitize-arc
1168 @samp{;} on the ARC;
1172 @samp{#} on the Vax;
1175 @samp{#} on the i960;
1178 @samp{!} on the SPARC;
1181 @samp{|} on the 680x0;
1184 @samp{;} for the AMD 29K family;
1187 @samp{;} for the H8/300 family;
1190 @samp{!} for the H8/500 family;
1193 @samp{;} for the HPPA;
1196 @samp{!} for the Hitachi SH;
1199 @samp{!} for the Z8000;
1201 see @ref{Machine Dependencies}. @refill
1202 @c FIXME What about i386, m88k, i860?
1205 On some machines there are two different line comment characters. One
1206 character only begins a comment if it is the first non-whitespace character on
1207 a line, while the other always begins a comment.
1211 @cindex lines starting with @code{#}
1212 @cindex logical line numbers
1213 To be compatible with past assemblers, lines that begin with @samp{#} have a
1214 special interpretation. Following the @samp{#} should be an absolute
1215 expression (@pxref{Expressions}): the logical line number of the @emph{next}
1216 line. Then a string (@pxref{Strings,, Strings}) is allowed: if present it is a
1217 new logical file name. The rest of the line, if any, should be whitespace.
1219 If the first non-whitespace characters on the line are not numeric,
1220 the line is ignored. (Just like a comment.)
1223 # This is an ordinary comment.
1224 # 42-6 "new_file_name" # New logical file name
1225 # This is logical line # 36.
1227 This feature is deprecated, and may disappear from future versions
1228 of @code{@value{AS}}.
1233 @cindex characters used in symbols
1234 @ifclear SPECIAL-SYMS
1235 A @dfn{symbol} is one or more characters chosen from the set of all
1236 letters (both upper and lower case), digits and the three characters
1242 A @dfn{symbol} is one or more characters chosen from the set of all
1243 letters (both upper and lower case), digits and the three characters
1244 @samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in
1250 On most machines, you can also use @code{$} in symbol names; exceptions
1251 are noted in @ref{Machine Dependencies}.
1253 No symbol may begin with a digit. Case is significant.
1254 There is no length limit: all characters are significant. Symbols are
1255 delimited by characters not in that set, or by the beginning of a file
1256 (since the source program must end with a newline, the end of a file is
1257 not a possible symbol delimiter). @xref{Symbols}.
1258 @cindex length of symbols
1263 @cindex statements, structure of
1264 @cindex line separator character
1265 @cindex statement separator character
1267 @ifclear abnormal-separator
1268 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
1269 semicolon (@samp{;}). The newline or semicolon is considered part of
1270 the preceding statement. Newlines and semicolons within character
1271 constants are an exception: they do not end statements.
1273 @ifset abnormal-separator
1275 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
1276 sign (@samp{@@}). The newline or at sign is considered part of the
1277 preceding statement. Newlines and at signs within character constants
1278 are an exception: they do not end statements.
1281 A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation
1282 point (@samp{!}). The newline or exclamation point is considered part of the
1283 preceding statement. Newlines and exclamation points within character
1284 constants are an exception: they do not end statements.
1287 A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
1288 H8/300) a dollar sign (@samp{$}); or (for the
1291 (@samp{;}). The newline or separator character is considered part of
1292 the preceding statement. Newlines and separators within character
1293 constants are an exception: they do not end statements.
1298 A @dfn{statement} ends at a newline character (@samp{\n}) or line
1299 separator character. (The line separator is usually @samp{;}, unless
1300 this conflicts with the comment character; @pxref{Machine Dependencies}.) The
1301 newline or separator character is considered part of the preceding
1302 statement. Newlines and separators within character constants are an
1303 exception: they do not end statements.
1306 @cindex newline, required at file end
1307 @cindex EOF, newline must precede
1308 It is an error to end any statement with end-of-file: the last
1309 character of any input file should be a newline.@refill
1311 @cindex continuing statements
1312 @cindex multi-line statements
1313 @cindex statement on multiple lines
1314 You may write a statement on more than one line if you put a
1315 backslash (@kbd{\}) immediately in front of any newlines within the
1316 statement. When @code{@value{AS}} reads a backslashed newline both
1317 characters are ignored. You can even put backslashed newlines in
1318 the middle of symbol names without changing the meaning of your
1321 An empty statement is allowed, and may include whitespace. It is ignored.
1323 @cindex instructions and directives
1324 @cindex directives and instructions
1325 @c "key symbol" is not used elsewhere in the document; seems pedantic to
1326 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
1328 A statement begins with zero or more labels, optionally followed by a
1329 key symbol which determines what kind of statement it is. The key
1330 symbol determines the syntax of the rest of the statement. If the
1331 symbol begins with a dot @samp{.} then the statement is an assembler
1332 directive: typically valid for any computer. If the symbol begins with
1333 a letter the statement is an assembly language @dfn{instruction}: it
1334 assembles into a machine language instruction.
1336 Different versions of @code{@value{AS}} for different computers
1337 recognize different instructions. In fact, the same symbol may
1338 represent a different instruction in a different computer's assembly
1342 @cindex @code{:} (label)
1343 @cindex label (@code{:})
1344 A label is a symbol immediately followed by a colon (@code{:}).
1345 Whitespace before a label or after a colon is permitted, but you may not
1346 have whitespace between a label's symbol and its colon. @xref{Labels}.
1349 For HPPA targets, labels need not be immediately followed by a colon, but
1350 the definition of a label must begin in column zero. This also implies that
1351 only one label may be defined on each line.
1355 label: .directive followed by something
1356 another_label: # This is an empty statement.
1357 instruction operand_1, operand_2, @dots{}
1364 A constant is a number, written so that its value is known by
1365 inspection, without knowing any context. Like this:
1368 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
1369 .ascii "Ring the bell\7" # A string constant.
1370 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
1371 .float 0f-314159265358979323846264338327\
1372 95028841971.693993751E-40 # - pi, a flonum.
1377 * Characters:: Character Constants
1378 * Numbers:: Number Constants
1382 @subsection Character Constants
1384 @cindex character constants
1385 @cindex constants, character
1386 There are two kinds of character constants. A @dfn{character} stands
1387 for one character in one byte and its value may be used in
1388 numeric expressions. String constants (properly called string
1389 @emph{literals}) are potentially many bytes and their values may not be
1390 used in arithmetic expressions.
1394 * Chars:: Characters
1398 @subsubsection Strings
1400 @cindex string constants
1401 @cindex constants, string
1402 A @dfn{string} is written between double-quotes. It may contain
1403 double-quotes or null characters. The way to get special characters
1404 into a string is to @dfn{escape} these characters: precede them with
1405 a backslash @samp{\} character. For example @samp{\\} represents
1406 one backslash: the first @code{\} is an escape which tells
1407 @code{@value{AS}} to interpret the second character literally as a backslash
1408 (which prevents @code{@value{AS}} from recognizing the second @code{\} as an
1409 escape character). The complete list of escapes follows.
1411 @cindex escape codes, character
1412 @cindex character escape codes
1415 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1418 @cindex @code{\b} (backspace character)
1419 @cindex backspace (@code{\b})
1420 Mnemonic for backspace; for ASCII this is octal code 010.
1423 @c Mnemonic for EOText; for ASCII this is octal code 004.
1426 @cindex @code{\f} (formfeed character)
1427 @cindex formfeed (@code{\f})
1428 Mnemonic for FormFeed; for ASCII this is octal code 014.
1431 @cindex @code{\n} (newline character)
1432 @cindex newline (@code{\n})
1433 Mnemonic for newline; for ASCII this is octal code 012.
1436 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1439 @cindex @code{\r} (carriage return character)
1440 @cindex carriage return (@code{\r})
1441 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1444 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1445 @c other assemblers.
1448 @cindex @code{\t} (tab)
1449 @cindex tab (@code{\t})
1450 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1453 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1454 @c @item \x @var{digit} @var{digit} @var{digit}
1455 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1457 @item \ @var{digit} @var{digit} @var{digit}
1458 @cindex @code{\@var{ddd}} (octal character code)
1459 @cindex octal character code (@code{\@var{ddd}})
1460 An octal character code. The numeric code is 3 octal digits.
1461 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1462 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1465 @item \@code{x} @var{hex-digit} @var{hex-digit}
1466 @cindex @code{\@var{xdd}} (hex character code)
1467 @cindex hex character code (@code{\@var{xdd}})
1468 A hex character code. The numeric code is 2 hexadecimal digits. Either
1469 upper or lower case @code{x} works.
1473 @cindex @code{\\} (@samp{\} character)
1474 @cindex backslash (@code{\\})
1475 Represents one @samp{\} character.
1478 @c Represents one @samp{'} (accent acute) character.
1479 @c This is needed in single character literals
1480 @c (@xref{Characters,,Character Constants}.) to represent
1484 @cindex @code{\"} (doublequote character)
1485 @cindex doublequote (@code{\"})
1486 Represents one @samp{"} character. Needed in strings to represent
1487 this character, because an unescaped @samp{"} would end the string.
1489 @item \ @var{anything-else}
1490 Any other character when escaped by @kbd{\} gives a warning, but
1491 assembles as if the @samp{\} was not present. The idea is that if
1492 you used an escape sequence you clearly didn't want the literal
1493 interpretation of the following character. However @code{@value{AS}} has no
1494 other interpretation, so @code{@value{AS}} knows it is giving you the wrong
1495 code and warns you of the fact.
1498 Which characters are escapable, and what those escapes represent,
1499 varies widely among assemblers. The current set is what we think
1500 the BSD 4.2 assembler recognizes, and is a subset of what most C
1501 compilers recognize. If you are in doubt, do not use an escape
1505 @subsubsection Characters
1507 @cindex single character constant
1508 @cindex character, single
1509 @cindex constant, single character
1510 A single character may be written as a single quote immediately
1511 followed by that character. The same escapes apply to characters as
1512 to strings. So if you want to write the character backslash, you
1513 must write @kbd{'\\} where the first @code{\} escapes the second
1514 @code{\}. As you can see, the quote is an acute accent, not a
1515 grave accent. A newline
1517 @ifclear abnormal-separator
1518 (or semicolon @samp{;})
1520 @ifset abnormal-separator
1522 (or at sign @samp{@@})
1525 (or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
1531 immediately following an acute accent is taken as a literal character
1532 and does not count as the end of a statement. The value of a character
1533 constant in a numeric expression is the machine's byte-wide code for
1534 that character. @code{@value{AS}} assumes your character code is ASCII:
1535 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1538 @subsection Number Constants
1540 @cindex constants, number
1541 @cindex number constants
1542 @code{@value{AS}} distinguishes three kinds of numbers according to how they
1543 are stored in the target machine. @emph{Integers} are numbers that
1544 would fit into an @code{int} in the C language. @emph{Bignums} are
1545 integers, but they are stored in more than 32 bits. @emph{Flonums}
1546 are floating point numbers, described below.
1549 * Integers:: Integers
1554 * Bit Fields:: Bit Fields
1560 @subsubsection Integers
1562 @cindex constants, integer
1564 @cindex binary integers
1565 @cindex integers, binary
1566 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1567 the binary digits @samp{01}.
1569 @cindex octal integers
1570 @cindex integers, octal
1571 An octal integer is @samp{0} followed by zero or more of the octal
1572 digits (@samp{01234567}).
1574 @cindex decimal integers
1575 @cindex integers, decimal
1576 A decimal integer starts with a non-zero digit followed by zero or
1577 more digits (@samp{0123456789}).
1579 @cindex hexadecimal integers
1580 @cindex integers, hexadecimal
1581 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1582 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1584 Integers have the usual values. To denote a negative integer, use
1585 the prefix operator @samp{-} discussed under expressions
1586 (@pxref{Prefix Ops,,Prefix Operators}).
1589 @subsubsection Bignums
1592 @cindex constants, bignum
1593 A @dfn{bignum} has the same syntax and semantics as an integer
1594 except that the number (or its negative) takes more than 32 bits to
1595 represent in binary. The distinction is made because in some places
1596 integers are permitted while bignums are not.
1599 @subsubsection Flonums
1601 @cindex floating point numbers
1602 @cindex constants, floating point
1604 @cindex precision, floating point
1605 A @dfn{flonum} represents a floating point number. The translation is
1606 indirect: a decimal floating point number from the text is converted by
1607 @code{@value{AS}} to a generic binary floating point number of more than
1608 sufficient precision. This generic floating point number is converted
1609 to a particular computer's floating point format (or formats) by a
1610 portion of @code{@value{AS}} specialized to that computer.
1612 A flonum is written by writing (in order)
1617 (@samp{0} is optional on the HPPA.)
1621 A letter, to tell @code{@value{AS}} the rest of the number is a flonum.
1623 @kbd{e} is recommended. Case is not important.
1625 @c FIXME: verify if flonum syntax really this vague for most cases
1626 (Any otherwise illegal letter works here, but that might be changed. Vax BSD
1627 4.2 assembler seems to allow any of @samp{defghDEFGH}.)
1630 On the H8/300, H8/500,
1632 and AMD 29K architectures, the letter must be
1633 one of the letters @samp{DFPRSX} (in upper or lower case).
1635 @c start-sanitize-arc
1636 On the ARC, the letter one of the letters @samp{DFRS}
1637 (in upper or lower case).
1640 On the Intel 960 architecture, the letter must be
1641 one of the letters @samp{DFT} (in upper or lower case).
1643 On the HPPA architecture, the letter must be @samp{E} (upper case only).
1647 One of the letters @samp{DFPRSX} (in upper or lower case).
1649 @c start-sanitize-arc
1651 One of the letters @samp{DFRS} (in upper or lower case).
1655 One of the letters @samp{DFPRSX} (in upper or lower case).
1658 One of the letters @samp{DFT} (in upper or lower case).
1661 The letter @samp{E} (upper case only).
1666 An optional sign: either @samp{+} or @samp{-}.
1669 An optional @dfn{integer part}: zero or more decimal digits.
1672 An optional @dfn{fractional part}: @samp{.} followed by zero
1673 or more decimal digits.
1676 An optional exponent, consisting of:
1680 An @samp{E} or @samp{e}.
1681 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1682 @c principle this can perfectly well be different on different targets.
1684 Optional sign: either @samp{+} or @samp{-}.
1686 One or more decimal digits.
1691 At least one of the integer part or the fractional part must be
1692 present. The floating point number has the usual base-10 value.
1694 @code{@value{AS}} does all processing using integers. Flonums are computed
1695 independently of any floating point hardware in the computer running
1700 @c Bit fields are written as a general facility but are also controlled
1701 @c by a conditional-compilation flag---which is as of now (21mar91)
1702 @c turned on only by the i960 config of GAS.
1704 @subsubsection Bit Fields
1707 @cindex constants, bit field
1708 You can also define numeric constants as @dfn{bit fields}.
1709 specify two numbers separated by a colon---
1711 @var{mask}:@var{value}
1714 @code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
1717 The resulting number is then packed
1719 @c this conditional paren in case bit fields turned on elsewhere than 960
1720 (in host-dependent byte order)
1722 into a field whose width depends on which assembler directive has the
1723 bit-field as its argument. Overflow (a result from the bitwise and
1724 requiring more binary digits to represent) is not an error; instead,
1725 more constants are generated, of the specified width, beginning with the
1726 least significant digits.@refill
1728 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1729 @code{.short}, and @code{.word} accept bit-field arguments.
1734 @chapter Sections and Relocation
1739 * Secs Background:: Background
1740 * Ld Sections:: @value{LD} Sections
1741 * As Sections:: @value{AS} Internal Sections
1742 * Sub-Sections:: Sub-Sections
1746 @node Secs Background
1749 Roughly, a section is a range of addresses, with no gaps; all data
1750 ``in'' those addresses is treated the same for some particular purpose.
1751 For example there may be a ``read only'' section.
1753 @cindex linker, and assembler
1754 @cindex assembler, and linker
1755 The linker @code{@value{LD}} reads many object files (partial programs) and
1756 combines their contents to form a runnable program. When @code{@value{AS}}
1757 emits an object file, the partial program is assumed to start at address 0.
1758 @code{@value{LD}} assigns the final addresses for the partial program, so that
1759 different partial programs do not overlap. This is actually an
1760 oversimplification, but it suffices to explain how @code{@value{AS}} uses
1763 @code{@value{LD}} moves blocks of bytes of your program to their run-time
1764 addresses. These blocks slide to their run-time addresses as rigid
1765 units; their length does not change and neither does the order of bytes
1766 within them. Such a rigid unit is called a @emph{section}. Assigning
1767 run-time addresses to sections is called @dfn{relocation}. It includes
1768 the task of adjusting mentions of object-file addresses so they refer to
1769 the proper run-time addresses.
1771 For the H8/300 and H8/500,
1772 and for the Hitachi SH,
1773 @code{@value{AS}} pads sections if needed to
1774 ensure they end on a word (sixteen bit) boundary.
1777 @cindex standard @code{@value{AS}} sections
1778 An object file written by @code{@value{AS}} has at least three sections, any
1779 of which may be empty. These are named @dfn{text}, @dfn{data} and
1784 When it generates COFF output,
1786 @code{@value{AS}} can also generate whatever other named sections you specify
1787 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1788 If you do not use any directives that place output in the @samp{.text}
1789 or @samp{.data} sections, these sections still exist, but are empty.
1794 When @code{@value{AS}} generates SOM or ELF output for the HPPA,
1796 @code{@value{AS}} can also generate whatever other named sections you
1797 specify using the @samp{.space} and @samp{.subspace} directives. See
1798 @cite{HP9000 Series 800 Assembly Language Reference Manual}
1799 (HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
1800 assembler directives.
1803 Additionally, @code{@value{AS}} uses different names for the standard
1804 text, data, and bss sections when generating SOM output. Program text
1805 is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
1806 BSS into @samp{$BSS$}.
1810 Within the object file, the text section starts at address @code{0}, the
1811 data section follows, and the bss section follows the data section.
1814 When generating either SOM or ELF output files on the HPPA, the text
1815 section starts at address @code{0}, the data section at address
1816 @code{0x4000000}, and the bss section follows the data section.
1819 To let @code{@value{LD}} know which data changes when the sections are
1820 relocated, and how to change that data, @code{@value{AS}} also writes to the
1821 object file details of the relocation needed. To perform relocation
1822 @code{@value{LD}} must know, each time an address in the object
1826 Where in the object file is the beginning of this reference to
1829 How long (in bytes) is this reference?
1831 Which section does the address refer to? What is the numeric value of
1833 (@var{address}) @minus{} (@var{start-address of section})?
1836 Is the reference to an address ``Program-Counter relative''?
1839 @cindex addresses, format of
1840 @cindex section-relative addressing
1841 In fact, every address @code{@value{AS}} ever uses is expressed as
1843 (@var{section}) + (@var{offset into section})
1846 Further, most expressions @code{@value{AS}} computes have this section-relative
1849 (For some object formats, such as SOM for the HPPA, some expressions are
1850 symbol-relative instead.)
1853 In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset
1854 @var{N} into section @var{secname}.''
1856 Apart from text, data and bss sections you need to know about the
1857 @dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
1858 addresses in the absolute section remain unchanged. For example, address
1859 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
1860 @code{@value{LD}}. Although the linker never arranges two partial programs'
1861 data sections with overlapping addresses after linking, @emph{by definition}
1862 their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one
1863 part of a program is always the same address when the program is running as
1864 address @code{@{absolute@ 239@}} in any other part of the program.
1866 The idea of sections is extended to the @dfn{undefined} section. Any
1867 address whose section is unknown at assembly time is by definition
1868 rendered @{undefined @var{U}@}---where @var{U} is filled in later.
1869 Since numbers are always defined, the only way to generate an undefined
1870 address is to mention an undefined symbol. A reference to a named
1871 common block would be such a symbol: its value is unknown at assembly
1872 time so it has section @emph{undefined}.
1874 By analogy the word @emph{section} is used to describe groups of sections in
1875 the linked program. @code{@value{LD}} puts all partial programs' text
1876 sections in contiguous addresses in the linked program. It is
1877 customary to refer to the @emph{text section} of a program, meaning all
1878 the addresses of all partial programs' text sections. Likewise for
1879 data and bss sections.
1881 Some sections are manipulated by @code{@value{LD}}; others are invented for
1882 use of @code{@value{AS}} and have no meaning except during assembly.
1885 @section @value{LD} Sections
1886 @code{@value{LD}} deals with just four kinds of sections, summarized below.
1891 @cindex named sections
1892 @cindex sections, named
1893 @item named sections
1896 @cindex text section
1897 @cindex data section
1901 These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as
1902 separate but equal sections. Anything you can say of one section is
1905 When the program is running, however, it is
1906 customary for the text section to be unalterable. The
1907 text section is often shared among processes: it contains
1908 instructions, constants and the like. The data section of a running
1909 program is usually alterable: for example, C variables would be stored
1910 in the data section.
1915 This section contains zeroed bytes when your program begins running. It
1916 is used to hold unitialized variables or common storage. The length of
1917 each partial program's bss section is important, but because it starts
1918 out containing zeroed bytes there is no need to store explicit zero
1919 bytes in the object file. The bss section was invented to eliminate
1920 those explicit zeros from object files.
1922 @cindex absolute section
1923 @item absolute section
1924 Address 0 of this section is always ``relocated'' to runtime address 0.
1925 This is useful if you want to refer to an address that @code{@value{LD}} must
1926 not change when relocating. In this sense we speak of absolute
1927 addresses being ``unrelocatable'': they do not change during relocation.
1929 @cindex undefined section
1930 @item undefined section
1931 This ``section'' is a catch-all for address references to objects not in
1932 the preceding sections.
1933 @c FIXME: ref to some other doc on obj-file formats could go here.
1936 @cindex relocation example
1937 An idealized example of three relocatable sections follows.
1939 The example uses the traditional section names @samp{.text} and @samp{.data}.
1941 Memory addresses are on the horizontal axis.
1945 @c END TEXI2ROFF-KILL
1948 partial program # 1: |ttttt|dddd|00|
1955 partial program # 2: |TTT|DDD|000|
1958 +--+---+-----+--+----+---+-----+~~
1959 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1960 +--+---+-----+--+----+---+-----+~~
1962 addresses: 0 @dots{}
1969 \line{\it Partial program \#1: \hfil}
1970 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1971 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1973 \line{\it Partial program \#2: \hfil}
1974 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1975 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1977 \line{\it linked program: \hfil}
1978 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1979 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1980 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1981 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1983 \line{\it addresses: \hfil}
1987 @c END TEXI2ROFF-KILL
1990 @section @value{AS} Internal Sections
1992 @cindex internal @code{@value{AS}} sections
1993 @cindex sections in messages, internal
1994 These sections are meant only for the internal use of @code{@value{AS}}. They
1995 have no meaning at run-time. You do not really need to know about these
1996 sections for most purposes; but they can be mentioned in @code{@value{AS}}
1997 warning messages, so it might be helpful to have an idea of their
1998 meanings to @code{@value{AS}}. These sections are used to permit the
1999 value of every expression in your assembly language program to be a
2000 section-relative address.
2003 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
2004 @cindex assembler internal logic error
2005 An internal assembler logic error has been found. This means there is a
2006 bug in the assembler.
2009 @cindex expr (internal section)
2010 The assembler stores complex expression internally as combinations of
2011 symbols. When it needs to represent an expression as a symbol, it puts
2012 it in the expr section.
2014 @c FIXME item transfer[t] vector preload
2015 @c FIXME item transfer[t] vector postload
2016 @c FIXME item register
2020 @section Sub-Sections
2022 @cindex numbered subsections
2023 @cindex grouping data
2029 fall into two sections: text and data.
2031 You may have separate groups of
2033 data in named sections
2037 data in named sections
2043 that you want to end up near to each other in the object file, even though they
2044 are not contiguous in the assembler source. @code{@value{AS}} allows you to
2045 use @dfn{subsections} for this purpose. Within each section, there can be
2046 numbered subsections with values from 0 to 8192. Objects assembled into the
2047 same subsection go into the object file together with other objects in the same
2048 subsection. For example, a compiler might want to store constants in the text
2049 section, but might not want to have them interspersed with the program being
2050 assembled. In this case, the compiler could issue a @samp{.text 0} before each
2051 section of code being output, and a @samp{.text 1} before each group of
2052 constants being output.
2054 Subsections are optional. If you do not use subsections, everything
2055 goes in subsection number zero.
2058 Each subsection is zero-padded up to a multiple of four bytes.
2059 (Subsections may be padded a different amount on different flavors
2060 of @code{@value{AS}}.)
2064 On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
2065 boundary (two bytes).
2066 The same is true on the Hitachi SH.
2069 @c FIXME section padding (alignment)?
2070 @c Rich Pixley says padding here depends on target obj code format; that
2071 @c doesn't seem particularly useful to say without further elaboration,
2072 @c so for now I say nothing about it. If this is a generic BFD issue,
2073 @c these paragraphs might need to vanish from this manual, and be
2074 @c discussed in BFD chapter of binutils (or some such).
2077 On the AMD 29K family, no particular padding is added to section or
2078 subsection sizes; @value{AS} forces no alignment on this platform.
2082 Subsections appear in your object file in numeric order, lowest numbered
2083 to highest. (All this to be compatible with other people's assemblers.)
2084 The object file contains no representation of subsections; @code{@value{LD}} and
2085 other programs that manipulate object files see no trace of them.
2086 They just see all your text subsections as a text section, and all your
2087 data subsections as a data section.
2089 To specify which subsection you want subsequent statements assembled
2090 into, use a numeric argument to specify it, in a @samp{.text
2091 @var{expression}} or a @samp{.data @var{expression}} statement.
2094 When generating COFF output, you
2099 can also use an extra subsection
2100 argument with arbitrary named sections: @samp{.section @var{name},
2103 @var{Expression} should be an absolute expression.
2104 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
2105 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
2106 begins in @code{text 0}. For instance:
2108 .text 0 # The default subsection is text 0 anyway.
2109 .ascii "This lives in the first text subsection. *"
2111 .ascii "But this lives in the second text subsection."
2113 .ascii "This lives in the data section,"
2114 .ascii "in the first data subsection."
2116 .ascii "This lives in the first text section,"
2117 .ascii "immediately following the asterisk (*)."
2120 Each section has a @dfn{location counter} incremented by one for every byte
2121 assembled into that section. Because subsections are merely a convenience
2122 restricted to @code{@value{AS}} there is no concept of a subsection location
2123 counter. There is no way to directly manipulate a location counter---but the
2124 @code{.align} directive changes it, and any label definition captures its
2125 current value. The location counter of the section where statements are being
2126 assembled is said to be the @dfn{active} location counter.
2129 @section bss Section
2132 @cindex common variable storage
2133 The bss section is used for local common variable storage.
2134 You may allocate address space in the bss section, but you may
2135 not dictate data to load into it before your program executes. When
2136 your program starts running, all the contents of the bss
2137 section are zeroed bytes.
2139 Addresses in the bss section are allocated with special directives; you
2140 may not assemble anything directly into the bss section. Hence there
2141 are no bss subsections. @xref{Comm,,@code{.comm}},
2142 @pxref{Lcomm,,@code{.lcomm}}.
2148 Symbols are a central concept: the programmer uses symbols to name
2149 things, the linker uses symbols to link, and the debugger uses symbols
2153 @cindex debuggers, and symbol order
2154 @emph{Warning:} @code{@value{AS}} does not place symbols in the object file in
2155 the same order they were declared. This may break some debuggers.
2160 * Setting Symbols:: Giving Symbols Other Values
2161 * Symbol Names:: Symbol Names
2162 * Dot:: The Special Dot Symbol
2163 * Symbol Attributes:: Symbol Attributes
2170 A @dfn{label} is written as a symbol immediately followed by a colon
2171 @samp{:}. The symbol then represents the current value of the
2172 active location counter, and is, for example, a suitable instruction
2173 operand. You are warned if you use the same symbol to represent two
2174 different locations: the first definition overrides any other
2178 On the HPPA, the usual form for a label need not be immediately followed by a
2179 colon, but instead must start in column zero. Only one label may be defined on
2180 a single line. To work around this, the HPPA version of @code{@value{AS}} also
2181 provides a special directive @code{.label} for defining labels more flexibly.
2184 @node Setting Symbols
2185 @section Giving Symbols Other Values
2187 @cindex assigning values to symbols
2188 @cindex symbol values, assigning
2189 A symbol can be given an arbitrary value by writing a symbol, followed
2190 by an equals sign @samp{=}, followed by an expression
2191 (@pxref{Expressions}). This is equivalent to using the @code{.set}
2192 directive. @xref{Set,,@code{.set}}.
2195 @section Symbol Names
2197 @cindex symbol names
2198 @cindex names, symbol
2199 @ifclear SPECIAL-SYMS
2200 Symbol names begin with a letter or with one of @samp{._}. On most
2201 machines, you can also use @code{$} in symbol names; exceptions are
2202 noted in @ref{Machine Dependencies}. That character may be followed by any
2203 string of digits, letters, dollar signs (unless otherwise noted in
2204 @ref{Machine Dependencies}), and underscores.
2207 For the AMD 29K family, @samp{?} is also allowed in the
2208 body of a symbol name, though not at its beginning.
2213 Symbol names begin with a letter or with one of @samp{._}. On the
2215 H8/500, you can also use @code{$} in symbol names. That character may
2216 be followed by any string of digits, letters, dollar signs (save on the
2217 H8/300), and underscores.
2221 Case of letters is significant: @code{foo} is a different symbol name
2224 Each symbol has exactly one name. Each name in an assembly language program
2225 refers to exactly one symbol. You may use that symbol name any number of times
2228 @subheading Local Symbol Names
2230 @cindex local symbol names
2231 @cindex symbol names, local
2232 @cindex temporary symbol names
2233 @cindex symbol names, temporary
2234 Local symbols help compilers and programmers use names temporarily.
2235 There are ten local symbol names, which are re-used throughout the
2236 program. You may refer to them using the names @samp{0} @samp{1}
2237 @dots{} @samp{9}. To define a local symbol, write a label of the form
2238 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
2239 recent previous definition of that symbol write @samp{@b{N}b}, using the
2240 same digit as when you defined the label. To refer to the next
2241 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
2242 a choice of 10 forward references. The @samp{b} stands for
2243 ``backwards'' and the @samp{f} stands for ``forwards''.
2245 Local symbols are not emitted by the current @sc{gnu} C compiler.
2247 There is no restriction on how you can use these labels, but
2248 remember that at any point in the assembly you can refer to at most
2249 10 prior local labels and to at most 10 forward local labels.
2251 Local symbol names are only a notation device. They are immediately
2252 transformed into more conventional symbol names before the assembler
2253 uses them. The symbol names stored in the symbol table, appearing in
2254 error messages and optionally emitted to the object file have these
2259 All local labels begin with @samp{L}. Normally both @code{@value{AS}} and
2260 @code{@value{LD}} forget symbols that start with @samp{L}. These labels are
2261 used for symbols you are never intended to see. If you use the
2262 @samp{-L} option then @code{@value{AS}} retains these symbols in the
2263 object file. If you also instruct @code{@value{LD}} to retain these symbols,
2264 you may use them in debugging.
2267 If the label is written @samp{0:} then the digit is @samp{0}.
2268 If the label is written @samp{1:} then the digit is @samp{1}.
2269 And so on up through @samp{9:}.
2272 This unusual character is included so you do not accidentally invent
2273 a symbol of the same name. The character has ASCII value
2276 @item @emph{ordinal number}
2277 This is a serial number to keep the labels distinct. The first
2278 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
2279 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
2283 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
2284 @code{3:} is named @code{L3@ctrl{A}44}.
2287 @section The Special Dot Symbol
2289 @cindex dot (symbol)
2290 @cindex @code{.} (symbol)
2291 @cindex current address
2292 @cindex location counter
2293 The special symbol @samp{.} refers to the current address that
2294 @code{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
2295 .long .} defines @code{melvin} to contain its own address.
2296 Assigning a value to @code{.} is treated the same as a @code{.org}
2297 directive. Thus, the expression @samp{.=.+4} is the same as saying
2298 @ifclear no-space-dir
2307 @node Symbol Attributes
2308 @section Symbol Attributes
2310 @cindex symbol attributes
2311 @cindex attributes, symbol
2312 Every symbol has, as well as its name, the attributes ``Value'' and
2313 ``Type''. Depending on output format, symbols can also have auxiliary
2316 The detailed definitions are in @file{a.out.h}.
2319 If you use a symbol without defining it, @code{@value{AS}} assumes zero for
2320 all these attributes, and probably won't warn you. This makes the
2321 symbol an externally defined symbol, which is generally what you
2325 * Symbol Value:: Value
2326 * Symbol Type:: Type
2329 * a.out Symbols:: Symbol Attributes: @code{a.out}
2333 * a.out Symbols:: Symbol Attributes: @code{a.out}
2336 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
2341 * COFF Symbols:: Symbol Attributes for COFF
2344 * SOM Symbols:: Symbol Attributes for SOM
2351 @cindex value of a symbol
2352 @cindex symbol value
2353 The value of a symbol is (usually) 32 bits. For a symbol which labels a
2354 location in the text, data, bss or absolute sections the value is the
2355 number of addresses from the start of that section to the label.
2356 Naturally for text, data and bss sections the value of a symbol changes
2357 as @code{@value{LD}} changes section base addresses during linking. Absolute
2358 symbols' values do not change during linking: that is why they are
2361 The value of an undefined symbol is treated in a special way. If it is
2362 0 then the symbol is not defined in this assembler source file, and
2363 @code{@value{LD}} tries to determine its value from other files linked into the
2364 same program. You make this kind of symbol simply by mentioning a symbol
2365 name without defining it. A non-zero value represents a @code{.comm}
2366 common declaration. The value is how much common storage to reserve, in
2367 bytes (addresses). The symbol refers to the first address of the
2373 @cindex type of a symbol
2375 The type attribute of a symbol contains relocation (section)
2376 information, any flag settings indicating that a symbol is external, and
2377 (optionally), other information for linkers and debuggers. The exact
2378 format depends on the object-code output format in use.
2383 @c The following avoids a "widow" subsection title. @group would be
2384 @c better if it were available outside examples.
2387 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
2389 @cindex @code{b.out} symbol attributes
2390 @cindex symbol attributes, @code{b.out}
2391 These symbol attributes appear only when @code{@value{AS}} is configured for
2392 one of the Berkeley-descended object output formats---@code{a.out} or
2398 @subsection Symbol Attributes: @code{a.out}
2400 @cindex @code{a.out} symbol attributes
2401 @cindex symbol attributes, @code{a.out}
2407 @subsection Symbol Attributes: @code{a.out}
2409 @cindex @code{a.out} symbol attributes
2410 @cindex symbol attributes, @code{a.out}
2414 * Symbol Desc:: Descriptor
2415 * Symbol Other:: Other
2419 @subsubsection Descriptor
2421 @cindex descriptor, of @code{a.out} symbol
2422 This is an arbitrary 16-bit value. You may establish a symbol's
2423 descriptor value by using a @code{.desc} statement
2424 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
2428 @subsubsection Other
2430 @cindex other attribute, of @code{a.out} symbol
2431 This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}.
2436 @subsection Symbol Attributes for COFF
2438 @cindex COFF symbol attributes
2439 @cindex symbol attributes, COFF
2441 The COFF format supports a multitude of auxiliary symbol attributes;
2442 like the primary symbol attributes, they are set between @code{.def} and
2443 @code{.endef} directives.
2445 @subsubsection Primary Attributes
2447 @cindex primary attributes, COFF symbols
2448 The symbol name is set with @code{.def}; the value and type,
2449 respectively, with @code{.val} and @code{.type}.
2451 @subsubsection Auxiliary Attributes
2453 @cindex auxiliary attributes, COFF symbols
2454 The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
2455 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2456 information for COFF.
2461 @subsection Symbol Attributes for SOM
2463 @cindex SOM symbol attributes
2464 @cindex symbol attributes, SOM
2466 The SOM format for the HPPA supports a multitude of symbol attributes set with
2467 the @code{.EXPORT} and @code{.IMPORT} directives.
2469 The attributes are described in @cite{HP9000 Series 800 Assembly
2470 Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
2471 @code{EXPORT} assembler directive documentation.
2475 @chapter Expressions
2479 @cindex numeric values
2480 An @dfn{expression} specifies an address or numeric value.
2481 Whitespace may precede and/or follow an expression.
2483 The result of an expression must be an absolute number, or else an offset into
2484 a particular section. If an expression is not absolute, and there is not
2485 enough information when @code{@value{AS}} sees the expression to know its
2486 section, a second pass over the source program might be necessary to interpret
2487 the expression---but the second pass is currently not implemented.
2488 @code{@value{AS}} aborts with an error message in this situation.
2491 * Empty Exprs:: Empty Expressions
2492 * Integer Exprs:: Integer Expressions
2496 @section Empty Expressions
2498 @cindex empty expressions
2499 @cindex expressions, empty
2500 An empty expression has no value: it is just whitespace or null.
2501 Wherever an absolute expression is required, you may omit the
2502 expression, and @code{@value{AS}} assumes a value of (absolute) 0. This
2503 is compatible with other assemblers.
2506 @section Integer Expressions
2508 @cindex integer expressions
2509 @cindex expressions, integer
2510 An @dfn{integer expression} is one or more @emph{arguments} delimited
2511 by @emph{operators}.
2514 * Arguments:: Arguments
2515 * Operators:: Operators
2516 * Prefix Ops:: Prefix Operators
2517 * Infix Ops:: Infix Operators
2521 @subsection Arguments
2523 @cindex expression arguments
2524 @cindex arguments in expressions
2525 @cindex operands in expressions
2526 @cindex arithmetic operands
2527 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2528 contexts arguments are sometimes called ``arithmetic operands''. In
2529 this manual, to avoid confusing them with the ``instruction operands'' of
2530 the machine language, we use the term ``argument'' to refer to parts of
2531 expressions only, reserving the word ``operand'' to refer only to machine
2532 instruction operands.
2534 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2535 @var{section} is one of text, data, bss, absolute,
2536 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2539 Numbers are usually integers.
2541 A number can be a flonum or bignum. In this case, you are warned
2542 that only the low order 32 bits are used, and @code{@value{AS}} pretends
2543 these 32 bits are an integer. You may write integer-manipulating
2544 instructions that act on exotic constants, compatible with other
2547 @cindex subexpressions
2548 Subexpressions are a left parenthesis @samp{(} followed by an integer
2549 expression, followed by a right parenthesis @samp{)}; or a prefix
2550 operator followed by an argument.
2553 @subsection Operators
2555 @cindex operators, in expressions
2556 @cindex arithmetic functions
2557 @cindex functions, in expressions
2558 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2559 operators are followed by an argument. Infix operators appear
2560 between their arguments. Operators may be preceded and/or followed by
2564 @subsection Prefix Operator
2566 @cindex prefix operators
2567 @code{@value{AS}} has the following @dfn{prefix operators}. They each take
2568 one argument, which must be absolute.
2570 @c the tex/end tex stuff surrounding this small table is meant to make
2571 @c it align, on the printed page, with the similar table in the next
2572 @c section (which is inside an enumerate).
2574 \global\advance\leftskip by \itemindent
2579 @dfn{Negation}. Two's complement negation.
2581 @dfn{Complementation}. Bitwise not.
2585 \global\advance\leftskip by -\itemindent
2589 @subsection Infix Operators
2591 @cindex infix operators
2592 @cindex operators, permitted arguments
2593 @dfn{Infix operators} take two arguments, one on either side. Operators
2594 have precedence, but operations with equal precedence are performed left
2595 to right. Apart from @code{+} or @code{-}, both arguments must be
2596 absolute, and the result is absolute.
2599 @cindex operator precedence
2600 @cindex precedence of operators
2607 @dfn{Multiplication}.
2610 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2617 @dfn{Shift Left}. Same as the C operator @samp{<<}.
2621 @dfn{Shift Right}. Same as the C operator @samp{>>}.
2625 Intermediate precedence
2630 @dfn{Bitwise Inclusive Or}.
2636 @dfn{Bitwise Exclusive Or}.
2639 @dfn{Bitwise Or Not}.
2647 @cindex addition, permitted arguments
2648 @cindex plus, permitted arguments
2649 @cindex arguments for addition
2650 @dfn{Addition}. If either argument is absolute, the result has the section of
2651 the other argument. You may not add together arguments from different
2655 @cindex subtraction, permitted arguments
2656 @cindex minus, permitted arguments
2657 @cindex arguments for subtraction
2658 @dfn{Subtraction}. If the right argument is absolute, the
2659 result has the section of the left argument.
2660 If both arguments are in the same section, the result is absolute.
2661 You may not subtract arguments from different sections.
2662 @c FIXME is there still something useful to say about undefined - undefined ?
2666 In short, it's only meaningful to add or subtract the @emph{offsets} in an
2667 address; you can only have a defined section in one of the two arguments.
2670 @chapter Assembler Directives
2672 @cindex directives, machine independent
2673 @cindex pseudo-ops, machine independent
2674 @cindex machine independent directives
2675 All assembler directives have names that begin with a period (@samp{.}).
2676 The rest of the name is letters, usually in lower case.
2678 This chapter discusses directives that are available regardless of the
2679 target machine configuration for the @sc{gnu} assembler.
2681 Some machine configurations provide additional directives.
2682 @xref{Machine Dependencies}.
2685 @ifset machine-directives
2686 @xref{Machine Dependencies} for additional directives.
2691 * Abort:: @code{.abort}
2693 * ABORT:: @code{.ABORT}
2696 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2697 * App-File:: @code{.app-file @var{string}}
2698 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2699 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2700 * Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}}
2701 * Byte:: @code{.byte @var{expressions}}
2702 * Comm:: @code{.comm @var{symbol} , @var{length} }
2703 * Data:: @code{.data @var{subsection}}
2705 * Def:: @code{.def @var{name}}
2708 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2714 * Double:: @code{.double @var{flonums}}
2715 * Eject:: @code{.eject}
2716 * Else:: @code{.else}
2718 * Endef:: @code{.endef}
2721 * Endif:: @code{.endif}
2722 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2723 * Extern:: @code{.extern}
2724 @ifclear no-file-dir
2725 * File:: @code{.file @var{string}}
2728 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2729 * Float:: @code{.float @var{flonums}}
2730 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2731 * hword:: @code{.hword @var{expressions}}
2732 * Ident:: @code{.ident}
2733 * If:: @code{.if @var{absolute expression}}
2734 * Include:: @code{.include "@var{file}"}
2735 * Int:: @code{.int @var{expressions}}
2736 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2737 * Lflags:: @code{.lflags}
2738 @ifclear no-line-dir
2739 * Line:: @code{.line @var{line-number}}
2742 * Ln:: @code{.ln @var{line-number}}
2743 * List:: @code{.list}
2744 * Long:: @code{.long @var{expressions}}
2746 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2749 * Nolist:: @code{.nolist}
2750 * Octa:: @code{.octa @var{bignums}}
2751 * Org:: @code{.org @var{new-lc} , @var{fill}}
2752 * P2align:: @code{.p2align @var{abs-expr} , @var{abs-expr}}
2753 * Psize:: @code{.psize @var{lines}, @var{columns}}
2754 * Quad:: @code{.quad @var{bignums}}
2755 * Sbttl:: @code{.sbttl "@var{subheading}"}
2757 * Scl:: @code{.scl @var{class}}
2760 * Section:: @code{.section @var{name}, @var{subsection}}
2763 * Set:: @code{.set @var{symbol}, @var{expression}}
2764 * Short:: @code{.short @var{expressions}}
2765 * Single:: @code{.single @var{flonums}}
2767 * Size:: @code{.size}
2770 * Space:: @code{.space @var{size} , @var{fill}}
2772 * Stab:: @code{.stabd, .stabn, .stabs}
2775 * String:: @code{.string "@var{str}"}
2777 * Tag:: @code{.tag @var{structname}}
2780 * Text:: @code{.text @var{subsection}}
2781 * Title:: @code{.title "@var{heading}"}
2783 * Type:: @code{.type @var{int}}
2784 * Val:: @code{.val @var{addr}}
2787 * Word:: @code{.word @var{expressions}}
2788 * Deprecated:: Deprecated Directives
2792 @section @code{.abort}
2794 @cindex @code{abort} directive
2795 @cindex stopping the assembly
2796 This directive stops the assembly immediately. It is for
2797 compatibility with other assemblers. The original idea was that the
2798 assembly language source would be piped into the assembler. If the sender
2799 of the source quit, it could use this directive tells @code{@value{AS}} to
2800 quit also. One day @code{.abort} will not be supported.
2804 @section @code{.ABORT}
2806 @cindex @code{ABORT} directive
2807 When producing COFF output, @code{@value{AS}} accepts this directive as a
2808 synonym for @samp{.abort}.
2811 When producing @code{b.out} output, @code{@value{AS}} accepts this directive,
2817 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2819 @cindex padding the location counter
2820 @cindex @code{align} directive
2821 Pad the location counter (in the current subsection) to a particular
2822 storage boundary. The first expression (which must be absolute) is the
2823 alignment required, as described below.
2824 The second expression (also absolute) gives the value to be stored in
2825 the padding bytes. It (and the comma) may be omitted. If it is
2826 omitted, the padding bytes are zero.
2828 The way the required alignment is specified varies from system to system.
2829 For the a29k, HPPA, m86k, m88k, w65, sparc, and i386 using ELF format,
2830 the first expression is the
2831 alignment request in bytes. For example @samp{.align 8} advances
2832 the location counter until it is a multiple of 8. If the location counter
2833 is already a multiple of 8, no change is needed.
2835 For other systems, including the i386 using a.out format, it is the
2836 number of low-order zero bits the location counter must have after
2837 advancement. For example @samp{.align 3} advances the location
2838 counter until it a multiple of 8. If the location counter is already a
2839 multiple of 8, no change is needed.
2841 This inconsistency is due to the different behaviors of the various
2842 native assemblers for these systems which GAS must emulate.
2843 GAS also provides @code{.balign} and @code{.p2align} directives,
2844 described later, which have a consistent behavior across all
2845 architectures (but are specific to GAS).
2848 @section @code{.app-file @var{string}}
2850 @cindex logical file name
2851 @cindex file name, logical
2852 @cindex @code{app-file} directive
2854 @ifclear no-file-dir
2855 (which may also be spelled @samp{.file})
2857 tells @code{@value{AS}} that we are about to start a new
2858 logical file. @var{string} is the new file name. In general, the
2859 filename is recognized whether or not it is surrounded by quotes @samp{"};
2860 but if you wish to specify an empty file name is permitted,
2861 you must give the quotes--@code{""}. This statement may go away in
2862 future: it is only recognized to be compatible with old @code{@value{AS}}
2866 @section @code{.ascii "@var{string}"}@dots{}
2868 @cindex @code{ascii} directive
2869 @cindex string literals
2870 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2871 separated by commas. It assembles each string (with no automatic
2872 trailing zero byte) into consecutive addresses.
2875 @section @code{.asciz "@var{string}"}@dots{}
2877 @cindex @code{asciz} directive
2878 @cindex zero-terminated strings
2879 @cindex null-terminated strings
2880 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2881 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2884 @section @code{.balign @var{abs-expr} , @var{abs-expr}}
2886 @cindex padding the location counter given number of bytes
2887 @cindex @code{balign} directive
2888 Pad the location counter (in the current subsection) to a particular
2889 storage boundary. The first expression (which must be absolute) is the
2890 alignment request in bytes. For example @samp{.balign 8} advances
2891 the location counter until it is a multiple of 8. If the location counter
2892 is already a multiple of 8, no change is needed.
2894 The second expression (also absolute) gives the value to be stored in
2895 the padding bytes. It (and the comma) may be omitted. If it is
2896 omitted, the padding bytes are zero.
2899 @section @code{.byte @var{expressions}}
2901 @cindex @code{byte} directive
2902 @cindex integers, one byte
2903 @code{.byte} expects zero or more expressions, separated by commas.
2904 Each expression is assembled into the next byte.
2907 @section @code{.comm @var{symbol} , @var{length} }
2909 @cindex @code{comm} directive
2910 @cindex symbol, common
2911 @code{.comm} declares a named common area in the bss section. Normally
2912 @code{@value{LD}} reserves memory addresses for it during linking, so no partial
2913 program defines the location of the symbol. Use @code{.comm} to tell
2914 @code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}}
2915 allocates space for each @code{.comm} symbol that is at least as
2916 long as the longest @code{.comm} request in any of the partial programs
2917 linked. @var{length} is an absolute expression.
2920 The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
2921 @samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
2925 @section @code{.data @var{subsection}}
2927 @cindex @code{data} directive
2928 @code{.data} tells @code{@value{AS}} to assemble the following statements onto the
2929 end of the data subsection numbered @var{subsection} (which is an
2930 absolute expression). If @var{subsection} is omitted, it defaults
2935 @section @code{.def @var{name}}
2937 @cindex @code{def} directive
2938 @cindex COFF symbols, debugging
2939 @cindex debugging COFF symbols
2940 Begin defining debugging information for a symbol @var{name}; the
2941 definition extends until the @code{.endef} directive is encountered.
2944 This directive is only observed when @code{@value{AS}} is configured for COFF
2945 format output; when producing @code{b.out}, @samp{.def} is recognized,
2952 @section @code{.desc @var{symbol}, @var{abs-expression}}
2954 @cindex @code{desc} directive
2955 @cindex COFF symbol descriptor
2956 @cindex symbol descriptor, COFF
2957 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2958 to the low 16 bits of an absolute expression.
2961 The @samp{.desc} directive is not available when @code{@value{AS}} is
2962 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2963 object format. For the sake of compatibility, @code{@value{AS}} accepts
2964 it, but produces no output, when configured for COFF.
2970 @section @code{.dim}
2972 @cindex @code{dim} directive
2973 @cindex COFF auxiliary symbol information
2974 @cindex auxiliary symbol information, COFF
2975 This directive is generated by compilers to include auxiliary debugging
2976 information in the symbol table. It is only permitted inside
2977 @code{.def}/@code{.endef} pairs.
2980 @samp{.dim} is only meaningful when generating COFF format output; when
2981 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
2987 @section @code{.double @var{flonums}}
2989 @cindex @code{double} directive
2990 @cindex floating point numbers (double)
2991 @code{.double} expects zero or more flonums, separated by commas. It
2992 assembles floating point numbers.
2994 The exact kind of floating point numbers emitted depends on how
2995 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
2999 On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
3000 in @sc{ieee} format.
3005 @section @code{.eject}
3007 @cindex @code{eject} directive
3008 @cindex new page, in listings
3009 @cindex page, in listings
3010 @cindex listing control: new page
3011 Force a page break at this point, when generating assembly listings.
3014 @section @code{.else}
3016 @cindex @code{else} directive
3017 @code{.else} is part of the @code{@value{AS}} support for conditional
3018 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
3019 of code to be assembled if the condition for the preceding @code{.if}
3023 @node End, Endef, Else, Pseudo Ops
3024 @section @code{.end}
3026 @cindex @code{end} directive
3027 This doesn't do anything---but isn't an s_ignore, so I suspect it's
3028 meant to do something eventually (which is why it isn't documented here
3029 as "for compatibility with blah").
3034 @section @code{.endef}
3036 @cindex @code{endef} directive
3037 This directive flags the end of a symbol definition begun with
3041 @samp{.endef} is only meaningful when generating COFF format output; if
3042 @code{@value{AS}} is configured to generate @code{b.out}, it accepts this
3043 directive but ignores it.
3048 @section @code{.endif}
3050 @cindex @code{endif} directive
3051 @code{.endif} is part of the @code{@value{AS}} support for conditional assembly;
3052 it marks the end of a block of code that is only assembled
3053 conditionally. @xref{If,,@code{.if}}.
3056 @section @code{.equ @var{symbol}, @var{expression}}
3058 @cindex @code{equ} directive
3059 @cindex assigning values to symbols
3060 @cindex symbols, assigning values to
3061 This directive sets the value of @var{symbol} to @var{expression}.
3062 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
3065 The syntax for @code{equ} on the HPPA is
3066 @samp{@var{symbol} .equ @var{expression}}.
3070 @section @code{.extern}
3072 @cindex @code{extern} directive
3073 @code{.extern} is accepted in the source program---for compatibility
3074 with other assemblers---but it is ignored. @code{@value{AS}} treats
3075 all undefined symbols as external.
3077 @ifclear no-file-dir
3079 @section @code{.file @var{string}}
3081 @cindex @code{file} directive
3082 @cindex logical file name
3083 @cindex file name, logical
3084 @code{.file} (which may also be spelled @samp{.app-file}) tells
3085 @code{@value{AS}} that we are about to start a new logical file.
3086 @var{string} is the new file name. In general, the filename is
3087 recognized whether or not it is surrounded by quotes @samp{"}; but if
3088 you wish to specify an empty file name, you must give the
3089 quotes--@code{""}. This statement may go away in future: it is only
3090 recognized to be compatible with old @code{@value{AS}} programs.
3092 In some configurations of @code{@value{AS}}, @code{.file} has already been
3093 removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}.
3098 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
3100 @cindex @code{fill} directive
3101 @cindex writing patterns in memory
3102 @cindex patterns, writing in memory
3103 @var{result}, @var{size} and @var{value} are absolute expressions.
3104 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
3105 may be zero or more. @var{Size} may be zero or more, but if it is
3106 more than 8, then it is deemed to have the value 8, compatible with
3107 other people's assemblers. The contents of each @var{repeat} bytes
3108 is taken from an 8-byte number. The highest order 4 bytes are
3109 zero. The lowest order 4 bytes are @var{value} rendered in the
3110 byte-order of an integer on the computer @code{@value{AS}} is assembling for.
3111 Each @var{size} bytes in a repetition is taken from the lowest order
3112 @var{size} bytes of this number. Again, this bizarre behavior is
3113 compatible with other people's assemblers.
3115 @var{size} and @var{value} are optional.
3116 If the second comma and @var{value} are absent, @var{value} is
3117 assumed zero. If the first comma and following tokens are absent,
3118 @var{size} is assumed to be 1.
3121 @section @code{.float @var{flonums}}
3123 @cindex floating point numbers (single)
3124 @cindex @code{float} directive
3125 This directive assembles zero or more flonums, separated by commas. It
3126 has the same effect as @code{.single}.
3128 The exact kind of floating point numbers emitted depends on how
3129 @code{@value{AS}} is configured.
3130 @xref{Machine Dependencies}.
3134 On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
3135 in @sc{ieee} format.
3140 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
3142 @cindex @code{global} directive
3143 @cindex symbol, making visible to linker
3144 @code{.global} makes the symbol visible to @code{@value{LD}}. If you define
3145 @var{symbol} in your partial program, its value is made available to
3146 other partial programs that are linked with it. Otherwise,
3147 @var{symbol} takes its attributes from a symbol of the same name
3148 from another file linked into the same program.
3150 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
3151 compatibility with other assemblers.
3154 On the HPPA, @code{.global} is not always enough to make it accessible to other
3155 partial programs. You may need the HPPA-only @code{.EXPORT} directive as well.
3156 @xref{HPPA Directives,, HPPA Assembler Directives}.
3160 @section @code{.hword @var{expressions}}
3162 @cindex @code{hword} directive
3163 @cindex integers, 16-bit
3164 @cindex numbers, 16-bit
3165 @cindex sixteen bit integers
3166 This expects zero or more @var{expressions}, and emits
3167 a 16 bit number for each.
3170 This directive is a synonym for @samp{.short}; depending on the target
3171 architecture, it may also be a synonym for @samp{.word}.
3175 This directive is a synonym for @samp{.short}.
3178 This directive is a synonym for both @samp{.short} and @samp{.word}.
3183 @section @code{.ident}
3185 @cindex @code{ident} directive
3186 This directive is used by some assemblers to place tags in object files.
3187 @code{@value{AS}} simply accepts the directive for source-file
3188 compatibility with such assemblers, but does not actually emit anything
3192 @section @code{.if @var{absolute expression}}
3194 @cindex conditional assembly
3195 @cindex @code{if} directive
3196 @code{.if} marks the beginning of a section of code which is only
3197 considered part of the source program being assembled if the argument
3198 (which must be an @var{absolute expression}) is non-zero. The end of
3199 the conditional section of code must be marked by @code{.endif}
3200 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
3201 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
3203 The following variants of @code{.if} are also supported:
3205 @item .ifdef @var{symbol}
3206 @cindex @code{ifdef} directive
3207 Assembles the following section of code if the specified @var{symbol}
3212 @cindex @code{ifeqs} directive
3213 Not yet implemented.
3216 @item .ifndef @var{symbol}
3217 @itemx ifnotdef @var{symbol}
3218 @cindex @code{ifndef} directive
3219 @cindex @code{ifnotdef} directive
3220 Assembles the following section of code if the specified @var{symbol}
3221 has not been defined. Both spelling variants are equivalent.
3225 Not yet implemented.
3230 @section @code{.include "@var{file}"}
3232 @cindex @code{include} directive
3233 @cindex supporting files, including
3234 @cindex files, including
3235 This directive provides a way to include supporting files at specified
3236 points in your source program. The code from @var{file} is assembled as
3237 if it followed the point of the @code{.include}; when the end of the
3238 included file is reached, assembly of the original file continues. You
3239 can control the search paths used with the @samp{-I} command-line option
3240 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
3244 @section @code{.int @var{expressions}}
3246 @cindex @code{int} directive
3247 @cindex integers, 32-bit
3248 Expect zero or more @var{expressions}, of any section, separated by commas.
3249 For each expression, emit a number that, at run time, is the value of that
3250 expression. The byte order and bit size of the number depends on what kind
3251 of target the assembly is for.
3255 On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
3256 integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits
3262 @section @code{.lcomm @var{symbol} , @var{length}}
3264 @cindex @code{lcomm} directive
3265 @cindex local common symbols
3266 @cindex symbols, local common
3267 Reserve @var{length} (an absolute expression) bytes for a local common
3268 denoted by @var{symbol}. The section and value of @var{symbol} are
3269 those of the new local common. The addresses are allocated in the bss
3270 section, so that at run-time the bytes start off zeroed. @var{Symbol}
3271 is not declared global (@pxref{Global,,@code{.global}}), so is normally
3272 not visible to @code{@value{LD}}.
3275 The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
3276 @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
3280 @section @code{.lflags}
3282 @cindex @code{lflags} directive (ignored)
3283 @code{@value{AS}} accepts this directive, for compatibility with other
3284 assemblers, but ignores it.
3286 @ifclear no-line-dir
3288 @section @code{.line @var{line-number}}
3290 @cindex @code{line} directive
3294 @section @code{.ln @var{line-number}}
3296 @cindex @code{ln} directive
3298 @cindex logical line number
3300 Change the logical line number. @var{line-number} must be an absolute
3301 expression. The next line has that logical line number. Therefore any other
3302 statements on the current line (after a statement separator character) are
3303 reported as on logical line number @var{line-number} @minus{} 1. One day
3304 @code{@value{AS}} will no longer support this directive: it is recognized only
3305 for compatibility with existing assembler programs.
3309 @emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
3310 not available; use the synonym @code{.ln} in that context.
3315 @ifclear no-line-dir
3316 Even though this is a directive associated with the @code{a.out} or
3317 @code{b.out} object-code formats, @code{@value{AS}} still recognizes it
3318 when producing COFF output, and treats @samp{.line} as though it
3319 were the COFF @samp{.ln} @emph{if} it is found outside a
3320 @code{.def}/@code{.endef} pair.
3322 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
3323 used by compilers to generate auxiliary symbol information for
3328 @section @code{.ln @var{line-number}}
3330 @cindex @code{ln} directive
3331 @ifclear no-line-dir
3332 @samp{.ln} is a synonym for @samp{.line}.
3335 Tell @code{@value{AS}} to change the logical line number. @var{line-number}
3336 must be an absolute expression. The next line has that logical
3337 line number, so any other statements on the current line (after a
3338 statement separator character @code{;}) are reported as on logical
3339 line number @var{line-number} @minus{} 1.
3342 This directive is accepted, but ignored, when @code{@value{AS}} is
3343 configured for @code{b.out}; its effect is only associated with COFF
3349 @section @code{.list}
3351 @cindex @code{list} directive
3352 @cindex listing control, turning on
3353 Control (in conjunction with the @code{.nolist} directive) whether or
3354 not assembly listings are generated. These two directives maintain an
3355 internal counter (which is zero initially). @code{.list} increments the
3356 counter, and @code{.nolist} decrements it. Assembly listings are
3357 generated whenever the counter is greater than zero.
3359 By default, listings are disabled. When you enable them (with the
3360 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
3361 the initial value of the listing counter is one.
3364 @section @code{.long @var{expressions}}
3366 @cindex @code{long} directive
3367 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
3370 @c no one seems to know what this is for or whether this description is
3371 @c what it really ought to do
3373 @section @code{.lsym @var{symbol}, @var{expression}}
3375 @cindex @code{lsym} directive
3376 @cindex symbol, not referenced in assembly
3377 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
3378 the hash table, ensuring it cannot be referenced by name during the
3379 rest of the assembly. This sets the attributes of the symbol to be
3380 the same as the expression value:
3382 @var{other} = @var{descriptor} = 0
3383 @var{type} = @r{(section of @var{expression})}
3384 @var{value} = @var{expression}
3387 The new symbol is not flagged as external.
3391 @section @code{.nolist}
3393 @cindex @code{nolist} directive
3394 @cindex listing control, turning off
3395 Control (in conjunction with the @code{.list} directive) whether or
3396 not assembly listings are generated. These two directives maintain an
3397 internal counter (which is zero initially). @code{.list} increments the
3398 counter, and @code{.nolist} decrements it. Assembly listings are
3399 generated whenever the counter is greater than zero.
3402 @section @code{.octa @var{bignums}}
3404 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
3405 @cindex @code{octa} directive
3406 @cindex integer, 16-byte
3407 @cindex sixteen byte integer
3408 This directive expects zero or more bignums, separated by commas. For each
3409 bignum, it emits a 16-byte integer.
3411 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
3412 hence @emph{octa}-word for 16 bytes.
3415 @section @code{.org @var{new-lc} , @var{fill}}
3417 @cindex @code{org} directive
3418 @cindex location counter, advancing
3419 @cindex advancing location counter
3420 @cindex current address, advancing
3421 Advance the location counter of the current section to
3422 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3423 expression with the same section as the current subsection. That is,
3424 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3425 wrong section, the @code{.org} directive is ignored. To be compatible
3426 with former assemblers, if the section of @var{new-lc} is absolute,
3427 @code{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
3428 is the same as the current subsection.
3430 @code{.org} may only increase the location counter, or leave it
3431 unchanged; you cannot use @code{.org} to move the location counter
3434 @c double negative used below "not undefined" because this is a specific
3435 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3436 @c section. pesch@cygnus.com 18feb91
3437 Because @code{@value{AS}} tries to assemble programs in one pass, @var{new-lc}
3438 may not be undefined. If you really detest this restriction we eagerly await
3439 a chance to share your improved assembler.
3441 Beware that the origin is relative to the start of the section, not
3442 to the start of the subsection. This is compatible with other
3443 people's assemblers.
3445 When the location counter (of the current subsection) is advanced, the
3446 intervening bytes are filled with @var{fill} which should be an
3447 absolute expression. If the comma and @var{fill} are omitted,
3448 @var{fill} defaults to zero.
3451 @section @code{.p2align @var{abs-expr} , @var{abs-expr}}
3453 @cindex padding the location counter given a power of two
3454 @cindex @code{p2align} directive
3455 Pad the location counter (in the current subsection) to a particular
3456 storage boundary. The first expression (which must be absolute) is the
3457 number of low-order zero bits the location counter must have after
3458 advancement. For example @samp{.p2align 3} advances the location
3459 counter until it a multiple of 8. If the location counter is already a
3460 multiple of 8, no change is needed.
3462 The second expression (also absolute) gives the value to be stored in
3463 the padding bytes. It (and the comma) may be omitted. If it is
3464 omitted, the padding bytes are zero.
3467 @section @code{.psize @var{lines} , @var{columns}}
3469 @cindex @code{psize} directive
3470 @cindex listing control: paper size
3471 @cindex paper size, for listings
3472 Use this directive to declare the number of lines---and, optionally, the
3473 number of columns---to use for each page, when generating listings.
3475 If you do not use @code{.psize}, listings use a default line-count
3476 of 60. You may omit the comma and @var{columns} specification; the
3477 default width is 200 columns.
3479 @code{@value{AS}} generates formfeeds whenever the specified number of
3480 lines is exceeded (or whenever you explicitly request one, using
3483 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3484 those explicitly specified with @code{.eject}.
3487 @section @code{.quad @var{bignums}}
3489 @cindex @code{quad} directive
3490 @code{.quad} expects zero or more bignums, separated by commas. For
3491 each bignum, it emits
3493 an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
3494 warning message; and just takes the lowest order 8 bytes of the bignum.
3495 @cindex eight-byte integer
3496 @cindex integer, 8-byte
3498 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3499 hence @emph{quad}-word for 8 bytes.
3502 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3503 warning message; and just takes the lowest order 16 bytes of the bignum.
3504 @cindex sixteen-byte integer
3505 @cindex integer, 16-byte
3509 @section @code{.sbttl "@var{subheading}"}
3511 @cindex @code{sbttl} directive
3512 @cindex subtitles for listings
3513 @cindex listing control: subtitle
3514 Use @var{subheading} as the title (third line, immediately after the
3515 title line) when generating assembly listings.
3517 This directive affects subsequent pages, as well as the current page if
3518 it appears within ten lines of the top of a page.
3522 @section @code{.scl @var{class}}
3524 @cindex @code{scl} directive
3525 @cindex symbol storage class (COFF)
3526 @cindex COFF symbol storage class
3527 Set the storage-class value for a symbol. This directive may only be
3528 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3529 whether a symbol is static or external, or it may record further
3530 symbolic debugging information.
3533 The @samp{.scl} directive is primarily associated with COFF output; when
3534 configured to generate @code{b.out} output format, @code{@value{AS}}
3535 accepts this directive but ignores it.
3541 @section @code{.section @var{name}, @var{subsection}}
3543 @cindex @code{section} directive
3544 @cindex named section (COFF)
3545 @cindex COFF named section
3546 Assemble the following code into end of subsection numbered
3547 @var{subsection} in the COFF named section @var{name}. If you omit
3548 @var{subsection}, @code{@value{AS}} uses subsection number zero.
3549 @samp{.section .text} is equivalent to the @code{.text} directive;
3550 @samp{.section .data} is equivalent to the @code{.data} directive.
3552 This directive is only supported for targets that actually support arbitrarily
3553 named sections; on @code{a.out} targets, for example, it is not accepted, even
3554 with a standard @code{a.out} section name as its parameter.
3559 @section @code{.set @var{symbol}, @var{expression}}
3561 @cindex @code{set} directive
3562 @cindex symbol value, setting
3563 Set the value of @var{symbol} to @var{expression}. This
3564 changes @var{symbol}'s value and type to conform to
3565 @var{expression}. If @var{symbol} was flagged as external, it remains
3566 flagged. (@xref{Symbol Attributes}.)
3568 You may @code{.set} a symbol many times in the same assembly.
3570 If you @code{.set} a global symbol, the value stored in the object
3571 file is the last value stored into it.
3574 The syntax for @code{set} on the HPPA is
3575 @samp{@var{symbol} .set @var{expression}}.
3579 @section @code{.short @var{expressions}}
3581 @cindex @code{short} directive
3583 @code{.short} is normally the same as @samp{.word}.
3584 @xref{Word,,@code{.word}}.
3586 In some configurations, however, @code{.short} and @code{.word} generate
3587 numbers of different lengths; @pxref{Machine Dependencies}.
3591 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3594 This expects zero or more @var{expressions}, and emits
3595 a 16 bit number for each.
3600 @section @code{.single @var{flonums}}
3602 @cindex @code{single} directive
3603 @cindex floating point numbers (single)
3604 This directive assembles zero or more flonums, separated by commas. It
3605 has the same effect as @code{.float}.
3607 The exact kind of floating point numbers emitted depends on how
3608 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
3612 On the @value{TARGET} family, @code{.single} emits 32-bit floating point
3613 numbers in @sc{ieee} format.
3619 @section @code{.size}
3621 @cindex @code{size} directive
3622 This directive is generated by compilers to include auxiliary debugging
3623 information in the symbol table. It is only permitted inside
3624 @code{.def}/@code{.endef} pairs.
3627 @samp{.size} is only meaningful when generating COFF format output; when
3628 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3633 @ifclear no-space-dir
3635 @section @code{.space @var{size} , @var{fill}}
3637 @cindex @code{space} directive
3638 @cindex filling memory
3639 This directive emits @var{size} bytes, each of value @var{fill}. Both
3640 @var{size} and @var{fill} are absolute expressions. If the comma
3641 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3645 @emph{Warning:} @code{.space} has a completely different meaning for HPPA
3646 targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800
3647 Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the
3648 @code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives},
3657 @section @code{.space}
3658 @cindex @code{space} directive
3660 On the AMD 29K, this directive is ignored; it is accepted for
3661 compatibility with other AMD 29K assemblers.
3664 @emph{Warning:} In most versions of the @sc{gnu} assembler, the directive
3665 @code{.space} has the effect of @code{.block} @xref{Machine Dependencies}.
3671 @section @code{.stabd, .stabn, .stabs}
3673 @cindex symbolic debuggers, information for
3674 @cindex @code{stab@var{x}} directives
3675 There are three directives that begin @samp{.stab}.
3676 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3677 The symbols are not entered in the @code{@value{AS}} hash table: they
3678 cannot be referenced elsewhere in the source file.
3679 Up to five fields are required:
3683 This is the symbol's name. It may contain any character except
3684 @samp{\000}, so is more general than ordinary symbol names. Some
3685 debuggers used to code arbitrarily complex structures into symbol names
3689 An absolute expression. The symbol's type is set to the low 8 bits of
3690 this expression. Any bit pattern is permitted, but @code{@value{LD}}
3691 and debuggers choke on silly bit patterns.
3694 An absolute expression. The symbol's ``other'' attribute is set to the
3695 low 8 bits of this expression.
3698 An absolute expression. The symbol's descriptor is set to the low 16
3699 bits of this expression.
3702 An absolute expression which becomes the symbol's value.
3705 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3706 or @code{.stabs} statement, the symbol has probably already been created;
3707 you get a half-formed symbol in your object file. This is
3708 compatible with earlier assemblers!
3711 @cindex @code{stabd} directive
3712 @item .stabd @var{type} , @var{other} , @var{desc}
3714 The ``name'' of the symbol generated is not even an empty string.
3715 It is a null pointer, for compatibility. Older assemblers used a
3716 null pointer so they didn't waste space in object files with empty
3719 The symbol's value is set to the location counter,
3720 relocatably. When your program is linked, the value of this symbol
3721 is the address of the location counter when the @code{.stabd} was
3724 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3725 @cindex @code{stabn} directive
3726 The name of the symbol is set to the empty string @code{""}.
3728 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3729 @cindex @code{stabs} directive
3730 All five fields are specified.
3736 @section @code{.string} "@var{str}"
3738 @cindex string, copying to object file
3739 @cindex @code{string} directive
3741 Copy the characters in @var{str} to the object file. You may specify more than
3742 one string to copy, separated by commas. Unless otherwise specified for a
3743 particular machine, the assembler marks the end of each string with a 0 byte.
3744 You can use any of the escape sequences described in @ref{Strings,,Strings}.
3748 @section @code{.tag @var{structname}}
3750 @cindex COFF structure debugging
3751 @cindex structure debugging, COFF
3752 @cindex @code{tag} directive
3753 This directive is generated by compilers to include auxiliary debugging
3754 information in the symbol table. It is only permitted inside
3755 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3756 definitions in the symbol table with instances of those structures.
3759 @samp{.tag} is only used when generating COFF format output; when
3760 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3766 @section @code{.text @var{subsection}}
3768 @cindex @code{text} directive
3769 Tells @code{@value{AS}} to assemble the following statements onto the end of
3770 the text subsection numbered @var{subsection}, which is an absolute
3771 expression. If @var{subsection} is omitted, subsection number zero
3775 @section @code{.title "@var{heading}"}
3777 @cindex @code{title} directive
3778 @cindex listing control: title line
3779 Use @var{heading} as the title (second line, immediately after the
3780 source file name and pagenumber) when generating assembly listings.
3782 This directive affects subsequent pages, as well as the current page if
3783 it appears within ten lines of the top of a page.
3787 @section @code{.type @var{int}}
3789 @cindex COFF symbol type
3790 @cindex symbol type, COFF
3791 @cindex @code{type} directive
3792 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3793 records the integer @var{int} as the type attribute of a symbol table entry.
3796 @samp{.type} is associated only with COFF format output; when
3797 @code{@value{AS}} is configured for @code{b.out} output, it accepts this
3798 directive but ignores it.
3804 @section @code{.val @var{addr}}
3806 @cindex @code{val} directive
3807 @cindex COFF value attribute
3808 @cindex value attribute, COFF
3809 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3810 records the address @var{addr} as the value attribute of a symbol table
3814 @samp{.val} is used only for COFF output; when @code{@value{AS}} is
3815 configured for @code{b.out}, it accepts this directive but ignores it.
3820 @section @code{.word @var{expressions}}
3822 @cindex @code{word} directive
3823 This directive expects zero or more @var{expressions}, of any section,
3824 separated by commas.
3827 For each expression, @code{@value{AS}} emits a 32-bit number.
3830 For each expression, @code{@value{AS}} emits a 16-bit number.
3835 The size of the number emitted, and its byte order,
3836 depend on what target computer the assembly is for.
3839 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3840 @c happen---32-bit addressability, period; no long/short jumps.
3841 @ifset DIFF-TBL-KLUGE
3842 @cindex difference tables altered
3843 @cindex altered difference tables
3845 @emph{Warning: Special Treatment to support Compilers}
3849 Machines with a 32-bit address space, but that do less than 32-bit
3850 addressing, require the following special treatment. If the machine of
3851 interest to you does 32-bit addressing (or doesn't require it;
3852 @pxref{Machine Dependencies}), you can ignore this issue.
3855 In order to assemble compiler output into something that works,
3856 @code{@value{AS}} occasionlly does strange things to @samp{.word} directives.
3857 Directives of the form @samp{.word sym1-sym2} are often emitted by
3858 compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a
3859 directive of the form @samp{.word sym1-sym2}, and the difference between
3860 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}}
3861 creates a @dfn{secondary jump table}, immediately before the next label.
3862 This secondary jump table is preceded by a short-jump to the
3863 first byte after the secondary table. This short-jump prevents the flow
3864 of control from accidentally falling into the new table. Inside the
3865 table is a long-jump to @code{sym2}. The original @samp{.word}
3866 contains @code{sym1} minus the address of the long-jump to
3869 If there were several occurrences of @samp{.word sym1-sym2} before the
3870 secondary jump table, all of them are adjusted. If there was a
3871 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3872 long-jump to @code{sym4} is included in the secondary jump table,
3873 and the @code{.word} directives are adjusted to contain @code{sym3}
3874 minus the address of the long-jump to @code{sym4}; and so on, for as many
3875 entries in the original jump table as necessary.
3878 @emph{This feature may be disabled by compiling @code{@value{AS}} with the
3879 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3880 assembly language programmers.
3883 @c end DIFF-TBL-KLUGE
3886 @section Deprecated Directives
3888 @cindex deprecated directives
3889 @cindex obsolescent directives
3890 One day these directives won't work.
3891 They are included for compatibility with older assemblers.
3899 @node Machine Dependencies
3900 @chapter Machine Dependent Features
3902 @cindex machine dependencies
3903 The machine instruction sets are (almost by definition) different on
3904 each machine where @code{@value{AS}} runs. Floating point representations
3905 vary as well, and @code{@value{AS}} often supports a few additional
3906 directives or command-line options for compatibility with other
3907 assemblers on a particular platform. Finally, some versions of
3908 @code{@value{AS}} support special pseudo-instructions for branch
3911 This chapter discusses most of these differences, though it does not
3912 include details on any machine's instruction set. For details on that
3913 subject, see the hardware manufacturer's manual.
3916 @c start-sanitize-arc
3918 * ARC-Dependent:: ARC Dependent Features
3922 * Vax-Dependent:: VAX Dependent Features
3925 * AMD29K-Dependent:: AMD 29K Dependent Features
3928 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
3931 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
3934 * HPPA-Dependent:: HPPA Dependent Features
3937 * SH-Dependent:: Hitachi SH Dependent Features
3940 * i960-Dependent:: Intel 80960 Dependent Features
3943 * M68K-Dependent:: M680x0 Dependent Features
3946 * Sparc-Dependent:: SPARC Dependent Features
3949 * Z8000-Dependent:: Z8000 Dependent Features
3952 * MIPS-Dependent:: MIPS Dependent Features
3955 * i386-Dependent:: 80386 Dependent Features
3962 @c The following major nodes are *sections* in the GENERIC version, *chapters*
3963 @c in single-cpu versions. This is mainly achieved by @lowersections. There is a
3964 @c peculiarity: to preserve cross-references, there must be a node called
3965 @c "Machine Dependencies". Hence the conditional nodenames in each
3966 @c major node below. Node defaulting in makeinfo requires adjacency of
3967 @c node and sectioning commands; hence the repetition of @chapter BLAH
3968 @c in both conditional blocks.
3970 @c start-sanitize-arc
3975 @chapter ARC Dependent Features
3978 @node Machine Dependencies
3979 @chapter ARC Dependent Features
3984 * ARC-Opts:: Options
3985 * ARC-Float:: Floating Point
3986 * ARC-Directives:: Sparc Machine Directives
3992 @cindex options for ARC
3994 @cindex architectures, ARC
3995 @cindex ARC architectures
3996 The ARC chip family includes several successive levels (or other
3997 variants) of chip, using the same core instruction set, but including
3998 a few additional instructions at each level.
4000 By default, @code{@value{AS}} assumes the core instruction set (ARC
4001 base). The @code{.cpu} pseudo-op is used to select a different variant.
4004 @cindex @code{-mbig-endian} option (ARC)
4005 @cindex @code{-mlittle-endian} option (ARC)
4006 @cindex ARC big-endian output
4007 @cindex ARC little-endian output
4008 @cindex big-endian output, ARC
4009 @cindex little-endian output, ARC
4011 @itemx -mlittle-endian
4012 Any @sc{arc} configuration of @code{@value{AS}} can select big-endian or
4013 little-endian output at run time (unlike most other @sc{gnu} development
4014 tools, which must be configured for one or the other). Use
4015 @samp{-mbig-endian} to select big-endian output, and @samp{-mlittle-endian}
4020 @section Floating Point
4022 @cindex floating point, ARC (@sc{ieee})
4023 @cindex ARC floating point (@sc{ieee})
4024 The ARC cpu family currently does not have hardware floating point
4025 support. Software floating point support is provided by @code{GCC}
4026 and uses @sc{ieee} floating-point numbers.
4028 @node ARC-Directives
4029 @section ARC Machine Directives
4031 @cindex ARC machine directives
4032 @cindex machine directives, ARC
4033 The ARC version of @code{@value{AS}} supports the following additional
4038 @cindex @code{cpu} directive, SPARC
4039 This must be followed by the desired cpu. It must be one of
4040 @code{base}, @code{host}, @code{graphics}, or @code{audio}.
4050 @chapter VAX Dependent Features
4055 @node Machine Dependencies
4056 @chapter VAX Dependent Features
4062 * Vax-Opts:: VAX Command-Line Options
4063 * VAX-float:: VAX Floating Point
4064 * VAX-directives:: Vax Machine Directives
4065 * VAX-opcodes:: VAX Opcodes
4066 * VAX-branch:: VAX Branch Improvement
4067 * VAX-operands:: VAX Operands
4068 * VAX-no:: Not Supported on VAX
4073 @section VAX Command-Line Options
4075 @cindex command-line options ignored, VAX
4076 @cindex VAX command-line options ignored
4077 The Vax version of @code{@value{AS}} accepts any of the following options,
4078 gives a warning message that the option was ignored and proceeds.
4079 These options are for compatibility with scripts designed for other
4080 people's assemblers.
4083 @item @code{-D} (Debug)
4084 @itemx @code{-S} (Symbol Table)
4085 @itemx @code{-T} (Token Trace)
4086 @cindex @code{-D}, ignored on VAX
4087 @cindex @code{-S}, ignored on VAX
4088 @cindex @code{-T}, ignored on VAX
4089 These are obsolete options used to debug old assemblers.
4091 @item @code{-d} (Displacement size for JUMPs)
4092 @cindex @code{-d}, VAX option
4093 This option expects a number following the @samp{-d}. Like options
4094 that expect filenames, the number may immediately follow the
4095 @samp{-d} (old standard) or constitute the whole of the command line
4096 argument that follows @samp{-d} (@sc{gnu} standard).
4098 @item @code{-V} (Virtualize Interpass Temporary File)
4099 @cindex @code{-V}, redundant on VAX
4100 Some other assemblers use a temporary file. This option
4101 commanded them to keep the information in active memory rather
4102 than in a disk file. @code{@value{AS}} always does this, so this
4103 option is redundant.
4105 @item @code{-J} (JUMPify Longer Branches)
4106 @cindex @code{-J}, ignored on VAX
4107 Many 32-bit computers permit a variety of branch instructions
4108 to do the same job. Some of these instructions are short (and
4109 fast) but have a limited range; others are long (and slow) but
4110 can branch anywhere in virtual memory. Often there are 3
4111 flavors of branch: short, medium and long. Some other
4112 assemblers would emit short and medium branches, unless told by
4113 this option to emit short and long branches.
4115 @item @code{-t} (Temporary File Directory)
4116 @cindex @code{-t}, ignored on VAX
4117 Some other assemblers may use a temporary file, and this option
4118 takes a filename being the directory to site the temporary
4119 file. Since @code{@value{AS}} does not use a temporary disk file, this
4120 option makes no difference. @samp{-t} needs exactly one
4124 @cindex VMS (VAX) options
4125 @cindex options for VAX/VMS
4126 @cindex VAX/VMS options
4127 @cindex @code{-h} option, VAX/VMS
4128 @cindex @code{-+} option, VAX/VMS
4129 @cindex Vax-11 C compatibility
4130 @cindex symbols with lowercase, VAX/VMS
4131 @c FIXME! look into "I think" below, correct if needed, delete.
4132 The Vax version of the assembler accepts two options when
4133 compiled for VMS. They are @samp{-h}, and @samp{-+}. The
4134 @samp{-h} option prevents @code{@value{AS}} from modifying the
4135 symbol-table entries for symbols that contain lowercase
4136 characters (I think). The @samp{-+} option causes @code{@value{AS}} to
4137 print warning messages if the FILENAME part of the object file,
4138 or any symbol name is larger than 31 characters. The @samp{-+}
4139 option also inserts some code following the @samp{_main}
4140 symbol so that the object file is compatible with Vax-11
4144 @section VAX Floating Point
4146 @cindex VAX floating point
4147 @cindex floating point, VAX
4148 Conversion of flonums to floating point is correct, and
4149 compatible with previous assemblers. Rounding is
4150 towards zero if the remainder is exactly half the least significant bit.
4152 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
4155 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
4156 are rendered correctly. Again, rounding is towards zero in the
4159 @cindex @code{float} directive, VAX
4160 @cindex @code{double} directive, VAX
4161 The @code{.float} directive produces @code{f} format numbers.
4162 The @code{.double} directive produces @code{d} format numbers.
4164 @node VAX-directives
4165 @section Vax Machine Directives
4167 @cindex machine directives, VAX
4168 @cindex VAX machine directives
4169 The Vax version of the assembler supports four directives for
4170 generating Vax floating point constants. They are described in the
4173 @cindex wide floating point directives, VAX
4176 @cindex @code{dfloat} directive, VAX
4177 This expects zero or more flonums, separated by commas, and
4178 assembles Vax @code{d} format 64-bit floating point constants.
4181 @cindex @code{ffloat} directive, VAX
4182 This expects zero or more flonums, separated by commas, and
4183 assembles Vax @code{f} format 32-bit floating point constants.
4186 @cindex @code{gfloat} directive, VAX
4187 This expects zero or more flonums, separated by commas, and
4188 assembles Vax @code{g} format 64-bit floating point constants.
4191 @cindex @code{hfloat} directive, VAX
4192 This expects zero or more flonums, separated by commas, and
4193 assembles Vax @code{h} format 128-bit floating point constants.
4198 @section VAX Opcodes
4200 @cindex VAX opcode mnemonics
4201 @cindex opcode mnemonics, VAX
4202 @cindex mnemonics for opcodes, VAX
4203 All DEC mnemonics are supported. Beware that @code{case@dots{}}
4204 instructions have exactly 3 operands. The dispatch table that
4205 follows the @code{case@dots{}} instruction should be made with
4206 @code{.word} statements. This is compatible with all unix
4207 assemblers we know of.
4210 @section VAX Branch Improvement
4212 @cindex VAX branch improvement
4213 @cindex branch improvement, VAX
4214 @cindex pseudo-ops for branch, VAX
4215 Certain pseudo opcodes are permitted. They are for branch
4216 instructions. They expand to the shortest branch instruction that
4217 reaches the target. Generally these mnemonics are made by
4218 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
4219 This feature is included both for compatibility and to help
4220 compilers. If you do not need this feature, avoid these
4221 opcodes. Here are the mnemonics, and the code they can expand into.
4225 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
4227 @item (byte displacement)
4229 @item (word displacement)
4231 @item (long displacement)
4236 Unconditional branch.
4238 @item (byte displacement)
4240 @item (word displacement)
4242 @item (long displacement)
4246 @var{COND} may be any one of the conditional branches
4247 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
4248 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
4249 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
4250 @var{COND} may also be one of the bit tests
4251 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
4252 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
4253 @var{NOTCOND} is the opposite condition to @var{COND}.
4255 @item (byte displacement)
4256 @kbd{b@var{COND} @dots{}}
4257 @item (word displacement)
4258 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
4259 @item (long displacement)
4260 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
4263 @var{X} may be one of @code{b d f g h l w}.
4265 @item (word displacement)
4266 @kbd{@var{OPCODE} @dots{}}
4267 @item (long displacement)
4269 @var{OPCODE} @dots{}, foo ;
4276 @var{YYY} may be one of @code{lss leq}.
4278 @var{ZZZ} may be one of @code{geq gtr}.
4280 @item (byte displacement)
4281 @kbd{@var{OPCODE} @dots{}}
4282 @item (word displacement)
4284 @var{OPCODE} @dots{}, foo ;
4286 foo: brw @var{destination} ;
4289 @item (long displacement)
4291 @var{OPCODE} @dots{}, foo ;
4293 foo: jmp @var{destination} ;
4302 @item (byte displacement)
4303 @kbd{@var{OPCODE} @dots{}}
4304 @item (word displacement)
4306 @var{OPCODE} @dots{}, foo ;
4308 foo: brw @var{destination} ;
4311 @item (long displacement)
4313 @var{OPCODE} @dots{}, foo ;
4315 foo: jmp @var{destination} ;
4322 @section VAX Operands
4324 @cindex VAX operand notation
4325 @cindex operand notation, VAX
4326 @cindex immediate character, VAX
4327 @cindex VAX immediate character
4328 The immediate character is @samp{$} for Unix compatibility, not
4329 @samp{#} as DEC writes it.
4331 @cindex indirect character, VAX
4332 @cindex VAX indirect character
4333 The indirect character is @samp{*} for Unix compatibility, not
4334 @samp{@@} as DEC writes it.
4336 @cindex displacement sizing character, VAX
4337 @cindex VAX displacement sizing character
4338 The displacement sizing character is @samp{`} (an accent grave) for
4339 Unix compatibility, not @samp{^} as DEC writes it. The letter
4340 preceding @samp{`} may have either case. @samp{G} is not
4341 understood, but all other letters (@code{b i l s w}) are understood.
4343 @cindex register names, VAX
4344 @cindex VAX register names
4345 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
4346 pc}. Upper and lower case letters are equivalent.
4353 Any expression is permitted in an operand. Operands are comma
4356 @c There is some bug to do with recognizing expressions
4357 @c in operands, but I forget what it is. It is
4358 @c a syntax clash because () is used as an address mode
4359 @c and to encapsulate sub-expressions.
4362 @section Not Supported on VAX
4364 @cindex VAX bitfields not supported
4365 @cindex bitfields, not supported on VAX
4366 Vax bit fields can not be assembled with @code{@value{AS}}. Someone
4367 can add the required code if they really need it.
4374 @node AMD29K-Dependent
4375 @chapter AMD 29K Dependent Features
4378 @node Machine Dependencies
4379 @chapter AMD 29K Dependent Features
4382 @cindex AMD 29K support
4385 * AMD29K Options:: Options
4386 * AMD29K Syntax:: Syntax
4387 * AMD29K Floating Point:: Floating Point
4388 * AMD29K Directives:: AMD 29K Machine Directives
4389 * AMD29K Opcodes:: Opcodes
4392 @node AMD29K Options
4394 @cindex AMD 29K options (none)
4395 @cindex options for AMD29K (none)
4396 @code{@value{AS}} has no additional command-line options for the AMD
4402 * AMD29K-Chars:: Special Characters
4403 * AMD29K-Regs:: Register Names
4407 @subsection Special Characters
4409 @cindex line comment character, AMD 29K
4410 @cindex AMD 29K line comment character
4411 @samp{;} is the line comment character.
4413 @cindex line separator, AMD 29K
4414 @cindex AMD 29K line separator
4415 @cindex statement separator, AMD 29K
4416 @cindex AMD 29K statement separator
4417 @samp{@@} can be used instead of a newline to separate statements.
4419 @cindex identifiers, AMD 29K
4420 @cindex AMD 29K identifiers
4421 The character @samp{?} is permitted in identifiers (but may not begin
4425 @subsection Register Names
4427 @cindex AMD 29K register names
4428 @cindex register names, AMD 29K
4429 General-purpose registers are represented by predefined symbols of the
4430 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
4431 (for local registers), where @var{nnn} represents a number between
4432 @code{0} and @code{127}, written with no leading zeros. The leading
4433 letters may be in either upper or lower case; for example, @samp{gr13}
4434 and @samp{LR7} are both valid register names.
4436 You may also refer to general-purpose registers by specifying the
4437 register number as the result of an expression (prefixed with @samp{%%}
4438 to flag the expression as a register number):
4443 ---where @var{expression} must be an absolute expression evaluating to a
4444 number between @code{0} and @code{255}. The range [0, 127] refers to
4445 global registers, and the range [128, 255] to local registers.
4447 @cindex special purpose registers, AMD 29K
4448 @cindex AMD 29K special purpose registers
4449 @cindex protected registers, AMD 29K
4450 @cindex AMD 29K protected registers
4451 In addition, @code{@value{AS}} understands the following protected
4452 special-purpose register names for the AMD 29K family:
4462 These unprotected special-purpose register names are also recognized:
4470 @node AMD29K Floating Point
4471 @section Floating Point
4473 @cindex floating point, AMD 29K (@sc{ieee})
4474 @cindex AMD 29K floating point (@sc{ieee})
4475 The AMD 29K family uses @sc{ieee} floating-point numbers.
4477 @node AMD29K Directives
4478 @section AMD 29K Machine Directives
4480 @cindex machine directives, AMD 29K
4481 @cindex AMD 29K machine directives
4483 @item .block @var{size} , @var{fill}
4484 @cindex @code{block} directive, AMD 29K
4485 This directive emits @var{size} bytes, each of value @var{fill}. Both
4486 @var{size} and @var{fill} are absolute expressions. If the comma
4487 and @var{fill} are omitted, @var{fill} is assumed to be zero.
4489 In other versions of the @sc{gnu} assembler, this directive is called
4495 @cindex @code{cputype} directive, AMD 29K
4496 This directive is ignored; it is accepted for compatibility with other
4500 @cindex @code{file} directive, AMD 29K
4501 This directive is ignored; it is accepted for compatibility with other
4505 @emph{Warning:} in other versions of the @sc{gnu} assembler, @code{.file} is
4506 used for the directive called @code{.app-file} in the AMD 29K support.
4510 @cindex @code{line} directive, AMD 29K
4511 This directive is ignored; it is accepted for compatibility with other
4515 @c since we're ignoring .lsym...
4516 @item .reg @var{symbol}, @var{expression}
4517 @cindex @code{reg} directive, AMD 29K
4518 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
4522 @cindex @code{sect} directive, AMD 29K
4523 This directive is ignored; it is accepted for compatibility with other
4526 @item .use @var{section name}
4527 @cindex @code{use} directive, AMD 29K
4528 Establishes the section and subsection for the following code;
4529 @var{section name} may be one of @code{.text}, @code{.data},
4530 @code{.data1}, or @code{.lit}. With one of the first three @var{section
4531 name} options, @samp{.use} is equivalent to the machine directive
4532 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
4536 @node AMD29K Opcodes
4539 @cindex AMD 29K opcodes
4540 @cindex opcodes for AMD 29K
4541 @code{@value{AS}} implements all the standard AMD 29K opcodes. No
4542 additional pseudo-instructions are needed on this family.
4544 For information on the 29K machine instruction set, see @cite{Am29000
4545 User's Manual}, Advanced Micro Devices, Inc.
4550 @node Machine Dependencies
4551 @chapter Machine Dependent Features
4553 The machine instruction sets are different on each Hitachi chip family,
4554 and there are also some syntax differences among the families. This
4555 chapter describes the specific @code{@value{AS}} features for each
4559 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
4560 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
4561 * SH-Dependent:: Hitachi SH Dependent Features
4571 @node H8/300-Dependent
4572 @chapter H8/300 Dependent Features
4574 @cindex H8/300 support
4576 * H8/300 Options:: Options
4577 * H8/300 Syntax:: Syntax
4578 * H8/300 Floating Point:: Floating Point
4579 * H8/300 Directives:: H8/300 Machine Directives
4580 * H8/300 Opcodes:: Opcodes
4583 @node H8/300 Options
4586 @cindex H8/300 options (none)
4587 @cindex options, H8/300 (none)
4588 @code{@value{AS}} has no additional command-line options for the Hitachi
4594 * H8/300-Chars:: Special Characters
4595 * H8/300-Regs:: Register Names
4596 * H8/300-Addressing:: Addressing Modes
4600 @subsection Special Characters
4602 @cindex line comment character, H8/300
4603 @cindex H8/300 line comment character
4604 @samp{;} is the line comment character.
4606 @cindex line separator, H8/300
4607 @cindex statement separator, H8/300
4608 @cindex H8/300 line separator
4609 @samp{$} can be used instead of a newline to separate statements.
4610 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4613 @subsection Register Names
4615 @cindex H8/300 registers
4616 @cindex register names, H8/300
4617 You can use predefined symbols of the form @samp{r@var{n}h} and
4618 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4619 general-purpose registers. @var{n} is a digit from @samp{0} to
4620 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4623 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4624 to the H8/300 registers as 16-bit registers (you must use this form for
4627 On the H8/300H, you can also use the eight predefined symbols
4628 @samp{er@var{n}} (@samp{er0} @dots{} @samp{er7}) to refer to the 32-bit
4629 general purpose registers.
4631 The two control registers are called @code{pc} (program counter; a
4632 16-bit register, except on the H8/300H where it is 24 bits) and
4633 @code{ccr} (condition code register; an 8-bit register). @code{r7} is
4634 used as the stack pointer, and can also be called @code{sp}.
4636 @node H8/300-Addressing
4637 @subsection Addressing Modes
4639 @cindex addressing modes, H8/300
4640 @cindex H8/300 addressing modes
4641 @value{AS} understands the following addressing modes for the H8/300:
4649 @item @@(@var{d}, r@var{n})
4650 @itemx @@(@var{d}:16, r@var{n})
4651 @itemx @@(@var{d}:24, r@var{n})
4652 Register indirect: 16-bit or 24-bit displacement @var{d} from register
4653 @var{n}. (24-bit displacements are only meaningful on the H8/300H.)
4656 Register indirect with post-increment
4659 Register indirect with pre-decrement
4661 @item @code{@@}@var{aa}
4662 @itemx @code{@@}@var{aa}:8
4663 @itemx @code{@@}@var{aa}:16
4664 @itemx @code{@@}@var{aa}:24
4665 Absolute address @code{aa}. (The address size @samp{:24} only makes
4666 sense on the H8/300H.)
4672 Immediate data @var{xx}. You may specify the @samp{:8}, @samp{:16}, or
4673 @samp{:32} for clarity, if you wish; but @code{@value{AS}} neither
4674 requires this nor uses it---the data size required is taken from
4677 @item @code{@@}@code{@@}@var{aa}
4678 @itemx @code{@@}@code{@@}@var{aa}:8
4679 Memory indirect. You may specify the @samp{:8} for clarity, if you
4680 wish; but @code{@value{AS}} neither requires this nor uses it.
4683 @node H8/300 Floating Point
4684 @section Floating Point
4686 @cindex floating point, H8/300 (@sc{ieee})
4687 @cindex H8/300 floating point (@sc{ieee})
4688 The H8/300 family has no hardware floating point, but the @code{.float}
4689 directive generates @sc{ieee} floating-point numbers for compatibility
4690 with other development tools.
4693 @node H8/300 Directives
4694 @section H8/300 Machine Directives
4696 @cindex H8/300 machine directives (none)
4697 @cindex machine directives, H8/300 (none)
4698 @cindex @code{word} directive, H8/300
4699 @cindex @code{int} directive, H8/300
4700 @code{@value{AS}} has only one machine-dependent directive for the
4704 @cindex H8/300H, assembling for
4706 Recognize and emit additional instructions for the H8/300H variant, and
4707 also make @code{.int} emit 32-bit numbers rather than the usual (16-bit)
4708 for the H8/300 family.
4711 On the H8/300 family (including the H8/300H) @samp{.word} directives
4712 generate 16-bit numbers.
4714 @node H8/300 Opcodes
4717 @cindex H8/300 opcode summary
4718 @cindex opcode summary, H8/300
4719 @cindex mnemonics, H8/300
4720 @cindex instruction summary, H8/300
4721 For detailed information on the H8/300 machine instruction set, see
4722 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025). For
4723 information specific to the H8/300H, see @cite{H8/300H Series
4724 Programming Manual} (Hitachi).
4726 @code{@value{AS}} implements all the standard H8/300 opcodes. No additional
4727 pseudo-instructions are needed on this family.
4730 @c this table, due to the multi-col faking and hardcoded order, looks silly
4731 @c except in smallbook. See comments below "@set SMALL" near top of this file.
4733 The following table summarizes the H8/300 opcodes, and their arguments.
4734 Entries marked @samp{*} are opcodes used only on the H8/300H.
4737 @c Using @group seems to use the normal baselineskip, not the smallexample
4738 @c baselineskip; looks approx doublespaced.
4740 Rs @r{source register}
4741 Rd @r{destination register}
4742 abs @r{absolute address}
4743 imm @r{immediate data}
4744 disp:N @r{N-bit displacement from a register}
4745 pcrel:N @r{N-bit displacement relative to program counter}
4747 add.b #imm,rd * andc #imm,ccr
4748 add.b rs,rd band #imm,rd
4749 add.w rs,rd band #imm,@@rd
4750 * add.w #imm,rd band #imm,@@abs:8
4751 * add.l rs,rd bra pcrel:8
4752 * add.l #imm,rd * bra pcrel:16
4753 adds #imm,rd bt pcrel:8
4754 addx #imm,rd * bt pcrel:16
4755 addx rs,rd brn pcrel:8
4756 and.b #imm,rd * brn pcrel:16
4757 and.b rs,rd bf pcrel:8
4758 * and.w rs,rd * bf pcrel:16
4759 * and.w #imm,rd bhi pcrel:8
4760 * and.l #imm,rd * bhi pcrel:16
4761 * and.l rs,rd bls pcrel:8
4763 * bls pcrel:16 bld #imm,rd
4764 bcc pcrel:8 bld #imm,@@rd
4765 * bcc pcrel:16 bld #imm,@@abs:8
4766 bhs pcrel:8 bnot #imm,rd
4767 * bhs pcrel:16 bnot #imm,@@rd
4768 bcs pcrel:8 bnot #imm,@@abs:8
4769 * bcs pcrel:16 bnot rs,rd
4770 blo pcrel:8 bnot rs,@@rd
4771 * blo pcrel:16 bnot rs,@@abs:8
4772 bne pcrel:8 bor #imm,rd
4773 * bne pcrel:16 bor #imm,@@rd
4774 beq pcrel:8 bor #imm,@@abs:8
4775 * beq pcrel:16 bset #imm,rd
4776 bvc pcrel:8 bset #imm,@@rd
4777 * bvc pcrel:16 bset #imm,@@abs:8
4778 bvs pcrel:8 bset rs,rd
4779 * bvs pcrel:16 bset rs,@@rd
4780 bpl pcrel:8 bset rs,@@abs:8
4781 * bpl pcrel:16 bsr pcrel:8
4782 bmi pcrel:8 bsr pcrel:16
4783 * bmi pcrel:16 bst #imm,rd
4784 bge pcrel:8 bst #imm,@@rd
4785 * bge pcrel:16 bst #imm,@@abs:8
4786 blt pcrel:8 btst #imm,rd
4787 * blt pcrel:16 btst #imm,@@rd
4788 bgt pcrel:8 btst #imm,@@abs:8
4789 * bgt pcrel:16 btst rs,rd
4790 ble pcrel:8 btst rs,@@rd
4791 * ble pcrel:16 btst rs,@@abs:8
4792 bclr #imm,rd bxor #imm,rd
4793 bclr #imm,@@rd bxor #imm,@@rd
4794 bclr #imm,@@abs:8 bxor #imm,@@abs:8
4795 bclr rs,rd cmp.b #imm,rd
4796 bclr rs,@@rd cmp.b rs,rd
4797 bclr rs,@@abs:8 cmp.w rs,rd
4798 biand #imm,rd cmp.w rs,rd
4799 biand #imm,@@rd * cmp.w #imm,rd
4800 biand #imm,@@abs:8 * cmp.l #imm,rd
4801 bild #imm,rd * cmp.l rs,rd
4802 bild #imm,@@rd daa rs
4803 bild #imm,@@abs:8 das rs
4804 bior #imm,rd dec.b rs
4805 bior #imm,@@rd * dec.w #imm,rd
4806 bior #imm,@@abs:8 * dec.l #imm,rd
4807 bist #imm,rd divxu.b rs,rd
4808 bist #imm,@@rd * divxu.w rs,rd
4809 bist #imm,@@abs:8 * divxs.b rs,rd
4810 bixor #imm,rd * divxs.w rs,rd
4811 bixor #imm,@@rd eepmov
4812 bixor #imm,@@abs:8 * eepmovw
4814 * exts.w rd mov.w rs,@@abs:16
4815 * exts.l rd * mov.l #imm,rd
4816 * extu.w rd * mov.l rs,rd
4817 * extu.l rd * mov.l @@rs,rd
4818 inc rs * mov.l @@(disp:16,rs),rd
4819 * inc.w #imm,rd * mov.l @@(disp:24,rs),rd
4820 * inc.l #imm,rd * mov.l @@rs+,rd
4821 jmp @@rs * mov.l @@abs:16,rd
4822 jmp abs * mov.l @@abs:24,rd
4823 jmp @@@@abs:8 * mov.l rs,@@rd
4824 jsr @@rs * mov.l rs,@@(disp:16,rd)
4825 jsr abs * mov.l rs,@@(disp:24,rd)
4826 jsr @@@@abs:8 * mov.l rs,@@-rd
4827 ldc #imm,ccr * mov.l rs,@@abs:16
4828 ldc rs,ccr * mov.l rs,@@abs:24
4829 * ldc @@abs:16,ccr movfpe @@abs:16,rd
4830 * ldc @@abs:24,ccr movtpe rs,@@abs:16
4831 * ldc @@(disp:16,rs),ccr mulxu.b rs,rd
4832 * ldc @@(disp:24,rs),ccr * mulxu.w rs,rd
4833 * ldc @@rs+,ccr * mulxs.b rs,rd
4834 * ldc @@rs,ccr * mulxs.w rs,rd
4835 * mov.b @@(disp:24,rs),rd neg.b rs
4836 * mov.b rs,@@(disp:24,rd) * neg.w rs
4837 mov.b @@abs:16,rd * neg.l rs
4839 mov.b @@abs:8,rd not.b rs
4840 mov.b rs,@@abs:8 * not.w rs
4841 mov.b rs,rd * not.l rs
4842 mov.b #imm,rd or.b #imm,rd
4843 mov.b @@rs,rd or.b rs,rd
4844 mov.b @@(disp:16,rs),rd * or.w #imm,rd
4845 mov.b @@rs+,rd * or.w rs,rd
4846 mov.b @@abs:8,rd * or.l #imm,rd
4847 mov.b rs,@@rd * or.l rs,rd
4848 mov.b rs,@@(disp:16,rd) orc #imm,ccr
4849 mov.b rs,@@-rd pop.w rs
4850 mov.b rs,@@abs:8 * pop.l rs
4851 mov.w rs,@@rd push.w rs
4852 * mov.w @@(disp:24,rs),rd * push.l rs
4853 * mov.w rs,@@(disp:24,rd) rotl.b rs
4854 * mov.w @@abs:24,rd * rotl.w rs
4855 * mov.w rs,@@abs:24 * rotl.l rs
4856 mov.w rs,rd rotr.b rs
4857 mov.w #imm,rd * rotr.w rs
4858 mov.w @@rs,rd * rotr.l rs
4859 mov.w @@(disp:16,rs),rd rotxl.b rs
4860 mov.w @@rs+,rd * rotxl.w rs
4861 mov.w @@abs:16,rd * rotxl.l rs
4862 mov.w rs,@@(disp:16,rd) rotxr.b rs
4863 mov.w rs,@@-rd * rotxr.w rs
4865 * rotxr.l rs * stc ccr,@@(disp:24,rd)
4867 rte * stc ccr,@@abs:16
4868 rts * stc ccr,@@abs:24
4869 shal.b rs sub.b rs,rd
4870 * shal.w rs sub.w rs,rd
4871 * shal.l rs * sub.w #imm,rd
4872 shar.b rs * sub.l rs,rd
4873 * shar.w rs * sub.l #imm,rd
4874 * shar.l rs subs #imm,rd
4875 shll.b rs subx #imm,rd
4876 * shll.w rs subx rs,rd
4877 * shll.l rs * trapa #imm
4878 shlr.b rs xor #imm,rd
4879 * shlr.w rs xor rs,rd
4880 * shlr.l rs * xor.w #imm,rd
4882 stc ccr,rd * xor.l #imm,rd
4883 * stc ccr,@@rs * xor.l rs,rd
4884 * stc ccr,@@(disp:16,rd) xorc #imm,ccr
4888 @cindex size suffixes, H8/300
4889 @cindex H8/300 size suffixes
4890 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4891 @code{sub}) are defined with variants using the suffixes @samp{.b},
4892 @samp{.w}, and @samp{.l} to specify the size of a memory operand.
4893 @code{@value{AS}} supports these suffixes, but does not require them;
4894 since one of the operands is always a register, @code{@value{AS}} can
4895 deduce the correct size.
4897 For example, since @code{r0} refers to a 16-bit register,
4900 @exdent is equivalent to
4904 If you use the size suffixes, @code{@value{AS}} issues a warning when
4905 the suffix and the register size do not match.
4910 @node H8/500-Dependent
4911 @chapter H8/500 Dependent Features
4913 @cindex H8/500 support
4915 * H8/500 Options:: Options
4916 * H8/500 Syntax:: Syntax
4917 * H8/500 Floating Point:: Floating Point
4918 * H8/500 Directives:: H8/500 Machine Directives
4919 * H8/500 Opcodes:: Opcodes
4922 @node H8/500 Options
4925 @cindex H8/500 options (none)
4926 @cindex options, H8/500 (none)
4927 @code{@value{AS}} has no additional command-line options for the Hitachi
4934 * H8/500-Chars:: Special Characters
4935 * H8/500-Regs:: Register Names
4936 * H8/500-Addressing:: Addressing Modes
4940 @subsection Special Characters
4942 @cindex line comment character, H8/500
4943 @cindex H8/500 line comment character
4944 @samp{!} is the line comment character.
4946 @cindex line separator, H8/500
4947 @cindex statement separator, H8/500
4948 @cindex H8/500 line separator
4949 @samp{;} can be used instead of a newline to separate statements.
4951 @cindex symbol names, @samp{$} in
4952 @cindex @code{$} in symbol names
4953 Since @samp{$} has no special meaning, you may use it in symbol names.
4956 @subsection Register Names
4958 @cindex H8/500 registers
4959 @cindex registers, H8/500
4960 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
4961 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, and @samp{r7} to refer to
4962 the H8/500 registers.
4964 The H8/500 also has these control registers:
4986 condition code register
4989 All registers are 16 bits long. To represent 32 bit numbers, use two
4990 adjacent registers; for distant memory addresses, use one of the segment
4991 pointers (@code{cp} for the program counter; @code{dp} for
4992 @code{r0}--@code{r3}; @code{ep} for @code{r4} and @code{r5}; and
4993 @code{tp} for @code{r6} and @code{r7}.
4995 @node H8/500-Addressing
4996 @subsection Addressing Modes
4998 @cindex addressing modes, H8/500
4999 @cindex H8/500 addressing modes
5000 @value{AS} understands the following addressing modes for the H8/500:
5008 @item @@(d:8, R@var{n})
5009 Register indirect with 8 bit signed displacement
5011 @item @@(d:16, R@var{n})
5012 Register indirect with 16 bit signed displacement
5015 Register indirect with pre-decrement
5018 Register indirect with post-increment
5021 8 bit absolute address
5024 16 bit absolute address
5033 @node H8/500 Floating Point
5034 @section Floating Point
5036 @cindex floating point, H8/500 (@sc{ieee})
5037 @cindex H8/500 floating point (@sc{ieee})
5038 The H8/500 family has no hardware floating point, but the @code{.float}
5039 directive generates @sc{ieee} floating-point numbers for compatibility
5040 with other development tools.
5042 @node H8/500 Directives
5043 @section H8/500 Machine Directives
5045 @cindex H8/500 machine directives (none)
5046 @cindex machine directives, H8/500 (none)
5047 @cindex @code{word} directive, H8/500
5048 @cindex @code{int} directive, H8/500
5049 @code{@value{AS}} has no machine-dependent directives for the H8/500.
5050 However, on this platform the @samp{.int} and @samp{.word} directives
5051 generate 16-bit numbers.
5053 @node H8/500 Opcodes
5056 @cindex H8/500 opcode summary
5057 @cindex opcode summary, H8/500
5058 @cindex mnemonics, H8/500
5059 @cindex instruction summary, H8/500
5060 For detailed information on the H8/500 machine instruction set, see
5061 @cite{H8/500 Series Programming Manual} (Hitachi M21T001).
5063 @code{@value{AS}} implements all the standard H8/500 opcodes. No additional
5064 pseudo-instructions are needed on this family.
5067 @c this table, due to the multi-col faking and hardcoded order, looks silly
5068 @c except in smallbook. See comments below "@set SMALL" near top of this file.
5070 The following table summarizes H8/500 opcodes and their operands:
5072 @c Use @group if it ever works, instead of @page
5076 abs8 @r{8-bit absolute address}
5077 abs16 @r{16-bit absolute address}
5078 abs24 @r{24-bit absolute address}
5079 crb @r{@code{ccr}, @code{br}, @code{ep}, @code{dp}, @code{tp}, @code{dp}}
5080 disp8 @r{8-bit displacement}
5081 ea @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
5082 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16},}
5083 @r{@code{#xx:8}, @code{#xx:16}}
5084 ea_mem @r{@code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
5085 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
5086 ea_noimm @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
5087 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
5089 imm4 @r{4-bit immediate data}
5090 imm8 @r{8-bit immediate data}
5091 imm16 @r{16-bit immediate data}
5092 pcrel8 @r{8-bit offset from program counter}
5093 pcrel16 @r{16-bit offset from program counter}
5094 qim @r{@code{-2}, @code{-1}, @code{1}, @code{2}}
5096 rs @r{a register distinct from rd}
5097 rlist @r{comma-separated list of registers in parentheses;}
5098 @r{register ranges @code{rd-rs} are allowed}
5099 sp @r{stack pointer (@code{r7})}
5100 sr @r{status register}
5101 sz @r{size; @samp{.b} or @samp{.w}. If omitted, default @samp{.w}}
5103 ldc[.b] ea,crb bcc[.w] pcrel16
5104 ldc[.w] ea,sr bcc[.b] pcrel8
5105 add[:q] sz qim,ea_noimm bhs[.w] pcrel16
5106 add[:g] sz ea,rd bhs[.b] pcrel8
5107 adds sz ea,rd bcs[.w] pcrel16
5108 addx sz ea,rd bcs[.b] pcrel8
5109 and sz ea,rd blo[.w] pcrel16
5110 andc[.b] imm8,crb blo[.b] pcrel8
5111 andc[.w] imm16,sr bne[.w] pcrel16
5113 bra[.w] pcrel16 beq[.w] pcrel16
5114 bra[.b] pcrel8 beq[.b] pcrel8
5115 bt[.w] pcrel16 bvc[.w] pcrel16
5116 bt[.b] pcrel8 bvc[.b] pcrel8
5117 brn[.w] pcrel16 bvs[.w] pcrel16
5118 brn[.b] pcrel8 bvs[.b] pcrel8
5119 bf[.w] pcrel16 bpl[.w] pcrel16
5120 bf[.b] pcrel8 bpl[.b] pcrel8
5121 bhi[.w] pcrel16 bmi[.w] pcrel16
5122 bhi[.b] pcrel8 bmi[.b] pcrel8
5123 bls[.w] pcrel16 bge[.w] pcrel16
5124 bls[.b] pcrel8 bge[.b] pcrel8
5126 blt[.w] pcrel16 mov[:g][.b] imm8,ea_mem
5127 blt[.b] pcrel8 mov[:g][.w] imm16,ea_mem
5128 bgt[.w] pcrel16 movfpe[.b] ea,rd
5129 bgt[.b] pcrel8 movtpe[.b] rs,ea_noimm
5130 ble[.w] pcrel16 mulxu sz ea,rd
5131 ble[.b] pcrel8 neg sz ea
5132 bclr sz imm4,ea_noimm nop
5133 bclr sz rs,ea_noimm not sz ea
5134 bnot sz imm4,ea_noimm or sz ea,rd
5135 bnot sz rs,ea_noimm orc[.b] imm8,crb
5136 bset sz imm4,ea_noimm orc[.w] imm16,sr
5137 bset sz rs,ea_noimm pjmp abs24
5138 bsr[.b] pcrel8 pjmp @@rd
5139 bsr[.w] pcrel16 pjsr abs24
5140 btst sz imm4,ea_noimm pjsr @@rd
5141 btst sz rs,ea_noimm prtd imm8
5142 clr sz ea prtd imm16
5143 cmp[:e][.b] imm8,rd prts
5144 cmp[:i][.w] imm16,rd rotl sz ea
5145 cmp[:g].b imm8,ea_noimm rotr sz ea
5146 cmp[:g][.w] imm16,ea_noimm rotxl sz ea
5147 Cmp[:g] sz ea,rd rotxr sz ea
5149 divxu sz ea,rd rtd imm16
5151 exts[.b] rd scb/f rs,pcrel8
5152 extu[.b] rd scb/ne rs,pcrel8
5153 jmp @@rd scb/eq rs,pcrel8
5154 jmp @@(imm8,rd) shal sz ea
5155 jmp @@(imm16,rd) shar sz ea
5156 jmp abs16 shll sz ea
5158 jsr @@(imm8,rd) sleep
5159 jsr @@(imm16,rd) stc[.b] crb,ea_noimm
5160 jsr abs16 stc[.w] sr,ea_noimm
5161 ldm @@sp+,(rlist) stm (rlist),@@-sp
5162 link fp,imm8 sub sz ea,rd
5163 link fp,imm16 subs sz ea,rd
5164 mov[:e][.b] imm8,rd subx sz ea,rd
5165 mov[:i][.w] imm16,rd swap[.b] rd
5166 mov[:l][.w] abs8,rd tas[.b] ea
5167 mov[:l].b abs8,rd trapa imm4
5168 mov[:s][.w] rs,abs8 trap/vs
5169 mov[:s].b rs,abs8 tst sz ea
5170 mov[:f][.w] @@(disp8,fp),rd unlk fp
5171 mov[:f][.w] rs,@@(disp8,fp) xch[.w] rs,rd
5172 mov[:f].b @@(disp8,fp),rd xor sz ea,rd
5173 mov[:f].b rs,@@(disp8,fp) xorc.b imm8,crb
5174 mov[:g] sz rs,ea_mem xorc.w imm16,sr
5182 @node HPPA-Dependent
5183 @chapter HPPA Dependent Features
5187 * HPPA Notes:: Notes
5188 * HPPA Options:: Options
5189 * HPPA Syntax:: Syntax
5190 * HPPA Floating Point:: Floating Point
5191 * HPPA Directives:: HPPA Machine Directives
5192 * HPPA Opcodes:: Opcodes
5197 As a back end for @sc{gnu} @sc{cc} @code{@value{AS}} has been throughly tested and should
5198 work extremely well. We have tested it only minimally on hand written assembly
5199 code and no one has tested it much on the assembly output from the HP
5202 The format of the debugging sections has changed since the original
5203 @code{@value{AS}} port (version 1.3X) was released; therefore,
5204 you must rebuild all HPPA objects and libraries with the new
5205 assembler so that you can debug the final executable.
5207 The HPPA @code{@value{AS}} port generates a small subset of the relocations
5208 available in the SOM and ELF object file formats. Additional relocation
5209 support will be added as it becomes necessary.
5213 @code{@value{AS}} has no machine-dependent command-line options for the HPPA.
5218 The assembler syntax closely follows the HPPA instruction set
5219 reference manual; assembler directives and general syntax closely follow the
5220 HPPA assembly language reference manual, with a few noteworthy differences.
5222 First, a colon may immediately follow a label definition. This is
5223 simply for compatibility with how most assembly language programmers
5226 Some obscure expression parsing problems may affect hand written code which
5227 uses the @code{spop} instructions, or code which makes significant
5228 use of the @code{!} line separator.
5230 @code{@value{AS}} is much less forgiving about missing arguments and other
5231 similar oversights than the HP assembler. @code{@value{AS}} notifies you
5232 of missing arguments as syntax errors; this is regarded as a feature, not a
5235 Finally, @code{@value{AS}} allows you to use an external symbol without
5236 explicitly importing the symbol. @emph{Warning:} in the future this will be
5237 an error for HPPA targets.
5239 Special characters for HPPA targets include:
5241 @samp{;} is the line comment character.
5243 @samp{!} can be used instead of a newline to separate statements.
5245 Since @samp{$} has no special meaning, you may use it in symbol names.
5247 @node HPPA Floating Point
5248 @section Floating Point
5249 @cindex floating point, HPPA (@sc{ieee})
5250 @cindex HPPA floating point (@sc{ieee})
5251 The HPPA family uses @sc{ieee} floating-point numbers.
5253 @node HPPA Directives
5254 @section HPPA Assembler Directives
5256 @code{@value{AS}} for the HPPA supports many additional directives for
5257 compatibility with the native assembler. This section describes them only
5258 briefly. For detailed information on HPPA-specific assembler directives, see
5259 @cite{HP9000 Series 800 Assembly Language Reference Manual} (HP 92432-90001).
5261 @cindex HPPA directives not supported
5262 @code{@value{AS}} does @emph{not} support the following assembler directives
5263 described in the HP manual:
5272 @cindex @code{.param} on HPPA
5273 Beyond those implemented for compatibility, @code{@value{AS}} supports one
5274 additional assembler directive for the HPPA: @code{.param}. It conveys
5275 register argument locations for static functions. Its syntax closely follows
5276 the @code{.export} directive.
5278 @cindex HPPA-only directives
5279 These are the additional directives in @code{@value{AS}} for the HPPA:
5282 @item .block @var{n}
5283 @itemx .blockz @var{n}
5284 Reserve @var{n} bytes of storage, and initialize them to zero.
5287 Mark the beginning of a procedure call. Only the special case with @emph{no
5288 arguments} is allowed.
5290 @item .callinfo [ @var{param}=@var{value}, @dots{} ] [ @var{flag}, @dots{} ]
5291 Specify a number of parameters and flags that define the environment for a
5294 @var{param} may be any of @samp{frame} (frame size), @samp{entry_gr} (end of
5295 general register range), @samp{entry_fr} (end of float register range),
5296 @samp{entry_sr} (end of space register range).
5298 The values for @var{flag} are @samp{calls} or @samp{caller} (proc has
5299 subroutines), @samp{no_calls} (proc does not call subroutines), @samp{save_rp}
5300 (preserve return pointer), @samp{save_sp} (proc preserves stack pointer),
5301 @samp{no_unwind} (do not unwind this proc), @samp{hpux_int} (proc is interrupt
5305 Assemble into the standard section called @samp{$TEXT$}, subsection
5309 @item .copyright "@var{string}"
5310 In the SOM object format, insert @var{string} into the object code, marked as a
5315 @item .copyright "@var{string}"
5316 In the ELF object format, insert @var{string} into the object code, marked as a
5321 Not yet supported; the assembler rejects programs containing this directive.
5324 Mark the beginning of a procedure.
5327 Mark the end of a procedure.
5329 @item .export @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5330 Make a procedure @var{name} available to callers. @var{typ}, if present, must
5331 be one of @samp{absolute}, @samp{code} (ELF only, not SOM), @samp{data},
5332 @samp{entry}, @samp{data}, @samp{entry}, @samp{millicode}, @samp{plabel},
5333 @samp{pri_prog}, or @samp{sec_prog}.
5335 @var{param}, if present, provides either relocation information for the
5336 procedure arguments and result, or a privilege level. @var{param} may be
5337 @samp{argw@var{n}} (where @var{n} ranges from @code{0} to @code{3}, and
5338 indicates one of four one-word arguments); @samp{rtnval} (the procedure's
5339 result); or @samp{priv_lev} (privilege level). For arguments or the result,
5340 @var{r} specifies how to relocate, and must be one of @samp{no} (not
5341 relocatable), @samp{gr} (argument is in general register), @samp{fr} (in
5342 floating point register), or @samp{fu} (upper half of float register).
5343 For @samp{priv_lev}, @var{r} is an integer.
5346 Define a two-byte integer constant @var{n}; synonym for the portable
5347 @code{@value{AS}} directive @code{.short}.
5349 @item .import @var{name} [ ,@var{typ} ]
5350 Converse of @code{.export}; make a procedure available to call. The arguments
5351 use the same conventions as the first two arguments for @code{.export}.
5353 @item .label @var{name}
5354 Define @var{name} as a label for the current assembly location.
5357 Not yet supported; the assembler rejects programs containing this directive.
5359 @item .origin @var{lc}
5360 Advance location counter to @var{lc}. Synonym for the @code{@value{as}}
5361 portable directive @code{.org}.
5363 @item .param @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5364 @c Not in HP manual; GNU HPPA extension
5365 Similar to @code{.export}, but used for static procedures.
5368 Use preceding the first statement of a procedure.
5371 Use following the last statement of a procedure.
5373 @item @var{label} .reg @var{expr}
5374 @c ?? Not in HP manual (Jan 1988 vn)
5375 Synonym for @code{.equ}; define @var{label} with the absolute expression
5376 @var{expr} as its value.
5378 @item .space @var{secname} [ ,@var{params} ]
5379 Switch to section @var{secname}, creating a new section by that name if
5380 necessary. You may only use @var{params} when creating a new section, not
5381 when switching to an existing one. @var{secname} may identify a section by
5382 number rather than by name.
5384 If specified, the list @var{params} declares attributes of the section,
5385 identified by keywords. The keywords recognized are @samp{spnum=@var{exp}}
5386 (identify this section by the number @var{exp}, an absolute expression),
5387 @samp{sort=@var{exp}} (order sections according to this sort key when linking;
5388 @var{exp} is an absolute expression), @samp{unloadable} (section contains no
5389 loadable data), @samp{notdefined} (this section defined elsewhere), and
5390 @samp{private} (data in this section not available to other programs).
5392 @item .spnum @var{secnam}
5393 @c ?? Not in HP manual (Jan 1988)
5394 Allocate four bytes of storage, and initialize them with the section number of
5395 the section named @var{secnam}. (You can define the section number with the
5396 HPPA @code{.space} directive.)
5398 @item .string "@var{str}"
5399 @cindex @code{string} directive on HPPA
5400 Copy the characters in the string @var{str} to the object file.
5401 @xref{Strings,,Strings}, for information on escape sequences you can use in
5402 @code{@value{AS}} strings.
5404 @emph{Warning!} The HPPA version of @code{.string} differs from the
5405 usual @code{@value{AS}} definition: it does @emph{not} write a zero byte
5406 after copying @var{str}.
5408 @item .stringz "@var{str}"
5409 Like @code{.string}, but appends a zero byte after copying @var{str} to object
5412 @item .subspa @var{name} [ ,@var{params} ]
5413 Similar to @code{.space}, but selects a subsection @var{name} within the
5414 current section. You may only specify @var{params} when you create a
5415 subsection (in the first instance of @code{.subspa} for this @var{name}).
5417 If specified, the list @var{params} declares attributes of the subsection,
5418 identified by keywords. The keywords recognized are @samp{quad=@var{expr}}
5419 (``quadrant'' for this subsection), @samp{align=@var{expr}} (alignment for
5420 beginning of this subsection; a power of two), @samp{access=@var{expr}} (value
5421 for ``access rights'' field), @samp{sort=@var{expr}} (sorting order for this
5422 subspace in link), @samp{code_only} (subsection contains only code),
5423 @samp{unloadable} (subsection cannot be loaded into memory), @samp{common}
5424 (subsection is common block), @samp{dup_comm} (initialized data may have
5425 duplicate names), or @samp{zero} (subsection is all zeros, do not write in
5428 @item .version "@var{str}"
5429 Write @var{str} as version identifier in object code.
5434 For detailed information on the HPPA machine instruction set, see
5435 @cite{PA-RISC Architecture and Instruction Set Reference Manual}
5442 @chapter Hitachi SH Dependent Features
5446 * SH Options:: Options
5447 * SH Syntax:: Syntax
5448 * SH Floating Point:: Floating Point
5449 * SH Directives:: SH Machine Directives
5450 * SH Opcodes:: Opcodes
5456 @cindex SH options (none)
5457 @cindex options, SH (none)
5458 @code{@value{AS}} has no additional command-line options for the Hitachi
5465 * SH-Chars:: Special Characters
5466 * SH-Regs:: Register Names
5467 * SH-Addressing:: Addressing Modes
5471 @subsection Special Characters
5473 @cindex line comment character, SH
5474 @cindex SH line comment character
5475 @samp{!} is the line comment character.
5477 @cindex line separator, SH
5478 @cindex statement separator, SH
5479 @cindex SH line separator
5480 You can use @samp{;} instead of a newline to separate statements.
5482 @cindex symbol names, @samp{$} in
5483 @cindex @code{$} in symbol names
5484 Since @samp{$} has no special meaning, you may use it in symbol names.
5487 @subsection Register Names
5489 @cindex SH registers
5490 @cindex registers, SH
5491 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
5492 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, @samp{r7}, @samp{r8},
5493 @samp{r9}, @samp{r10}, @samp{r11}, @samp{r12}, @samp{r13}, @samp{r14},
5494 and @samp{r15} to refer to the SH registers.
5496 The SH also has these control registers:
5500 procedure register (holds return address)
5507 high and low multiply accumulator registers
5513 global base register
5516 vector base register (for interrupt vectors)
5520 @subsection Addressing Modes
5522 @cindex addressing modes, SH
5523 @cindex SH addressing modes
5524 @code{@value{AS}} understands the following addressing modes for the SH.
5525 @code{R@var{n}} in the following refers to any of the numbered
5526 registers, but @emph{not} the control registers.
5536 Register indirect with pre-decrement
5539 Register indirect with post-increment
5541 @item @@(@var{disp}, R@var{n})
5542 Register indirect with displacement
5544 @item @@(R0, R@var{n})
5547 @item @@(@var{disp}, GBR)
5554 @itemx @@(@var{disp}, PC)
5555 PC relative address (for branch or for addressing memory). The
5556 @code{@value{AS}} implementation allows you to use the simpler form
5557 @var{addr} anywhere a PC relative address is called for; the alternate
5558 form is supported for compatibility with other assemblers.
5564 @node SH Floating Point
5565 @section Floating Point
5567 @cindex floating point, SH (@sc{ieee})
5568 @cindex SH floating point (@sc{ieee})
5569 The SH family has no hardware floating point, but the @code{.float}
5570 directive generates @sc{ieee} floating-point numbers for compatibility
5571 with other development tools.
5574 @section SH Machine Directives
5576 @cindex SH machine directives (none)
5577 @cindex machine directives, SH (none)
5578 @cindex @code{word} directive, SH
5579 @cindex @code{int} directive, SH
5580 @code{@value{AS}} has no machine-dependent directives for the SH.
5585 @cindex SH opcode summary
5586 @cindex opcode summary, SH
5587 @cindex mnemonics, SH
5588 @cindex instruction summary, SH
5589 For detailed information on the SH machine instruction set, see
5590 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
5592 @code{@value{AS}} implements all the standard SH opcodes. No additional
5593 pseudo-instructions are needed on this family. Note, however, that
5594 because @code{@value{AS}} supports a simpler form of PC-relative
5595 addressing, you may simply write (for example)
5602 where other assemblers might require an explicit displacement to
5603 @code{bar} from the program counter:
5606 mov.l @@(@var{disp}, PC)
5610 @c this table, due to the multi-col faking and hardcoded order, looks silly
5611 @c except in smallbook. See comments below "@set SMALL" near top of this file.
5613 Here is a summary of SH opcodes:
5618 Rn @r{a numbered register}
5619 Rm @r{another numbered register}
5620 #imm @r{immediate data}
5621 disp @r{displacement}
5622 disp8 @r{8-bit displacement}
5623 disp12 @r{12-bit displacement}
5625 add #imm,Rn lds.l @@Rn+,PR
5626 add Rm,Rn mac.w @@Rm+,@@Rn+
5627 addc Rm,Rn mov #imm,Rn
5628 addv Rm,Rn mov Rm,Rn
5629 and #imm,R0 mov.b Rm,@@(R0,Rn)
5630 and Rm,Rn mov.b Rm,@@-Rn
5631 and.b #imm,@@(R0,GBR) mov.b Rm,@@Rn
5632 bf disp8 mov.b @@(disp,Rm),R0
5633 bra disp12 mov.b @@(disp,GBR),R0
5634 bsr disp12 mov.b @@(R0,Rm),Rn
5635 bt disp8 mov.b @@Rm+,Rn
5636 clrmac mov.b @@Rm,Rn
5637 clrt mov.b R0,@@(disp,Rm)
5638 cmp/eq #imm,R0 mov.b R0,@@(disp,GBR)
5639 cmp/eq Rm,Rn mov.l Rm,@@(disp,Rn)
5640 cmp/ge Rm,Rn mov.l Rm,@@(R0,Rn)
5641 cmp/gt Rm,Rn mov.l Rm,@@-Rn
5642 cmp/hi Rm,Rn mov.l Rm,@@Rn
5643 cmp/hs Rm,Rn mov.l @@(disp,Rn),Rm
5644 cmp/pl Rn mov.l @@(disp,GBR),R0
5645 cmp/pz Rn mov.l @@(disp,PC),Rn
5646 cmp/str Rm,Rn mov.l @@(R0,Rm),Rn
5647 div0s Rm,Rn mov.l @@Rm+,Rn
5649 div1 Rm,Rn mov.l R0,@@(disp,GBR)
5650 exts.b Rm,Rn mov.w Rm,@@(R0,Rn)
5651 exts.w Rm,Rn mov.w Rm,@@-Rn
5652 extu.b Rm,Rn mov.w Rm,@@Rn
5653 extu.w Rm,Rn mov.w @@(disp,Rm),R0
5654 jmp @@Rn mov.w @@(disp,GBR),R0
5655 jsr @@Rn mov.w @@(disp,PC),Rn
5656 ldc Rn,GBR mov.w @@(R0,Rm),Rn
5657 ldc Rn,SR mov.w @@Rm+,Rn
5658 ldc Rn,VBR mov.w @@Rm,Rn
5659 ldc.l @@Rn+,GBR mov.w R0,@@(disp,Rm)
5660 ldc.l @@Rn+,SR mov.w R0,@@(disp,GBR)
5661 ldc.l @@Rn+,VBR mova @@(disp,PC),R0
5663 lds Rn,MACL muls Rm,Rn
5664 lds Rn,PR mulu Rm,Rn
5665 lds.l @@Rn+,MACH neg Rm,Rn
5666 lds.l @@Rn+,MACL negc Rm,Rn
5669 not Rm,Rn stc.l GBR,@@-Rn
5670 or #imm,R0 stc.l SR,@@-Rn
5671 or Rm,Rn stc.l VBR,@@-Rn
5672 or.b #imm,@@(R0,GBR) sts MACH,Rn
5673 rotcl Rn sts MACL,Rn
5675 rotl Rn sts.l MACH,@@-Rn
5676 rotr Rn sts.l MACL,@@-Rn
5681 shar Rn swap.b Rm,Rn
5682 shll Rn swap.w Rm,Rn
5683 shll16 Rn tas.b @@Rn
5685 shll8 Rn tst #imm,R0
5687 shlr16 Rn tst.b #imm,@@(R0,GBR)
5688 shlr2 Rn xor #imm,R0
5690 sleep xor.b #imm,@@(R0,GBR)
5691 stc GBR,Rn xtrct Rm,Rn
5706 @node i960-Dependent
5707 @chapter Intel 80960 Dependent Features
5710 @node Machine Dependencies
5711 @chapter Intel 80960 Dependent Features
5714 @cindex i960 support
5716 * Options-i960:: i960 Command-line Options
5717 * Floating Point-i960:: Floating Point
5718 * Directives-i960:: i960 Machine Directives
5719 * Opcodes for i960:: i960 Opcodes
5722 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
5723 @c long as they're not turned on for other machines than 960.
5727 @section i960 Command-line Options
5729 @cindex i960 options
5730 @cindex options, i960
5733 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
5734 @cindex i960 architecture options
5735 @cindex architecture options, i960
5736 @cindex @code{-A} options, i960
5737 Select the 80960 architecture. Instructions or features not supported
5738 by the selected architecture cause fatal errors.
5740 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
5741 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
5743 If you do not specify any of these options, @code{@value{AS}} generates code
5744 for any instruction or feature that is supported by @emph{some} version of the
5745 960 (even if this means mixing architectures!). In principle,
5746 @code{@value{AS}} attempts to deduce the minimal sufficient processor type if
5747 none is specified; depending on the object code format, the processor type may
5748 be recorded in the object file. If it is critical that the @code{@value{AS}}
5749 output match a specific architecture, specify that architecture explicitly.
5752 @cindex @code{-b} option, i960
5753 @cindex branch recording, i960
5754 @cindex i960 branch recording
5755 Add code to collect information about conditional branches taken, for
5756 later optimization using branch prediction bits. (The conditional branch
5757 instructions have branch prediction bits in the CA, CB, and CC
5758 architectures.) If @var{BR} represents a conditional branch instruction,
5759 the following represents the code generated by the assembler when
5760 @samp{-b} is specified:
5763 call @var{increment routine}
5764 .word 0 # pre-counter
5766 call @var{increment routine}
5767 .word 0 # post-counter
5770 The counter following a branch records the number of times that branch
5771 was @emph{not} taken; the differenc between the two counters is the
5772 number of times the branch @emph{was} taken.
5774 @cindex @code{gbr960}, i960 postprocessor
5775 @cindex branch statistics table, i960
5776 A table of every such @code{Label} is also generated, so that the
5777 external postprocessor @code{gbr960} (supplied by Intel) can locate all
5778 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
5779 this is a local symbol to permit collecting statistics for many separate
5780 object files. The table is word aligned, and begins with a two-word
5781 header. The first word, initialized to 0, is used in maintaining linked
5782 lists of branch tables. The second word is a count of the number of
5783 entries in the table, which follow immediately: each is a word, pointing
5784 to one of the labels illustrated above.
5788 @c END TEXI2ROFF-KILL
5790 +------------+------------+------------+ ... +------------+
5792 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
5794 +------------+------------+------------+ ... +------------+
5796 __BRANCH_TABLE__ layout
5803 \line{\leftskip=0pt\hskip\tableindent
5804 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
5805 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
5806 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
5808 @c END TEXI2ROFF-KILL
5810 The first word of the header is used to locate multiple branch tables,
5811 since each object file may contain one. Normally the links are
5812 maintained with a call to an initialization routine, placed at the
5813 beginning of each function in the file. The @sc{gnu} C compiler
5814 generates these calls automatically when you give it a @samp{-b} option.
5815 For further details, see the documentation of @samp{gbr960}.
5818 @cindex @code{-no-relax} option, i960
5819 Normally, Compare-and-Branch instructions with targets that require
5820 displacements greater than 13 bits (or that have external targets) are
5821 replaced with the corresponding compare (or @samp{chkbit}) and branch
5822 instructions. You can use the @samp{-no-relax} option to specify that
5823 @code{@value{AS}} should generate errors instead, if the target displacement
5824 is larger than 13 bits.
5826 This option does not affect the Compare-and-Jump instructions; the code
5827 emitted for them is @emph{always} adjusted when necessary (depending on
5828 displacement size), regardless of whether you use @samp{-no-relax}.
5831 @node Floating Point-i960
5832 @section Floating Point
5834 @cindex floating point, i960 (@sc{ieee})
5835 @cindex i960 floating point (@sc{ieee})
5836 @code{@value{AS}} generates @sc{ieee} floating-point numbers for the directives
5837 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
5839 @node Directives-i960
5840 @section i960 Machine Directives
5842 @cindex machine directives, i960
5843 @cindex i960 machine directives
5846 @cindex @code{bss} directive, i960
5847 @item .bss @var{symbol}, @var{length}, @var{align}
5848 Reserve @var{length} bytes in the bss section for a local @var{symbol},
5849 aligned to the power of two specified by @var{align}. @var{length} and
5850 @var{align} must be positive absolute expressions. This directive
5851 differs from @samp{.lcomm} only in that it permits you to specify
5852 an alignment. @xref{Lcomm,,@code{.lcomm}}.
5856 @item .extended @var{flonums}
5857 @cindex @code{extended} directive, i960
5858 @code{.extended} expects zero or more flonums, separated by commas; for
5859 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
5860 floating-point number.
5862 @item .leafproc @var{call-lab}, @var{bal-lab}
5863 @cindex @code{leafproc} directive, i960
5864 You can use the @samp{.leafproc} directive in conjunction with the
5865 optimized @code{callj} instruction to enable faster calls of leaf
5866 procedures. If a procedure is known to call no other procedures, you
5867 may define an entry point that skips procedure prolog code (and that does
5868 not depend on system-supplied saved context), and declare it as the
5869 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
5870 entry point that goes through the normal prolog, you can specify that
5871 entry point as @var{call-lab}.
5873 A @samp{.leafproc} declaration is meant for use in conjunction with the
5874 optimized call instruction @samp{callj}; the directive records the data
5875 needed later to choose between converting the @samp{callj} into a
5876 @code{bal} or a @code{call}.
5878 @var{call-lab} is optional; if only one argument is present, or if the
5879 two arguments are identical, the single argument is assumed to be the
5880 @code{bal} entry point.
5882 @item .sysproc @var{name}, @var{index}
5883 @cindex @code{sysproc} directive, i960
5884 The @samp{.sysproc} directive defines a name for a system procedure.
5885 After you define it using @samp{.sysproc}, you can use @var{name} to
5886 refer to the system procedure identified by @var{index} when calling
5887 procedures with the optimized call instruction @samp{callj}.
5889 Both arguments are required; @var{index} must be between 0 and 31
5893 @node Opcodes for i960
5894 @section i960 Opcodes
5896 @cindex opcodes, i960
5897 @cindex i960 opcodes
5898 All Intel 960 machine instructions are supported;
5899 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
5900 selecting the instruction subset for a particular 960
5901 architecture.@refill
5903 Some opcodes are processed beyond simply emitting a single corresponding
5904 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
5905 instructions with target displacements larger than 13 bits.
5908 * callj-i960:: @code{callj}
5909 * Compare-and-branch-i960:: Compare-and-Branch
5913 @subsection @code{callj}
5915 @cindex @code{callj}, i960 pseudo-opcode
5916 @cindex i960 @code{callj} pseudo-opcode
5917 You can write @code{callj} to have the assembler or the linker determine
5918 the most appropriate form of subroutine call: @samp{call},
5919 @samp{bal}, or @samp{calls}. If the assembly source contains
5920 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
5921 defining the operand---then @code{@value{AS}} translates the
5922 @code{callj}; if not, it simply emits the @code{callj}, leaving it
5923 for the linker to resolve.
5925 @node Compare-and-branch-i960
5926 @subsection Compare-and-Branch
5928 @cindex i960 compare/branch instructions
5929 @cindex compare/branch instructions, i960
5930 The 960 architectures provide combined Compare-and-Branch instructions
5931 that permit you to store the branch target in the lower 13 bits of the
5932 instruction word itself. However, if you specify a branch target far
5933 enough away that its address won't fit in 13 bits, the assembler can
5934 either issue an error, or convert your Compare-and-Branch instruction
5935 into separate instructions to do the compare and the branch.
5937 @cindex compare and jump expansions, i960
5938 @cindex i960 compare and jump expansions
5939 Whether @code{@value{AS}} gives an error or expands the instruction depends
5940 on two choices you can make: whether you use the @samp{-no-relax} option,
5941 and whether you use a ``Compare and Branch'' instruction or a ``Compare
5942 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
5943 expanded if necessary; the ``Branch'' instructions are expanded when
5944 necessary @emph{unless} you specify @code{-no-relax}---in which case
5945 @code{@value{AS}} gives an error instead.
5947 These are the Compare-and-Branch instructions, their ``Jump'' variants,
5948 and the instruction pairs they may expand into:
5952 @c END TEXI2ROFF-KILL
5955 Branch Jump Expanded to
5956 ------ ------ ------------
5959 cmpibe cmpije cmpi; be
5960 cmpibg cmpijg cmpi; bg
5961 cmpibge cmpijge cmpi; bge
5962 cmpibl cmpijl cmpi; bl
5963 cmpible cmpijle cmpi; ble
5964 cmpibno cmpijno cmpi; bno
5965 cmpibne cmpijne cmpi; bne
5966 cmpibo cmpijo cmpi; bo
5967 cmpobe cmpoje cmpo; be
5968 cmpobg cmpojg cmpo; bg
5969 cmpobge cmpojge cmpo; bge
5970 cmpobl cmpojl cmpo; bl
5971 cmpoble cmpojle cmpo; ble
5972 cmpobne cmpojne cmpo; bne
5978 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
5979 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
5980 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
5981 bbc& & chkbit; bno\cr
5982 bbs& & chkbit; bo\cr
5983 cmpibe& cmpije& cmpi; be\cr
5984 cmpibg& cmpijg& cmpi; bg\cr
5985 cmpibge& cmpijge& cmpi; bge\cr
5986 cmpibl& cmpijl& cmpi; bl\cr
5987 cmpible& cmpijle& cmpi; ble\cr
5988 cmpibno& cmpijno& cmpi; bno\cr
5989 cmpibne& cmpijne& cmpi; bne\cr
5990 cmpibo& cmpijo& cmpi; bo\cr
5991 cmpobe& cmpoje& cmpo; be\cr
5992 cmpobg& cmpojg& cmpo; bg\cr
5993 cmpobge& cmpojge& cmpo; bge\cr
5994 cmpobl& cmpojl& cmpo; bl\cr
5995 cmpoble& cmpojle& cmpo; ble\cr
5996 cmpobne& cmpojne& cmpo; bne\cr}
5998 @c END TEXI2ROFF-KILL
6004 @node M68K-Dependent
6005 @chapter M680x0 Dependent Features
6008 @node Machine Dependencies
6009 @chapter M680x0 Dependent Features
6012 @cindex M680x0 support
6014 * M68K-Opts:: M680x0 Options
6015 * M68K-Syntax:: Syntax
6016 * M68K-Moto-Syntax:: Motorola Syntax
6017 * M68K-Float:: Floating Point
6018 * M68K-Directives:: 680x0 Machine Directives
6019 * M68K-opcodes:: Opcodes
6023 @section M680x0 Options
6025 @cindex options, M680x0
6026 @cindex M680x0 options
6027 The Motorola 680x0 version of @code{@value{AS}} has two machine dependent options.
6028 One shortens undefined references from 32 to 16 bits, while the
6029 other is used to tell @code{@value{AS}} what kind of machine it is
6032 @cindex @code{-l} option, M680x0
6033 You can use the @samp{-l} option to shorten the size of references to undefined
6034 symbols. If you do not use the @samp{-l} option, references to undefined
6035 symbols are wide enough for a full @code{long} (32 bits). (Since
6036 @code{@value{AS}} cannot know where these symbols end up, @code{@value{AS}} can
6037 only allocate space for the linker to fill in later. Since @code{@value{AS}}
6038 does not know how far away these symbols are, it allocates as much space as it
6039 can.) If you use this option, the references are only one word wide (16 bits).
6040 This may be useful if you want the object file to be as small as possible, and
6041 you know that the relevant symbols are always less than 17 bits away.
6043 @cindex @code{-m68000} and related options
6044 @cindex architecture options, M680x0
6045 @cindex M680x0 architecture options
6046 The 680x0 version of @code{@value{AS}} is most frequently used to assemble
6047 programs for the Motorola MC68020 microprocessor. Occasionally it is
6048 used to assemble programs for the mostly similar, but slightly different
6049 MC68000 or MC68010 microprocessors. You can give @code{@value{AS}} the options
6050 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
6051 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
6058 This syntax for the Motorola 680x0 was developed at @sc{mit}.
6060 @cindex M680x0 syntax
6061 @cindex syntax, M680x0
6062 @cindex M680x0 size modifiers
6063 @cindex size modifiers, M680x0
6064 The 680x0 version of @code{@value{AS}} uses syntax compatible with the Sun
6065 assembler. Intervening periods are ignored; for example, @samp{movl} is
6066 equivalent to @samp{move.l}.
6069 If @code{@value{AS}} is compiled with SUN_ASM_SYNTAX defined, it
6070 also allows Sun-style local labels of the form @samp{1$} through
6074 In the following table @dfn{apc} stands for any of the address
6075 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
6076 Program Counter (@samp{pc}), or the zero-address relative to the
6077 program counter (@samp{zpc}).
6079 @cindex M680x0 addressing modes
6080 @cindex addressing modes, M680x0
6081 The following addressing modes are understood:
6084 @samp{#@var{digits}}
6087 @samp{%d0} through @samp{%d7}
6089 @item Address Register
6090 @samp{%a0} through @samp{%a7}@*
6091 @samp{%a7} is also known as @samp{%sp}, i.e. the Stack Pointer. @code{%a6}
6092 is also known as @samp{%fp}, the Frame Pointer.
6094 @item Address Register Indirect
6095 @samp{%a0@@} through @samp{%a7@@}
6097 @item Address Register Postincrement
6098 @samp{%a0@@+} through @samp{%a7@@+}
6100 @item Address Register Predecrement
6101 @samp{%a0@@-} through @samp{%a7@@-}
6103 @item Indirect Plus Offset
6104 @samp{%@var{apc}@@(@var{digits})}
6107 @samp{%@var{apc}@@(@var{digits},%@var{register}:@var{size}:@var{scale})}
6109 or @samp{%@var{apc}@@(%@var{register}:@var{size}:@var{scale})}
6112 @samp{%@var{apc}@@(@var{digits})@@(@var{digits},%@var{register}:@var{size}:@var{scale})}
6114 or @samp{%@var{apc}@@(@var{digits})@@(%@var{register}:@var{size}:@var{scale})}
6117 @samp{%@var{apc}@@(@var{digits},%@var{register}:@var{size}:@var{scale})@@(@var{digits})}
6119 or @samp{%@var{apc}@@(%@var{register}:@var{size}:@var{scale})@@(@var{digits})}
6121 @item Memory Indirect
6122 @samp{%@var{apc}@@(@var{digits})@@(@var{digits})}
6125 @samp{@var{symbol}}, or @samp{@var{digits}}
6127 @c pesch@cygnus.com: gnu, rich concur the following needs careful
6128 @c research before documenting.
6129 , or either of the above followed
6130 by @samp{:b}, @samp{:w}, or @samp{:l}.
6134 For some configurations, especially those where the compiler normally does not
6135 prepend an underscore to the names of user variables, the assembler requires a
6136 @samp{%} before any use of a register name. This is intended to let the
6137 assembler distinguish between C variables and registers named @samp{a0} through
6138 @samp{a7}, and so on. The @samp{%} is always accepted, but is not required for
6139 certain configurations, notably @samp{sun3}.
6141 @node M68K-Moto-Syntax
6142 @section Motorola Syntax
6144 @cindex Motorola syntax for the 680x0
6145 @cindex alternate syntax for the 680x0
6147 The standard Motorola syntax for this chip differs from the syntax already
6148 discussed (@pxref{M68K-Syntax,,Syntax}). @code{@value{AS}} can accept some
6149 forms of Motorola syntax for operands, even if @sc{mit} syntax is used for
6150 other operands in the same instruction. The two kinds of syntax are fully
6151 compatible; our support for Motorola syntax is simply incomplete at present.
6153 @cindex M680x0 syntax
6154 @cindex syntax, M680x0
6155 In particular, you may write or generate M68K assembler with the
6156 following conventions:
6158 (In the following table @dfn{%apc} stands for any of the address registers
6159 (@samp{%a0} through @samp{%a7}), nothing (@samp{}), the Program Counter
6160 (@samp{%pc}), or the zero-address relative to the program counter
6163 @cindex M680x0 addressing modes
6164 @cindex addressing modes, M680x0
6165 The following additional addressing modes are understood:
6167 @item Address Register Indirect
6168 @samp{%a0} through @samp{%a7}@*
6169 @samp{%a7} is also known as @samp{%sp}, i.e. the Stack Pointer. @code{%a6}
6170 is also known as @samp{%fp}, the Frame Pointer.
6172 @item Address Register Postincrement
6173 @samp{(%a0)+} through @samp{(%a7)+}
6175 @item Address Register Predecrement
6176 @samp{-(%a0)} through @samp{-(%a7)}
6178 @item Indirect Plus Offset
6179 @samp{@var{digits}(%@var{apc})}
6182 @samp{@var{digits}(%@var{apc},(%@var{register}.@var{size}*@var{scale}))}@*
6183 or @samp{(%@var{apc},%@var{register}.@var{size}*@var{scale})}@*
6184 In either case, @var{size} and @var{scale} are optional
6185 (@var{scale} defaults to @samp{1}, @var{size} defaults to @samp{l}).
6186 @var{scale} can be @samp{1}, @samp{2}, @samp{4}, or @samp{8}.
6187 @var{size} can be @samp{w} or @samp{l}. @var{scale} is only supported
6188 on the 68020 and greater.
6191 Other, more complex addressing modes permitted in Motorola syntax are not
6195 @section Floating Point
6197 @cindex floating point, M680x0
6198 @cindex M680x0 floating point
6199 @c FIXME is this "not too well tested" crud STILL true?
6200 The floating point code is not too well tested, and may have
6203 Packed decimal (P) format floating literals are not supported.
6204 Feel free to add the code!
6206 The floating point formats generated by directives are these.
6210 @cindex @code{float} directive, M680x0
6211 @code{Single} precision floating point constants.
6214 @cindex @code{double} directive, M680x0
6215 @code{Double} precision floating point constants.
6218 There is no directive to produce regions of memory holding
6219 extended precision numbers, however they can be used as
6220 immediate operands to floating-point instructions. Adding a
6221 directive to create extended precision numbers would not be
6222 hard, but it has not yet seemed necessary.
6224 @node M68K-Directives
6225 @section 680x0 Machine Directives
6227 @cindex M680x0 directives
6228 @cindex directives, M680x0
6229 In order to be compatible with the Sun assembler the 680x0 assembler
6230 understands the following directives.
6234 @cindex @code{data1} directive, M680x0
6235 This directive is identical to a @code{.data 1} directive.
6238 @cindex @code{data2} directive, M680x0
6239 This directive is identical to a @code{.data 2} directive.
6242 @cindex @code{even} directive, M680x0
6243 This directive is identical to a @code{.align 1} directive.
6244 @c Is this true? does it work???
6247 @cindex @code{skip} directive, M680x0
6248 This directive is identical to a @code{.space} directive.
6255 @cindex M680x0 opcodes
6256 @cindex opcodes, M680x0
6257 @cindex instruction set, M680x0
6258 @c pesch@cygnus.com: I don't see any point in the following
6259 @c paragraph. Bugs are bugs; how does saying this
6262 Danger: Several bugs have been found in the opcode table (and
6263 fixed). More bugs may exist. Be careful when using obscure
6268 * M68K-Branch:: Branch Improvement
6269 * M68K-Chars:: Special Characters
6273 @subsection Branch Improvement
6275 @cindex pseudo-opcodes, M680x0
6276 @cindex M680x0 pseudo-opcodes
6277 @cindex branch improvement, M680x0
6278 @cindex M680x0 branch improvement
6279 Certain pseudo opcodes are permitted for branch instructions.
6280 They expand to the shortest branch instruction that reach the
6281 target. Generally these mnemonics are made by substituting @samp{j} for
6282 @samp{b} at the start of a Motorola mnemonic.
6284 The following table summarizes the pseudo-operations. A @code{*} flags
6285 cases that are more fully described after the table:
6289 +-------------------------------------------------
6291 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
6292 +-------------------------------------------------
6293 jbsr |bsrs bsr bsrl jsr jsr
6294 jra |bras bra bral jmp jmp
6295 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
6296 * dbXX |dbXX dbXX dbXX; bra; jmpl
6297 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
6300 NX: negative of condition XX
6303 @center @code{*}---see full description below
6308 These are the simplest jump pseudo-operations; they always map to one
6309 particular machine instruction, depending on the displacement to the
6313 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
6314 where @var{XX} is a conditional branch or condition-code test. The full
6315 list of pseudo-ops in this family is:
6317 jhi jls jcc jcs jne jeq jvc
6318 jvs jpl jmi jge jlt jgt jle
6321 For the cases of non-PC relative displacements and long displacements on
6322 the 68000 or 68010, @code{@value{AS}} issues a longer code fragment in terms of
6323 @var{NX}, the opposite condition to @var{XX}. For example, for the
6324 non-PC relative case:
6336 The full family of pseudo-operations covered here is
6338 dbhi dbls dbcc dbcs dbne dbeq dbvc
6339 dbvs dbpl dbmi dbge dblt dbgt dble
6343 Other than for word and byte displacements, when the source reads
6344 @samp{db@var{XX} foo}, @code{@value{AS}} emits
6353 This family includes
6355 fjne fjeq fjge fjlt fjgt fjle fjf
6356 fjt fjgl fjgle fjnge fjngl fjngle fjngt
6357 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
6358 fjor fjseq fjsf fjsne fjst fjueq fjuge
6359 fjugt fjule fjult fjun
6362 For branch targets that are not PC relative, @code{@value{AS}} emits
6368 when it encounters @samp{fj@var{XX} foo}.
6373 @subsection Special Characters
6375 @cindex special characters, M680x0
6376 @cindex M680x0 immediate character
6377 @cindex immediate character, M680x0
6378 @cindex M680x0 line comment character
6379 @cindex line comment character, M680x0
6380 @cindex comments, M680x0
6381 The immediate character is @samp{#} for Sun compatibility. The
6382 line-comment character is @samp{|}. If a @samp{#} appears at the
6383 beginning of a line, it is treated as a comment unless it looks like
6384 @samp{# line file}, in which case it is treated normally.
6388 @c FIXME! Stop ignoring when filled in.
6393 The 32x32 version of @code{@value{AS}} accepts a @samp{-m32032} option to
6394 specify thiat it is compiling for a 32032 processor, or a
6395 @samp{-m32532} to specify that it is compiling for a 32532 option.
6396 The default (if neither is specified) is chosen when the assembler
6400 I don't know anything about the 32x32 syntax assembled by
6401 @code{@value{AS}}. Someone who undersands the processor (I've never seen
6402 one) and the possible syntaxes should write this section.
6404 @section Floating Point
6405 The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{AS}}
6406 only creates single or double precision values. I don't know if the
6407 32x32 understands extended precision numbers.
6409 @section 32x32 Machine Directives
6410 The 32x32 has no machine dependent directives.
6416 @node Sparc-Dependent
6417 @chapter SPARC Dependent Features
6420 @node Machine Dependencies
6421 @chapter SPARC Dependent Features
6424 @cindex SPARC support
6426 * Sparc-Opts:: Options
6427 * Sparc-Float:: Floating Point
6428 * Sparc-Directives:: Sparc Machine Directives
6434 @cindex options for SPARC
6435 @cindex SPARC options
6436 @cindex architectures, SPARC
6437 @cindex SPARC architectures
6438 The SPARC chip family includes several successive levels (or other
6439 variants) of chip, using the same core instruction set, but including
6440 a few additional instructions at each level.
6442 By default, @code{@value{AS}} assumes the core instruction set (SPARC
6443 v6), but ``bumps'' the architecture level as needed: it switches to
6444 successively higher architectures as it encounters instructions that
6445 only exist in the higher levels.
6448 @item -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite
6454 Use one of the @samp{-A} options to select one of the SPARC
6455 architectures explicitly. If you select an architecture explicitly,
6456 @code{@value{AS}} reports a fatal error if it encounters an instruction
6457 or feature requiring a higher level.
6460 Permit the assembler to ``bump'' the architecture level as required, but
6461 warn whenever it is necessary to switch to another level.
6465 @c FIXME: (sparc) Fill in "syntax" section!
6466 @c subsection syntax
6467 I don't know anything about Sparc syntax. Someone who does
6468 will have to write this section.
6472 @section Floating Point
6474 @cindex floating point, SPARC (@sc{ieee})
6475 @cindex SPARC floating point (@sc{ieee})
6476 The Sparc uses @sc{ieee} floating-point numbers.
6478 @node Sparc-Directives
6479 @section Sparc Machine Directives
6481 @cindex SPARC machine directives
6482 @cindex machine directives, SPARC
6483 The Sparc version of @code{@value{AS}} supports the following additional
6488 @cindex @code{align} directive, SPARC
6489 This must be followed by the desired alignment in bytes.
6492 @cindex @code{common} directive, SPARC
6493 This must be followed by a symbol name, a positive number, and
6494 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
6495 syntax is different.
6498 @cindex @code{half} directive, SPARC
6499 This is functionally identical to @code{.short}.
6502 @cindex @code{proc} directive, SPARC
6503 This directive is ignored. Any text following it on the same
6504 line is also ignored.
6507 @cindex @code{reserve} directive, SPARC
6508 This must be followed by a symbol name, a positive number, and
6509 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
6510 syntax is different.
6513 @cindex @code{seg} directive, SPARC
6514 This must be followed by @code{"text"}, @code{"data"}, or
6515 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
6519 @cindex @code{skip} directive, SPARC
6520 This is functionally identical to the @code{.space} directive.
6523 @cindex @code{word} directive, SPARC
6524 On the Sparc, the @code{.word} directive produces 32 bit values,
6525 instead of the 16 bit values it produces on many other machines.
6528 @cindex @code{xword} directive, SPARC
6529 On the Sparc V9 processor, the @code{.xword} directive produces
6537 @node i386-Dependent
6538 @chapter 80386 Dependent Features
6541 @node Machine Dependencies
6542 @chapter 80386 Dependent Features
6545 @cindex i386 support
6546 @cindex i80306 support
6548 * i386-Options:: Options
6549 * i386-Syntax:: AT&T Syntax versus Intel Syntax
6550 * i386-Opcodes:: Opcode Naming
6551 * i386-Regs:: Register Naming
6552 * i386-prefixes:: Opcode Prefixes
6553 * i386-Memory:: Memory References
6554 * i386-jumps:: Handling of Jump Instructions
6555 * i386-Float:: Floating Point
6556 * i386-16bit:: Writing 16-bit Code
6557 * i386-Notes:: Notes
6563 @cindex options for i386 (none)
6564 @cindex i386 options (none)
6565 The 80386 has no machine dependent options.
6568 @section AT&T Syntax versus Intel Syntax
6570 @cindex i386 syntax compatibility
6571 @cindex syntax compatibility, i386
6572 In order to maintain compatibility with the output of @code{@value{GCC}},
6573 @code{@value{AS}} supports AT&T System V/386 assembler syntax. This is quite
6574 different from Intel syntax. We mention these differences because
6575 almost all 80386 documents used only Intel syntax. Notable differences
6576 between the two syntaxes are:
6580 @cindex immediate operands, i386
6581 @cindex i386 immediate operands
6582 @cindex register operands, i386
6583 @cindex i386 register operands
6584 @cindex jump/call operands, i386
6585 @cindex i386 jump/call operands
6586 @cindex operand delimiters, i386
6587 AT&T immediate operands are preceded by @samp{$}; Intel immediate
6588 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
6589 AT&T register operands are preceded by @samp{%}; Intel register operands
6590 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
6591 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
6594 @cindex i386 source, destination operands
6595 @cindex source, destination operands; i386
6596 AT&T and Intel syntax use the opposite order for source and destination
6597 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
6598 @samp{source, dest} convention is maintained for compatibility with
6599 previous Unix assemblers.
6602 @cindex opcode suffixes, i386
6603 @cindex sizes operands, i386
6604 @cindex i386 size suffixes
6605 In AT&T syntax the size of memory operands is determined from the last
6606 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
6607 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
6608 memory references. Intel syntax accomplishes this by prefixes memory
6609 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
6610 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
6611 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
6614 @cindex return instructions, i386
6615 @cindex i386 jump, call, return
6616 Immediate form long jumps and calls are
6617 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
6619 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
6621 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
6622 @samp{ret far @var{stack-adjust}}.
6625 @cindex sections, i386
6626 @cindex i386 sections
6627 The AT&T assembler does not provide support for multiple section
6628 programs. Unix style systems expect all programs to be single sections.
6632 @section Opcode Naming
6634 @cindex i386 opcode naming
6635 @cindex opcode naming, i386
6636 Opcode names are suffixed with one character modifiers which specify the
6637 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
6638 byte, word, and long operands. If no suffix is specified by an
6639 instruction and it contains no memory operands then @code{@value{AS}} tries to
6640 fill in the missing suffix based on the destination register operand
6641 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
6642 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
6643 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
6644 assembler which assumes that a missing opcode suffix implies long
6645 operand size. (This incompatibility does not affect compiler output
6646 since compilers always explicitly specify the opcode suffix.)
6648 Almost all opcodes have the same names in AT&T and Intel format. There
6649 are a few exceptions. The sign extend and zero extend instructions need
6650 two sizes to specify them. They need a size to sign/zero extend
6651 @emph{from} and a size to zero extend @emph{to}. This is accomplished
6652 by using two opcode suffixes in AT&T syntax. Base names for sign extend
6653 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
6654 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
6655 suffixes are tacked on to this base name, the @emph{from} suffix before
6656 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
6657 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
6658 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
6659 and @samp{wl} (from word to long).
6661 @cindex conversion instructions, i386
6662 @cindex i386 conversion instructions
6663 The Intel-syntax conversion instructions
6667 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
6670 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
6673 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
6676 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
6680 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
6681 AT&T naming. @code{@value{AS}} accepts either naming for these instructions.
6683 @cindex jump instructions, i386
6684 @cindex call instructions, i386
6685 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
6686 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
6690 @section Register Naming
6692 @cindex i386 registers
6693 @cindex registers, i386
6694 Register operands are always prefixes with @samp{%}. The 80386 registers
6699 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
6700 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
6701 frame pointer), and @samp{%esp} (the stack pointer).
6704 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
6705 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
6708 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
6709 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
6710 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
6711 @samp{%cx}, and @samp{%dx})
6714 the 6 section registers @samp{%cs} (code section), @samp{%ds}
6715 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
6719 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
6723 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
6724 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
6727 the 2 test registers @samp{%tr6} and @samp{%tr7}.
6730 the 8 floating point register stack @samp{%st} or equivalently
6731 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
6732 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
6736 @section Opcode Prefixes
6738 @cindex i386 opcode prefixes
6739 @cindex opcode prefixes, i386
6740 @cindex prefixes, i386
6741 Opcode prefixes are used to modify the following opcode. They are used
6742 to repeat string instructions, to provide section overrides, to perform
6743 bus lock operations, and to give operand and address size (16-bit
6744 operands are specified in an instruction by prefixing what would
6745 normally be 32-bit operands with a ``operand size'' opcode prefix).
6746 Opcode prefixes are usually given as single-line instructions with no
6747 operands, and must directly precede the instruction they act upon. For
6748 example, the @samp{scas} (scan string) instruction is repeated with:
6754 Here is a list of opcode prefixes:
6758 @cindex section override prefixes, i386
6759 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
6760 @samp{fs}, @samp{gs}. These are automatically added by specifying
6761 using the @var{section}:@var{memory-operand} form for memory references.
6764 @cindex size prefixes, i386
6765 Operand/Address size prefixes @samp{data16} and @samp{addr16}
6766 change 32-bit operands/addresses into 16-bit operands/addresses. Note
6767 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
6768 are not supported (yet).
6771 @cindex bus lock prefixes, i386
6772 @cindex inhibiting interrupts, i386
6773 The bus lock prefix @samp{lock} inhibits interrupts during
6774 execution of the instruction it precedes. (This is only valid with
6775 certain instructions; see a 80386 manual for details).
6778 @cindex coprocessor wait, i386
6779 The wait for coprocessor prefix @samp{wait} waits for the
6780 coprocessor to complete the current instruction. This should never be
6781 needed for the 80386/80387 combination.
6784 @cindex repeat prefixes, i386
6785 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
6786 to string instructions to make them repeat @samp{%ecx} times.
6790 @section Memory References
6792 @cindex i386 memory references
6793 @cindex memory references, i386
6794 An Intel syntax indirect memory reference of the form
6797 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
6801 is translated into the AT&T syntax
6804 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
6808 where @var{base} and @var{index} are the optional 32-bit base and
6809 index registers, @var{disp} is the optional displacement, and
6810 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
6811 to calculate the address of the operand. If no @var{scale} is
6812 specified, @var{scale} is taken to be 1. @var{section} specifies the
6813 optional section register for the memory operand, and may override the
6814 default section register (see a 80386 manual for section register
6815 defaults). Note that section overrides in AT&T syntax @emph{must} have
6816 be preceded by a @samp{%}. If you specify a section override which
6817 coincides with the default section register, @code{@value{AS}} does @emph{not}
6818 output any section register override prefixes to assemble the given
6819 instruction. Thus, section overrides can be specified to emphasize which
6820 section register is used for a given memory operand.
6822 Here are some examples of Intel and AT&T style memory references:
6825 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
6826 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
6827 missing, and the default section is used (@samp{%ss} for addressing with
6828 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
6830 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
6831 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
6832 @samp{foo}. All other fields are missing. The section register here
6833 defaults to @samp{%ds}.
6835 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
6836 This uses the value pointed to by @samp{foo} as a memory operand.
6837 Note that @var{base} and @var{index} are both missing, but there is only
6838 @emph{one} @samp{,}. This is a syntactic exception.
6840 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
6841 This selects the contents of the variable @samp{foo} with section
6842 register @var{section} being @samp{%gs}.
6845 Absolute (as opposed to PC relative) call and jump operands must be
6846 prefixed with @samp{*}. If no @samp{*} is specified, @code{@value{AS}}
6847 always chooses PC relative addressing for jump/call labels.
6849 Any instruction that has a memory operand @emph{must} specify its size (byte,
6850 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
6854 @section Handling of Jump Instructions
6856 @cindex jump optimization, i386
6857 @cindex i386 jump optimization
6858 Jump instructions are always optimized to use the smallest possible
6859 displacements. This is accomplished by using byte (8-bit) displacement
6860 jumps whenever the target is sufficiently close. If a byte displacement
6861 is insufficient a long (32-bit) displacement is used. We do not support
6862 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
6863 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
6864 @samp{%eip} to 16 bits after the word displacement is added.
6866 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
6867 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in byte
6868 displacements, so that if you use these instructions (@code{@value{GCC}} does
6869 not use them) you may get an error message (and incorrect code). The AT&T
6870 80386 assembler tries to get around this problem by expanding @samp{jcxz foo}
6881 @section Floating Point
6883 @cindex i386 floating point
6884 @cindex floating point, i386
6885 All 80387 floating point types except packed BCD are supported.
6886 (BCD support may be added without much difficulty). These data
6887 types are 16-, 32-, and 64- bit integers, and single (32-bit),
6888 double (64-bit), and extended (80-bit) precision floating point.
6889 Each supported type has an opcode suffix and a constructor
6890 associated with it. Opcode suffixes specify operand's data
6891 types. Constructors build these data types into memory.
6895 @cindex @code{float} directive, i386
6896 @cindex @code{single} directive, i386
6897 @cindex @code{double} directive, i386
6898 @cindex @code{tfloat} directive, i386
6899 Floating point constructors are @samp{.float} or @samp{.single},
6900 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
6901 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
6902 @samp{t} stands for temporary real, and that the 80387 only supports
6903 this format via the @samp{fldt} (load temporary real to stack top) and
6904 @samp{fstpt} (store temporary real and pop stack) instructions.
6907 @cindex @code{word} directive, i386
6908 @cindex @code{long} directive, i386
6909 @cindex @code{int} directive, i386
6910 @cindex @code{quad} directive, i386
6911 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
6912 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
6913 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
6914 (quad). As with the temporary real format the 64-bit @samp{q} format is
6915 only present in the @samp{fildq} (load quad integer to stack top) and
6916 @samp{fistpq} (store quad integer and pop stack) instructions.
6919 Register to register operations do not require opcode suffixes,
6920 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
6922 @cindex i386 @code{fwait} instruction
6923 @cindex @code{fwait instruction}, i386
6924 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
6925 instructions are almost never needed (this is not the case for the
6926 80286/80287 and 8086/8087 combinations). Therefore, @code{@value{AS}} suppresses
6927 the @samp{fwait} instruction whenever it is implicitly selected by one
6928 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
6929 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
6930 instructions are made equivalent to @samp{f@dots{}} instructions. If
6931 @samp{fwait} is desired it must be explicitly coded.
6934 @section Writing 16-bit Code
6936 @cindex i386 16-bit code
6937 @cindex 16-bit code, i386
6938 @cindex real-mode code, i386
6939 @cindex @code{code16} directive, i386
6940 @cindex @code{code32} directive, i386
6941 While GAS normally writes only ``pure'' 32-bit i386 code, it has limited
6942 support for writing code to run in real mode or in 16-bit protected mode
6943 code segments. To do this, insert a @samp{.code16} directive before the
6944 assembly language instructions to be run in 16-bit mode. You can switch
6945 GAS back to writing normal 32-bit code with the @samp{.code32} directive.
6947 GAS understands exactly the same assembly language syntax in 16-bit mode as
6948 in 32-bit mode. The function of any given instruction is exactly the same
6949 regardless of mode, as long as the resulting object code is executed in the
6950 mode for which GAS wrote it. So, for example, the @samp{ret} mnemonic
6951 produces a 32-bit return instruction regardless of whether it is to be run
6952 in 16-bit or 32-bit mode. (If GAS is in 16-bit mode, it will add an
6953 operand size prefix to the instruction to force it to be a 32-bit return.)
6955 This means, for one thing, that you can use GNU CC to write code to be run
6956 in real mode or 16-bit protected mode. Just insert the statement
6957 @samp{asm(".code16");} at the beginning of your C source file, and while
6958 GNU CC will still be generating 32-bit code, GAS will automatically add all
6959 the necessary size prefixes to make that code run in 16-bit mode. Of
6960 course, since GNU CC only writes small-model code (it doesn't know how to
6961 attach segment selectors to pointers like native x86 compilers do), any
6962 16-bit code you write with GNU CC will essentially be limited to a 64K
6963 address space. Also, there will be a code size and performance penalty
6964 due to all the extra address and operand size prefixes GAS has to add to
6967 Note that placing GAS in 16-bit mode does not mean that the resulting
6968 code will necessarily run on a 16-bit pre-80386 processor. To write code
6969 that runs on such a processor, you would have to refrain from using
6970 @emph{any} 32-bit constructs which require GAS to output address or
6971 operand size prefixes. At the moment this would be rather difficult,
6972 because GAS currently supports @emph{only} 32-bit addressing modes: when
6973 writing 16-bit code, it @emph{always} outputs address size prefixes for any
6974 instruction that uses a non-register addressing mode. So you can write
6975 code that runs on 16-bit processors, but only if that code never references
6981 @cindex i386 @code{mul}, @code{imul} instructions
6982 @cindex @code{mul} instruction, i386
6983 @cindex @code{imul} instruction, i386
6984 There is some trickery concerning the @samp{mul} and @samp{imul}
6985 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
6986 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
6987 for @samp{imul}) can be output only in the one operand form. Thus,
6988 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
6989 the expanding multiply would clobber the @samp{%edx} register, and this
6990 would confuse @code{@value{GCC}} output. Use @samp{imul %ebx} to get the
6991 64-bit product in @samp{%edx:%eax}.
6993 We have added a two operand form of @samp{imul} when the first operand
6994 is an immediate mode expression and the second operand is a register.
6995 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
6996 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
7003 @node Z8000-Dependent
7004 @chapter Z8000 Dependent Features
7007 @node Machine Dependencies
7008 @chapter Z8000 Dependent Features
7011 @cindex Z8000 support
7012 The Z8000 @value{AS} supports both members of the Z8000 family: the
7013 unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with
7016 When the assembler is in unsegmented mode (specified with the
7017 @code{unsegm} directive), an address takes up one word (16 bit)
7018 sized register. When the assembler is in segmented mode (specified with
7019 the @code{segm} directive), a 24-bit address takes up a long (32 bit)
7020 register. @xref{Z8000 Directives,,Assembler Directives for the Z8000},
7021 for a list of other Z8000 specific assembler directives.
7024 * Z8000 Options:: No special command-line options for Z8000
7025 * Z8000 Syntax:: Assembler syntax for the Z8000
7026 * Z8000 Directives:: Special directives for the Z8000
7027 * Z8000 Opcodes:: Opcodes
7033 @cindex Z8000 options
7034 @cindex options, Z8000
7035 @code{@value{AS}} has no additional command-line options for the Zilog
7041 * Z8000-Chars:: Special Characters
7042 * Z8000-Regs:: Register Names
7043 * Z8000-Addressing:: Addressing Modes
7047 @subsection Special Characters
7049 @cindex line comment character, Z8000
7050 @cindex Z8000 line comment character
7051 @samp{!} is the line comment character.
7053 @cindex line separator, Z8000
7054 @cindex statement separator, Z8000
7055 @cindex Z8000 line separator
7056 You can use @samp{;} instead of a newline to separate statements.
7059 @subsection Register Names
7061 @cindex Z8000 registers
7062 @cindex registers, Z8000
7063 The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer
7064 to different sized groups of registers by register number, with the
7065 prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and
7066 @samp{rq} for 64 bit registers. You can also refer to the contents of
7067 the first eight (of the sixteen 16 bit registers) by bytes. They are
7068 named @samp{r@var{n}h} and @samp{r@var{n}l}.
7071 @exdent @emph{byte registers}
7072 r0l r0h r1h r1l r2h r2l r3h r3l
7073 r4h r4l r5h r5l r6h r6l r7h r7l
7075 @exdent @emph{word registers}
7076 r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15
7078 @exdent @emph{long word registers}
7079 rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14
7081 @exdent @emph{quad word registers}
7085 @node Z8000-Addressing
7086 @subsection Addressing Modes
7088 @cindex addressing modes, Z8000
7089 @cindex Z800 addressing modes
7090 @value{AS} understands the following addressing modes for the Z8000:
7100 Direct: the 16 bit or 24 bit address (depending on whether the assembler
7101 is in segmented or unsegmented mode) of the operand is in the instruction.
7103 @item address(r@var{n})
7104 Indexed: the 16 or 24 bit address is added to the 16 bit register to produce
7105 the final address in memory of the operand.
7107 @item r@var{n}(#@var{imm})
7108 Base Address: the 16 or 24 bit register is added to the 16 bit sign
7109 extended immediate displacement to produce the final address in memory
7112 @item r@var{n}(r@var{m})
7113 Base Index: the 16 or 24 bit register r@var{n} is added to the sign
7114 extended 16 bit index register r@var{m} to produce the final address in
7115 memory of the operand.
7118 Immediate data @var{xx}.
7121 @node Z8000 Directives
7122 @section Assembler Directives for the Z8000
7124 @cindex Z8000 directives
7125 @cindex directives, Z8000
7126 The Z8000 port of @value{AS} includes these additional assembler directives,
7127 for compatibility with other Z8000 assemblers. As shown, these do not
7128 begin with @samp{.} (unlike the ordinary @value{AS} directives).
7133 Generates code for the segmented Z8001.
7137 Generates code for the unsegmented Z8002.
7141 Synonym for @code{.file}
7145 Synonum for @code{.global}
7149 Synonym for @code{.word}
7153 Synonym for @code{.long}
7157 Synonym for @code{.byte}
7161 Assemble a string. @code{sval} expects one string literal, delimited by
7162 single quotes. It assembles each byte of the string into consecutive
7163 addresses. You can use the escape sequence @samp{%@var{xx}} (where
7164 @var{xx} represents a two-digit hexadecimal number) to represent the
7165 character whose @sc{ascii} value is @var{xx}. Use this feature to
7166 describe single quote and other characters that may not appear in string
7167 literals as themselves. For example, the C statement @w{@samp{char *a =
7168 "he said \"it's 50% off\"";}} is represented in Z8000 assembly language
7169 (shown with the assembler output in hex at the left) as
7173 @let@nonarrowing=@comment
7176 68652073 sval 'he said %22it%27s 50%25 off%22%00'
7189 synonym for @code{.section}
7193 synonym for @code{.space}
7197 synonym for @code{.align 1}
7203 @cindex Z8000 opcode summary
7204 @cindex opcode summary, Z8000
7205 @cindex mnemonics, Z8000
7206 @cindex instruction summary, Z8000
7207 For detailed information on the Z8000 machine instruction set, see
7208 @cite{Z8000 Technical Manual}.
7211 @c this table, due to the multi-col faking and hardcoded order, looks silly
7212 @c except in smallbook. See comments below "@set SMALL" near top of this file.
7214 The following table summarizes the opcodes and their arguments:
7217 @let@nonarrowing=@comment
7221 rs @r{16 bit source register}
7222 rd @r{16 bit destination register}
7223 rbs @r{8 bit source register}
7224 rbd @r{8 bit destination register}
7225 rrs @r{32 bit source register}
7226 rrd @r{32 bit destination register}
7227 rqs @r{64 bit source register}
7228 rqd @r{64 bit destination register}
7229 addr @r{16/24 bit address}
7230 imm @r{immediate data}
7232 adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc
7233 adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc
7234 add rd,@@rs clrb rbd dab rbd
7235 add rd,addr com @@rd dbjnz rbd,disp7
7236 add rd,addr(rs) com addr dec @@rd,imm4m1
7237 add rd,imm16 com addr(rd) dec addr(rd),imm4m1
7238 add rd,rs com rd dec addr,imm4m1
7239 addb rbd,@@rs comb @@rd dec rd,imm4m1
7240 addb rbd,addr comb addr decb @@rd,imm4m1
7241 addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1
7242 addb rbd,imm8 comb rbd decb addr,imm4m1
7243 addb rbd,rbs comflg flags decb rbd,imm4m1
7244 addl rrd,@@rs cp @@rd,imm16 di i2
7245 addl rrd,addr cp addr(rd),imm16 div rrd,@@rs
7246 addl rrd,addr(rs) cp addr,imm16 div rrd,addr
7247 addl rrd,imm32 cp rd,@@rs div rrd,addr(rs)
7248 addl rrd,rrs cp rd,addr div rrd,imm16
7249 and rd,@@rs cp rd,addr(rs) div rrd,rs
7250 and rd,addr cp rd,imm16 divl rqd,@@rs
7251 and rd,addr(rs) cp rd,rs divl rqd,addr
7252 and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs)
7253 and rd,rs cpb addr(rd),imm8 divl rqd,imm32
7254 andb rbd,@@rs cpb addr,imm8 divl rqd,rrs
7255 andb rbd,addr cpb rbd,@@rs djnz rd,disp7
7256 andb rbd,addr(rs) cpb rbd,addr ei i2
7257 andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs
7258 andb rbd,rbs cpb rbd,imm8 ex rd,addr
7259 bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs)
7260 bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs
7261 bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs
7262 bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr
7263 bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs)
7264 bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs
7265 bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8
7266 bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8
7267 bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8
7268 bitb rbd,rs cpl rrd,@@rs ext8f imm8
7269 bpt cpl rrd,addr exts rrd
7270 call @@rd cpl rrd,addr(rs) extsb rd
7271 call addr cpl rrd,imm32 extsl rqd
7272 call addr(rd) cpl rrd,rrs halt
7273 calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs
7274 clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16
7275 clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs
7276 clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16
7277 clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1
7278 clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1
7279 inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs)
7280 inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16
7281 incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs
7282 incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs
7283 incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr
7284 incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs)
7285 ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32
7286 indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs
7287 inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd
7288 inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr
7289 iret ldib @@rd,@@rs,rr neg addr(rd)
7290 jp cc,@@rd ldir @@rd,@@rs,rr neg rd
7291 jp cc,addr ldirb @@rd,@@rs,rr negb @@rd
7292 jp cc,addr(rd) ldk rd,imm4 negb addr
7293 jr cc,disp8 ldl @@rd,rrs negb addr(rd)
7294 ld @@rd,imm16 ldl addr(rd),rrs negb rbd
7295 ld @@rd,rs ldl addr,rrs nop
7296 ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs
7297 ld addr(rd),rs ldl rd(rx),rrs or rd,addr
7298 ld addr,imm16 ldl rrd,@@rs or rd,addr(rs)
7299 ld addr,rs ldl rrd,addr or rd,imm16
7300 ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs
7301 ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs
7302 ld rd,@@rs ldl rrd,rrs orb rbd,addr
7303 ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs)
7304 ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8
7305 ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs
7306 ld rd,rs ldm addr(rd),rs,n out @@rd,rs
7307 ld rd,rs(imm16) ldm addr,rs,n out imm16,rs
7308 ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs
7309 lda rd,addr ldm rd,addr(rs),n outb imm16,rbs
7310 lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra
7311 lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba
7312 lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra
7313 ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra
7314 ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs
7315 ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs
7316 ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs
7317 ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs
7318 ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs
7319 ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs
7320 ldb rbd,@@rs mbit popl addr,@@rs
7321 ldb rbd,addr mreq rd popl rrd,@@rs
7322 ldb rbd,addr(rs) mres push @@rd,@@rs
7323 ldb rbd,imm8 mset push @@rd,addr
7324 ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs)
7325 ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16
7326 push @@rd,rs set addr,imm4 subl rrd,imm32
7327 pushl @@rd,@@rs set rd,imm4 subl rrd,rrs
7328 pushl @@rd,addr set rd,rs tcc cc,rd
7329 pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd
7330 pushl @@rd,rrs setb addr(rd),imm4 test @@rd
7331 res @@rd,imm4 setb addr,imm4 test addr
7332 res addr(rd),imm4 setb rbd,imm4 test addr(rd)
7333 res addr,imm4 setb rbd,rs test rd
7334 res rd,imm4 setflg imm4 testb @@rd
7335 res rd,rs sinb rbd,imm16 testb addr
7336 resb @@rd,imm4 sinb rd,imm16 testb addr(rd)
7337 resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd
7338 resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd
7339 resb rbd,imm4 sinib @@rd,@@rs,ra testl addr
7340 resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd)
7341 resflg imm4 sla rd,imm8 testl rrd
7342 ret cc slab rbd,imm8 trdb @@rd,@@rs,rba
7343 rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba
7344 rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr
7345 rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr
7346 rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr
7347 rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr
7348 rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr
7349 rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr
7350 rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd
7351 rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr
7352 rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd)
7353 rsvd36 sra rd,imm8 tset rd
7354 rsvd38 srab rbd,imm8 tsetb @@rd
7355 rsvd78 sral rrd,imm8 tsetb addr
7356 rsvd7e srl rd,imm8 tsetb addr(rd)
7357 rsvd9d srlb rbd,imm8 tsetb rbd
7358 rsvd9f srll rrd,imm8 xor rd,@@rs
7359 rsvdb9 sub rd,@@rs xor rd,addr
7360 rsvdbf sub rd,addr xor rd,addr(rs)
7361 sbc rd,rs sub rd,addr(rs) xor rd,imm16
7362 sbcb rbd,rbs sub rd,imm16 xor rd,rs
7363 sc imm8 sub rd,rs xorb rbd,@@rs
7364 sda rd,rs subb rbd,@@rs xorb rbd,addr
7365 sdab rbd,rs subb rbd,addr xorb rbd,addr(rs)
7366 sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8
7367 sdl rd,rs subb rbd,imm8 xorb rbd,rbs
7368 sdlb rbd,rs subb rbd,rbs xorb rbd,rbs
7369 sdll rrd,rs subl rrd,@@rs
7370 set @@rd,imm4 subl rrd,addr
7371 set addr(rd),imm4 subl rrd,addr(rs)
7383 @node MIPS-Dependent
7384 @chapter MIPS Dependent Features
7387 @node Machine Dependencies
7388 @chapter MIPS Dependent Features
7395 @sc{gnu} @code{@value{AS}} for @sc{mips} architectures supports the @sc{mips}
7396 @sc{r2000}, @sc{r3000}, @sc{r4000} and @sc{r6000} processors. For information
7397 about the @sc{mips} instruction set, see @cite{MIPS RISC Architecture}, by Kane
7398 and Heindrich (Prentice-Hall). For an overview of @sc{mips} assembly
7399 conventions, see ``Appendix D: Assembly Language Programming'' in the same
7403 * MIPS Opts:: Assembler options
7404 * MIPS Object:: ECOFF object code
7405 * MIPS Stabs:: Directives for debugging information
7406 * MIPS ISA:: Directives to override the ISA level
7410 @section Assembler options
7412 The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support these
7416 @cindex @code{-G} option (MIPS)
7418 This option sets the largest size of an object that can be referenced
7419 implicitly with the @code{gp} register. It is only accepted for targets
7420 that use @sc{ecoff} format. The default value is 8.
7422 @cindex @code{-EB} option (MIPS)
7423 @cindex @code{-EL} option (MIPS)
7424 @cindex MIPS big-endian output
7425 @cindex MIPS little-endian output
7426 @cindex big-endian output, MIPS
7427 @cindex little-endian output, MIPS
7430 Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or
7431 little-endian output at run time (unlike the other @sc{gnu} development
7432 tools, which must be configured for one or the other). Use @samp{-EB}
7433 to select big-endian output, and @samp{-EL} for little-endian.
7435 @cindex MIPS architecture options
7439 Generate code for a particular MIPS Instruction Set Architecture level.
7440 @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
7441 @samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000}
7442 processor. You can also switch instruction sets during the assembly; see
7443 @ref{MIPS ISA,, Directives to override the ISA level}.
7447 Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept
7448 the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
7449 instructions around accesses to the @samp{HI} and @samp{LO} registers.
7450 @samp{-no-m4650} turns off this option.
7452 @item -mcpu=@var{CPU}
7453 Generate code for a particular MIPS cpu. This has little effect on the
7454 assembler, but it is passed by @code{@value{GCC}}.
7456 @cindex @code{-nocpp} ignored (MIPS)
7458 This option is ignored. It is accepted for command-line compatibility with
7459 other assemblers, which use it to turn off C style preprocessing. With
7460 @sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the
7461 @sc{gnu} assembler itself never runs the C preprocessor.
7465 @c FIXME! (1) reflect these options (next item too) in option summaries;
7466 @c (2) stop teasing, say _which_ instructions expanded _how_.
7467 @code{@value{AS}} automatically macro expands certain division and
7468 multiplication instructions to check for overflow and division by zero. This
7469 option causes @code{@value{AS}} to generate code to take a trap exception
7470 rather than a break exception when an error is detected. The trap instructions
7471 are only supported at Instruction Set Architecture level 2 and higher.
7475 Generate code to take a break exception rather than a trap exception when an
7476 error is detected. This is the default.
7480 @section MIPS ECOFF object code
7482 @cindex ECOFF sections
7483 @cindex MIPS ECOFF sections
7484 Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections
7485 besides the usual @code{.text}, @code{.data} and @code{.bss}. The
7486 additional sections are @code{.rdata}, used for read-only data,
7487 @code{.sdata}, used for small data, and @code{.sbss}, used for small
7490 @cindex small objects, MIPS ECOFF
7491 @cindex @code{gp} register, MIPS
7492 When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28})
7493 register to form the address of a ``small object''. Any object in the
7494 @code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense.
7495 For external objects, or for objects in the @code{.bss} section, you can use
7496 the @code{@value{GCC}} @samp{-G} option to control the size of objects addressed via
7497 @code{$gp}; the default value is 8, meaning that a reference to any object
7498 eight bytes or smaller uses @code{$gp}. Passing @samp{-G 0} to
7499 @code{@value{AS}} prevents it from using the @code{$gp} register on the basis
7500 of object size (but the assembler uses @code{$gp} for objects in @code{.sdata}
7501 or @code{sbss} in any case). The size of an object in the @code{.bss} section
7502 is set by the @code{.comm} or @code{.lcomm} directive that defines it. The
7503 size of an external object may be set with the @code{.extern} directive. For
7504 example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes
7505 in length, whie leaving @code{sym} otherwise undefined.
7507 Using small @sc{ecoff} objects requires linker support, and assumes that the
7508 @code{$gp} register is correctly initialized (normally done automatically by
7509 the startup code). @sc{mips} @sc{ecoff} assembly code must not modify the
7510 @code{$gp} register.
7513 @section Directives for debugging information
7515 @cindex MIPS debugging directives
7516 @sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for
7517 generating debugging information which are not support by traditional @sc{mips}
7518 assemblers. These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file},
7519 @code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val},
7520 @code{.stabd}, @code{.stabn}, and @code{.stabs}. The debugging information
7521 generated by the three @code{.stab} directives can only be read by @sc{gdb},
7522 not by traditional @sc{mips} debuggers (this enhancement is required to fully
7523 support C++ debugging). These directives are primarily used by compilers, not
7524 assembly language programmers!
7527 @section Directives to override the ISA level
7529 @cindex MIPS ISA override
7530 @kindex @code{.set mips@var{n}}
7531 @sc{gnu} @code{@value{AS}} supports an additional directive to change the
7532 @sc{mips} Instruction Set Architecture level on the fly: @code{.set
7533 mips@var{n}}. @var{n} should be a number from 0 to 3. A value from 1 to 3
7534 makes the assembler accept instructions for the corresponding @sc{isa} level,
7535 from that point on in the assembly. @code{.set mips@var{n}} affects not only
7536 which instructions are permitted, but also how certain macros are expanded.
7537 @code{.set mips0} restores the @sc{isa} level to its original level: either the
7538 level you selected with command line options, or the default for your
7539 configuration. You can use this feature to permit specific @sc{r4000}
7540 instructions while assembling in 32 bit mode. Use this directive with care!
7542 Traditional @sc{mips} assemblers do not support this directive.
7546 @c reverse effect of @down at top of generic Machine-Dep chapter
7550 @node Acknowledgements
7551 @chapter Acknowledgements
7553 If you have contributed to @code{@value{AS}} and your name isn't listed here,
7554 it is not meant as a slight. We just don't know about it. Send mail to the
7555 maintainer, and we'll correct the situation. Currently (January 1994), the
7556 maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
7558 Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any more
7561 Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
7562 information and the 68k series machines, most of the preprocessing pass, and
7563 extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}.
7565 K. Richard Pixley maintained GAS for a while, adding various enhancements and
7566 many bug fixes, including merging support for several processors, breaking GAS
7567 up to handle multiple object file format back ends (including heavy rewrite,
7568 testing, an integration of the coff and b.out back ends), adding configuration
7569 including heavy testing and verification of cross assemblers and file splits
7570 and renaming, converted GAS to strictly ANSI C including full prototypes, added
7571 support for m680[34]0 and cpu32, did considerable work on i960 including a COFF
7572 port (including considerable amounts of reverse engineering), a SPARC opcode
7573 file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know''
7574 assertions and made them work, much other reorganization, cleanup, and lint.
7576 Ken Raeburn wrote the high-level BFD interface code to replace most of the code
7577 in format-specific I/O modules.
7579 The original VMS support was contributed by David L. Kashtan. Eric Youngdale
7580 has done much work with it since.
7582 The Intel 80386 machine description was written by Eliot Dresselhaus.
7584 Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
7586 The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
7587 University and Torbjorn Granlund of the Swedish Institute of Computer Science.
7589 Keith Knowles at the Open Software Foundation wrote the original MIPS back end
7590 (@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support
7591 (which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to
7592 support a.out format.
7594 Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k,
7595 tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
7596 Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
7597 use BFD for some low-level operations, for use with the H8/300 and AMD 29k
7600 John Gilmore built the AMD 29000 support, added @code{.include} support, and
7601 simplified the configuration of which versions accept which directives. He
7602 updated the 68k machine description so that Motorola's opcodes always produced
7603 fixed-size instructions (e.g. @code{jsr}), while synthetic instructions
7604 remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested
7605 cross-compilation support, and one bug in relaxation that took a week and
7606 required the proverbial one-bit fix.
7608 Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
7609 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
7610 added support for MIPS ECOFF and ELF targets, and made a few other minor
7613 Steve Chamberlain made @code{@value{AS}} able to generate listings.
7615 Hewlett-Packard contributed support for the HP9000/300.
7617 Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
7618 along with a fairly extensive HPPA testsuite (for both SOM and ELF object
7619 formats). This work was supported by both the Center for Software Science at
7620 the University of Utah and Cygnus Support.
7622 Support for ELF format files has been worked on by Mark Eichin of Cygnus
7623 Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
7624 Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
7625 Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
7626 and some initial 64-bit support).
7628 Several engineers at Cygnus Support have also provided many small bug fixes and
7629 configuration enhancements.
7631 Many others have contributed large or small bugfixes and enhancements. If
7632 you have contributed significant work and are not mentioned on this list, and
7633 want to be, let us know. Some of the history has been lost; we are not
7634 intentionally leaving anyone out.