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
205 @c Hitachi family chips have no machine-dependent assembler options
208 @c HPPA has no machine-dependent assembler options (yet).
211 [ -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite | -bump ]
214 @c Z8000 has no machine-dependent assembler options
217 @c see md_parse_option in tc-i960.c
218 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
222 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
225 [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ]
226 [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ]
227 [ --trap ] [ --break ]
229 [ -- | @var{files} @dots{} ]
234 Turn on listings, in any of a variety of ways:
238 omit debugging directives
241 include high-level source
247 omit forms processing
253 You may combine these options; for example, use @samp{-aln} for assembly
254 listing without forms processing. By itself, @samp{-a} defaults to
255 @samp{-ahls}---that is, all listings turned on.
258 Ignored. This option is accepted for script compatibility with calls to
262 ``fast''---skip whitespace and comment preprocessing (assume source is
266 Print a summary of the command line options and exit.
269 Add directory @var{dir} to the search list for @code{.include} directives.
272 Don't warn about signed overflow.
275 @ifclear DIFF-TBL-KLUGE
276 This option is accepted but has no effect on the @value{TARGET} family.
278 @ifset DIFF-TBL-KLUGE
279 Issue warnings when difference tables altered for long displacements.
283 Keep (in the symbol table) local symbols, starting with @samp{L}.
285 @item -o @var{objfile}
286 Name the object-file output from @code{@value{AS}} @var{objfile}.
289 Fold the data section into the text section.
292 Print the maximum space (in bytes) and total time (in seconds) used by
297 Print the @code{as} version.
300 Print the @code{as} version and exit.
303 Suppress warning messages.
312 Generate an object file even after errors.
314 @item -- | @var{files} @dots{}
315 Standard input, or source files to assemble.
320 The following options are available when @value{AS} is configured for the
321 Intel 80960 processor.
324 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
325 Specify which variant of the 960 architecture is the target.
328 Add code to collect statistics about branches taken.
331 Do not alter compare-and-branch instructions for long displacements;
338 The following options are available when @value{AS} is configured for the
339 Motorola 68000 series.
344 Shorten references to undefined symbols, to one word instead of two.
346 @item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040
347 @itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32
348 Specify what processor in the 68000 family is the target. The default
349 is normally the 68020, but this can be changed at configuration time.
351 @item -m68881 | -m68882 | -mno-68881 | -mno-68882
352 The target machine does (or does not) have a floating-point coprocessor.
353 The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
354 the basic 68000 is not compatible with the 68881, a combination of the
355 two can be specified, since it's possible to do emulation of the
356 coprocessor instructions with the main processor.
358 @item -m68851 | -mno-68851
359 The target machine does (or does not) have a memory-management
360 unit coprocessor. The default is to assume an MMU for 68020 and up.
366 The following options are available when @code{@value{AS}} is configured
367 for the SPARC architecture:
370 @item -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite
371 Explicitly select a variant of the SPARC architecture.
374 Warn when the assembler switches to another architecture.
379 The following options are available when @value{AS} is configured for
384 This option sets the largest size of an object that can be referenced
385 implicitly with the @code{gp} register. It is only accepted for targets that
386 use ECOFF format, such as a DECstation running Ultrix. The default value is 8.
388 @cindex MIPS endianness
389 @cindex endianness, MIPS
390 @cindex big endian output, MIPS
392 Generate ``big endian'' format output.
394 @cindex little endian output, MIPS
396 Generate ``little endian'' format output.
402 Generate code for a particular MIPS Instruction Set Architecture level.
403 @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
404 @samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000}
409 Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept
410 the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
411 instructions around accesses to the @samp{HI} and @samp{LO} registers.
412 @samp{-no-m4650} turns off this option.
414 @item -mcpu=@var{CPU}
415 Generate code for a particular MIPS cpu. This has little effect on the
416 assembler, but it is passed by @code{@value{GCC}}.
419 @code{@value{AS}} ignores this option. It is accepted for compatibility with
426 Control how to deal with multiplication overflow and division by zero.
427 @samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception
428 (and only work for Instruction Set Architecture level 2 and higher);
429 @samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a
435 * Manual:: Structure of this Manual
436 * GNU Assembler:: @value{AS}, the GNU Assembler
437 * Object Formats:: Object File Formats
438 * Command Line:: Command Line
439 * Input Files:: Input Files
440 * Object:: Output (Object) File
441 * Errors:: Error and Warning Messages
445 @section Structure of this Manual
447 @cindex manual, structure and purpose
448 This manual is intended to describe what you need to know to use
449 @sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including
450 notation for symbols, constants, and expressions; the directives that
451 @code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}.
454 We also cover special features in the @value{TARGET}
455 configuration of @code{@value{AS}}, including assembler directives.
458 This manual also describes some of the machine-dependent features of
459 various flavors of the assembler.
462 @cindex machine instructions (not covered)
463 On the other hand, this manual is @emph{not} intended as an introduction
464 to programming in assembly language---let alone programming in general!
465 In a similar vein, we make no attempt to introduce the machine
466 architecture; we do @emph{not} describe the instruction set, standard
467 mnemonics, registers or addressing modes that are standard to a
468 particular architecture.
470 You may want to consult the manufacturer's
471 machine architecture manual for this information.
475 For information on the H8/300 machine instruction set, see @cite{H8/300
476 Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H,
477 see @cite{H8/300H Series Programming Manual} (Hitachi).
480 For information on the H8/500 machine instruction set, see @cite{H8/500
481 Series Programming Manual} (Hitachi M21T001).
484 For information on the Hitachi SH machine instruction set, see
485 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
488 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
492 @c I think this is premature---pesch@cygnus.com, 17jan1991
494 Throughout this manual, we assume that you are running @dfn{GNU},
495 the portable operating system from the @dfn{Free Software
496 Foundation, Inc.}. This restricts our attention to certain kinds of
497 computer (in particular, the kinds of computers that @sc{gnu} can run on);
498 once this assumption is granted examples and definitions need less
501 @code{@value{AS}} is part of a team of programs that turn a high-level
502 human-readable series of instructions into a low-level
503 computer-readable series of instructions. Different versions of
504 @code{@value{AS}} are used for different kinds of computer.
507 @c There used to be a section "Terminology" here, which defined
508 @c "contents", "byte", "word", and "long". Defining "word" to any
509 @c particular size is confusing when the .word directive may generate 16
510 @c bits on one machine and 32 bits on another; in general, for the user
511 @c version of this manual, none of these terms seem essential to define.
512 @c They were used very little even in the former draft of the manual;
513 @c this draft makes an effort to avoid them (except in names of
517 @section @value{AS}, the GNU Assembler
519 @sc{gnu} @code{as} is really a family of assemblers.
521 This manual describes @code{@value{AS}}, a member of that family which is
522 configured for the @value{TARGET} architectures.
524 If you use (or have used) the @sc{gnu} assembler on one architecture, you
525 should find a fairly similar environment when you use it on another
526 architecture. Each version has much in common with the others,
527 including object file formats, most assembler directives (often called
528 @dfn{pseudo-ops}) and assembler syntax.@refill
530 @cindex purpose of @sc{gnu} @code{@value{AS}}
531 @code{@value{AS}} is primarily intended to assemble the output of the
532 @sc{gnu} C compiler @code{@value{GCC}} for use by the linker
533 @code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}}
534 assemble correctly everything that other assemblers for the same
535 machine would assemble.
537 Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
540 @c This remark should appear in generic version of manual; assumption
541 @c here is that generic version sets M680x0.
542 This doesn't mean @code{@value{AS}} always uses the same syntax as another
543 assembler for the same architecture; for example, we know of several
544 incompatible versions of 680x0 assembly language syntax.
547 Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
548 program in one pass of the source file. This has a subtle impact on the
549 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
552 @section Object File Formats
554 @cindex object file format
555 The @sc{gnu} assembler can be configured to produce several alternative
556 object file formats. For the most part, this does not affect how you
557 write assembly language programs; but directives for debugging symbols
558 are typically different in different file formats. @xref{Symbol
559 Attributes,,Symbol Attributes}.
562 On the @value{TARGET}, @code{@value{AS}} is configured to produce
563 @value{OBJ-NAME} format object files.
565 @c The following should exhaust all configs that set MULTI-OBJ, ideally
567 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
568 @code{a.out} or COFF format object files.
571 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
572 @code{b.out} or COFF format object files.
575 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
576 SOM or ELF format object files.
581 @section Command Line
583 @cindex command line conventions
584 After the program name @code{@value{AS}}, the command line may contain
585 options and file names. Options may appear in any order, and may be
586 before, after, or between file names. The order of file names is
589 @cindex standard input, as input file
591 @file{--} (two hyphens) by itself names the standard input file
592 explicitly, as one of the files for @code{@value{AS}} to assemble.
594 @cindex options, command line
595 Except for @samp{--} any command line argument that begins with a
596 hyphen (@samp{-}) is an option. Each option changes the behavior of
597 @code{@value{AS}}. No option changes the way another option works. An
598 option is a @samp{-} followed by one or more letters; the case of
599 the letter is important. All options are optional.
601 Some options expect exactly one file name to follow them. The file
602 name may either immediately follow the option's letter (compatible
603 with older assemblers) or it may be the next command argument (@sc{gnu}
604 standard). These two command lines are equivalent:
607 @value{AS} -o my-object-file.o mumble.s
608 @value{AS} -omy-object-file.o mumble.s
615 @cindex source program
617 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
618 describe the program input to one run of @code{@value{AS}}. The program may
619 be in one or more files; how the source is partitioned into files
620 doesn't change the meaning of the source.
622 @c I added "con" prefix to "catenation" just to prove I can overcome my
623 @c APL training... pesch@cygnus.com
624 The source program is a concatenation of the text in all the files, in the
627 Each time you run @code{@value{AS}} it assembles exactly one source
628 program. The source program is made up of one or more files.
629 (The standard input is also a file.)
631 You give @code{@value{AS}} a command line that has zero or more input file
632 names. The input files are read (from left file name to right). A
633 command line argument (in any position) that has no special meaning
634 is taken to be an input file name.
636 If you give @code{@value{AS}} no file names it attempts to read one input file
637 from the @code{@value{AS}} standard input, which is normally your terminal. You
638 may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program
641 Use @samp{--} if you need to explicitly name the standard input file
642 in your command line.
644 If the source is empty, @code{@value{AS}} produces a small, empty object
647 @subheading Filenames and Line-numbers
649 @cindex input file linenumbers
650 @cindex line numbers, in input files
651 There are two ways of locating a line in the input file (or files) and
652 either may be used in reporting error messages. One way refers to a line
653 number in a physical file; the other refers to a line number in a
654 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
656 @dfn{Physical files} are those files named in the command line given
657 to @code{@value{AS}}.
659 @dfn{Logical files} are simply names declared explicitly by assembler
660 directives; they bear no relation to physical files. Logical file names
661 help error messages reflect the original source file, when @code{@value{AS}}
662 source is itself synthesized from other files.
663 @xref{App-File,,@code{.app-file}}.
666 @section Output (Object) File
672 Every time you run @code{@value{AS}} it produces an output file, which is
673 your assembly language program translated into numbers. This file
674 is the object file. Its default name is
682 @code{b.out} when @code{@value{AS}} is configured for the Intel 80960.
684 You can give it another name by using the @code{-o} option. Conventionally,
685 object file names end with @file{.o}. The default name is used for historical
686 reasons: older assemblers were capable of assembling self-contained programs
687 directly into a runnable program. (For some formats, this isn't currently
688 possible, but it can be done for the @code{a.out} format.)
692 The object file is meant for input to the linker @code{@value{LD}}. It contains
693 assembled program code, information to help @code{@value{LD}} integrate
694 the assembled program into a runnable file, and (optionally) symbolic
695 information for the debugger.
697 @c link above to some info file(s) like the description of a.out.
698 @c don't forget to describe GNU info as well as Unix lossage.
701 @section Error and Warning Messages
703 @cindex error messsages
704 @cindex warning messages
705 @cindex messages from @code{@value{AS}}
706 @code{@value{AS}} may write warnings and error messages to the standard error
707 file (usually your terminal). This should not happen when a compiler
708 runs @code{@value{AS}} automatically. Warnings report an assumption made so
709 that @code{@value{AS}} could keep assembling a flawed program; errors report a
710 grave problem that stops the assembly.
712 @cindex format of warning messages
713 Warning messages have the format
716 file_name:@b{NNN}:Warning Message Text
720 @cindex line numbers, in warnings/errors
721 (where @b{NNN} is a line number). If a logical file name has been given
722 (@pxref{App-File,,@code{.app-file}}) it is used for the filename,
723 otherwise the name of the current input file is used. If a logical line
726 (@pxref{Line,,@code{.line}})
730 (@pxref{Line,,@code{.line}})
733 (@pxref{Ln,,@code{.ln}})
736 then it is used to calculate the number printed,
737 otherwise the actual line in the current source file is printed. The
738 message text is intended to be self explanatory (in the grand Unix
741 @cindex format of error messages
742 Error messages have the format
744 file_name:@b{NNN}:FATAL:Error Message Text
746 The file name and line number are derived as for warning
747 messages. The actual message text may be rather less explanatory
748 because many of them aren't supposed to happen.
751 @chapter Command-Line Options
753 @cindex options, all versions of @code{@value{AS}}
754 This chapter describes command-line options available in @emph{all}
755 versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific
757 to the @value{TARGET}.
760 to particular machine architectures.
763 If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2), you
764 can use the @samp{-Wa} option to pass arguments through to the
765 assembler. The assembler arguments must be separated from each other
766 (and the @samp{-Wa}) by commas. For example:
769 gcc -c -g -O -Wa,-alh,-L file.c
773 emits a listing to standard output with high-level
776 Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
777 command-line options are automatically passed to the assembler by the compiler.
778 (You can call the @sc{gnu} compiler driver with the @samp{-v} option to see
779 precisely what options it passes to each compilation pass, including the
783 * a:: -a[dhlns] enable listings
784 * D:: -D for compatibility
785 * f:: -f to work faster
786 * I:: -I for .include search path
787 @ifclear DIFF-TBL-KLUGE
788 * K:: -K for compatibility
790 @ifset DIFF-TBL-KLUGE
791 * K:: -K for difference tables
794 * L:: -L to retain local labels
795 * o:: -o to name the object file
796 * R:: -R to join data and text sections
797 * statistics:: --statistics to see statistics about assembly
798 * v:: -v to announce version
799 * W:: -W to suppress warnings
800 * Z:: -Z to make object file even after errors
804 @section Enable Listings: @code{-a[dhlns]}
812 @cindex listings, enabling
813 @cindex assembly listings, enabling
815 These options enable listing output from the assembler. By itself,
816 @samp{-a} requests high-level, assembly, and symbols listing.
817 You can use other letters to select specific options for the list:
818 @samp{-ah} requests a high-level language listing,
819 @samp{-al} requests an output-program assembly listing, and
820 @samp{-as} requests a symbol table listing.
821 High-level listings require that a compiler debugging option like
822 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
825 Use the @samp{-ad} option to omit debugging directives from the
828 Once you have specified one of these options, you can further control
829 listing output and its appearance using the directives @code{.list},
830 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
832 The @samp{-an} option turns off all forms processing.
833 If you do not request listing output with one of the @samp{-a} options, the
834 listing-control directives have no effect.
836 The letters after @samp{-a} may be combined into one option,
837 @emph{e.g.}, @samp{-aln}.
843 This option has no effect whatsoever, but it is accepted to make it more
844 likely that scripts written for other assemblers also work with
848 @section Work Faster: @code{-f}
851 @cindex trusted compiler
852 @cindex faster processing (@code{-f})
853 @samp{-f} should only be used when assembling programs written by a
854 (trusted) compiler. @samp{-f} stops the assembler from doing whitespace
855 and comment preprocessing on
856 the input file(s) before assembling them. @xref{Preprocessing,
860 @emph{Warning:} if you use @samp{-f} when the files actually need to be
861 preprocessed (if they contain comments, for example), @code{@value{AS}} does
866 @section @code{.include} search path: @code{-I} @var{path}
868 @kindex -I @var{path}
869 @cindex paths for @code{.include}
870 @cindex search path for @code{.include}
871 @cindex @code{include} directive search path
872 Use this option to add a @var{path} to the list of directories
873 @code{@value{AS}} searches for files specified in @code{.include}
874 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
875 many times as necessary to include a variety of paths. The current
876 working directory is always searched first; after that, @code{@value{AS}}
877 searches any @samp{-I} directories in the same order as they were
878 specified (left to right) on the command line.
881 @section Difference Tables: @code{-K}
884 @ifclear DIFF-TBL-KLUGE
885 On the @value{TARGET} family, this option is allowed, but has no effect. It is
886 permitted for compatibility with the @sc{gnu} assembler on other platforms,
887 where it can be used to warn when the assembler alters the machine code
888 generated for @samp{.word} directives in difference tables. The @value{TARGET}
889 family does not have the addressing limitations that sometimes lead to this
890 alteration on other platforms.
893 @ifset DIFF-TBL-KLUGE
894 @cindex difference tables, warning
895 @cindex warning for altered difference tables
896 @code{@value{AS}} sometimes alters the code emitted for directives of the form
897 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
898 You can use the @samp{-K} option if you want a warning issued when this
903 @section Include Local Labels: @code{-L}
906 @cindex local labels, retaining in output
907 Labels beginning with @samp{L} (upper case only) are called @dfn{local
908 labels}. @xref{Symbol Names}. Normally you do not see such labels when
909 debugging, because they are intended for the use of programs (like
910 compilers) that compose assembler programs, not for your notice.
911 Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not
912 normally debug with them.
914 This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols
915 in the object file. Usually if you do this you also tell the linker
916 @code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
918 By default, a local label is any label beginning with @samp{L}, but each
919 target is allowed to redefine the local label prefix.
921 On the HPPA local labels begin with @samp{L$}.
925 @section Name the Object File: @code{-o}
928 @cindex naming object file
929 @cindex object file name
930 There is always one object file output when you run @code{@value{AS}}. By
931 default it has the name
934 @file{a.out} (or @file{b.out}, for Intel 960 targets only).
948 You use this option (which takes exactly one filename) to give the
949 object file a different name.
951 Whatever the object file is called, @code{@value{AS}} overwrites any
952 existing file of the same name.
955 @section Join Data and Text Sections: @code{-R}
958 @cindex data and text sections, joining
959 @cindex text and data sections, joining
960 @cindex joining text and data sections
961 @cindex merging text and data sections
962 @code{-R} tells @code{@value{AS}} to write the object file as if all
963 data-section data lives in the text section. This is only done at
964 the very last moment: your binary data are the same, but data
965 section parts are relocated differently. The data section part of
966 your object file is zero bytes long because all its bytes are
967 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
969 When you specify @code{-R} it would be possible to generate shorter
970 address displacements (because we do not have to cross between text and
971 data section). We refrain from doing this simply for compatibility with
972 older versions of @code{@value{AS}}. In future, @code{-R} may work this way.
975 When @code{@value{AS}} is configured for COFF output,
976 this option is only useful if you use sections named @samp{.text} and
981 @code{-R} is not supported for any of the HPPA targets. Using
982 @code{-R} generates a warning from @code{@value{AS}}.
986 @section Display Assembly Statistics: @code{--statistics}
989 @cindex statistics, about assembly
990 @cindex time, total for assembly
991 @cindex space used, maximum for assembly
992 Use @samp{--statistics} to display two statistics about the resources used by
993 @code{@value{AS}}: the maximum amount of space allocated during the assembly
994 (in bytes), and the total execution time taken for the assembly (in @sc{cpu}
998 @section Announce Version: @code{-v}
1002 @cindex @code{@value{AS}} version
1003 @cindex version of @code{@value{AS}}
1004 You can find out what version of as is running by including the
1005 option @samp{-v} (which you can also spell as @samp{-version}) on the
1009 @section Suppress Warnings: @code{-W}
1012 @cindex suppressing warnings
1013 @cindex warnings, suppressing
1014 @code{@value{AS}} should never give a warning or error message when
1015 assembling compiler output. But programs written by people often
1016 cause @code{@value{AS}} to give a warning that a particular assumption was
1017 made. All such warnings are directed to the standard error file.
1018 If you use this option, no warnings are issued. This option only
1019 affects the warning messages: it does not change any particular of how
1020 @code{@value{AS}} assembles your file. Errors, which stop the assembly, are
1024 @section Generate Object File in Spite of Errors: @code{-Z}
1025 @cindex object file, after errors
1026 @cindex errors, continuing after
1027 After an error message, @code{@value{AS}} normally produces no output. If for
1028 some reason you are interested in object file output even after
1029 @code{@value{AS}} gives an error message on your program, use the @samp{-Z}
1030 option. If there are any errors, @code{@value{AS}} continues anyways, and
1031 writes an object file after a final warning message of the form @samp{@var{n}
1032 errors, @var{m} warnings, generating bad object file.}
1037 @cindex machine-independent syntax
1038 @cindex syntax, machine-independent
1039 This chapter describes the machine-independent syntax allowed in a
1040 source file. @code{@value{AS}} syntax is similar to what many other
1041 assemblers use; it is inspired by the BSD 4.2
1046 assembler, except that @code{@value{AS}} does not assemble Vax bit-fields.
1050 * Preprocessing:: Preprocessing
1051 * Whitespace:: Whitespace
1052 * Comments:: Comments
1053 * Symbol Intro:: Symbols
1054 * Statements:: Statements
1055 * Constants:: Constants
1059 @section Preprocessing
1061 @cindex preprocessing
1062 The @code{@value{AS}} internal preprocessor:
1064 @cindex whitespace, removed by preprocessor
1066 adjusts and removes extra whitespace. It leaves one space or tab before
1067 the keywords on a line, and turns any other whitespace on the line into
1070 @cindex comments, removed by preprocessor
1072 removes all comments, replacing them with a single space, or an
1073 appropriate number of newlines.
1075 @cindex constants, converted by preprocessor
1077 converts character constants into the appropriate numeric values.
1080 It does not do macro processing, include file handling, or
1081 anything else you may get from your C compiler's preprocessor. You can
1082 do include file processing with the @code{.include} directive
1083 (@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver
1084 to get other ``CPP'' style preprocessing, by giving the input file a
1085 @samp{.S} suffix. @xref{Overall Options,, Options Controlling the Kind of
1086 Output, gcc.info, Using GNU CC}.
1088 Excess whitespace, comments, and character constants
1089 cannot be used in the portions of the input text that are not
1092 @cindex turning preprocessing on and off
1093 @cindex preprocessing, turning on and off
1096 If the first line of an input file is @code{#NO_APP} or if you use the
1097 @samp{-f} option, whitespace and comments are not removed from the input file.
1098 Within an input file, you can ask for whitespace and comment removal in
1099 specific portions of the by putting a line that says @code{#APP} before the
1100 text that may contain whitespace or comments, and putting a line that says
1101 @code{#NO_APP} after this text. This feature is mainly intend to support
1102 @code{asm} statements in compilers whose output is otherwise free of comments
1109 @dfn{Whitespace} is one or more blanks or tabs, in any order.
1110 Whitespace is used to separate symbols, and to make programs neater for
1111 people to read. Unless within character constants
1112 (@pxref{Characters,,Character Constants}), any whitespace means the same
1113 as exactly one space.
1119 There are two ways of rendering comments to @code{@value{AS}}. In both
1120 cases the comment is equivalent to one space.
1122 Anything from @samp{/*} through the next @samp{*/} is a comment.
1123 This means you may not nest these comments.
1127 The only way to include a newline ('\n') in a comment
1128 is to use this sort of comment.
1131 /* This sort of comment does not nest. */
1134 @cindex line comment character
1135 Anything from the @dfn{line comment} character to the next newline
1136 is considered a comment and is ignored. The line comment character is
1138 @samp{#} on the Vax;
1141 @samp{#} on the i960;
1144 @samp{!} on the SPARC;
1147 @samp{|} on the 680x0;
1150 @samp{;} for the AMD 29K family;
1153 @samp{;} for the H8/300 family;
1156 @samp{!} for the H8/500 family;
1159 @samp{;} for the HPPA;
1162 @samp{!} for the Hitachi SH;
1165 @samp{!} for the Z8000;
1167 see @ref{Machine Dependencies}. @refill
1168 @c FIXME What about i386, m88k, i860?
1171 On some machines there are two different line comment characters. One
1172 character only begins a comment if it is the first non-whitespace character on
1173 a line, while the other always begins a comment.
1177 @cindex lines starting with @code{#}
1178 @cindex logical line numbers
1179 To be compatible with past assemblers, lines that begin with @samp{#} have a
1180 special interpretation. Following the @samp{#} should be an absolute
1181 expression (@pxref{Expressions}): the logical line number of the @emph{next}
1182 line. Then a string (@pxref{Strings,, Strings}) is allowed: if present it is a
1183 new logical file name. The rest of the line, if any, should be whitespace.
1185 If the first non-whitespace characters on the line are not numeric,
1186 the line is ignored. (Just like a comment.)
1189 # This is an ordinary comment.
1190 # 42-6 "new_file_name" # New logical file name
1191 # This is logical line # 36.
1193 This feature is deprecated, and may disappear from future versions
1194 of @code{@value{AS}}.
1199 @cindex characters used in symbols
1200 @ifclear SPECIAL-SYMS
1201 A @dfn{symbol} is one or more characters chosen from the set of all
1202 letters (both upper and lower case), digits and the three characters
1208 A @dfn{symbol} is one or more characters chosen from the set of all
1209 letters (both upper and lower case), digits and the three characters
1210 @samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in
1216 On most machines, you can also use @code{$} in symbol names; exceptions
1217 are noted in @ref{Machine Dependencies}.
1219 No symbol may begin with a digit. Case is significant.
1220 There is no length limit: all characters are significant. Symbols are
1221 delimited by characters not in that set, or by the beginning of a file
1222 (since the source program must end with a newline, the end of a file is
1223 not a possible symbol delimiter). @xref{Symbols}.
1224 @cindex length of symbols
1229 @cindex statements, structure of
1230 @cindex line separator character
1231 @cindex statement separator character
1233 @ifclear abnormal-separator
1234 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
1235 semicolon (@samp{;}). The newline or semicolon is considered part of
1236 the preceding statement. Newlines and semicolons within character
1237 constants are an exception: they do not end statements.
1239 @ifset abnormal-separator
1241 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
1242 sign (@samp{@@}). The newline or at sign is considered part of the
1243 preceding statement. Newlines and at signs within character constants
1244 are an exception: they do not end statements.
1247 A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation
1248 point (@samp{!}). The newline or exclamation point is considered part of the
1249 preceding statement. Newlines and exclamation points within character
1250 constants are an exception: they do not end statements.
1253 A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
1254 H8/300) a dollar sign (@samp{$}); or (for the
1257 (@samp{;}). The newline or separator character is considered part of
1258 the preceding statement. Newlines and separators within character
1259 constants are an exception: they do not end statements.
1264 A @dfn{statement} ends at a newline character (@samp{\n}) or line
1265 separator character. (The line separator is usually @samp{;}, unless
1266 this conflicts with the comment character; @pxref{Machine Dependencies}.) The
1267 newline or separator character is considered part of the preceding
1268 statement. Newlines and separators within character constants are an
1269 exception: they do not end statements.
1272 @cindex newline, required at file end
1273 @cindex EOF, newline must precede
1274 It is an error to end any statement with end-of-file: the last
1275 character of any input file should be a newline.@refill
1277 @cindex continuing statements
1278 @cindex multi-line statements
1279 @cindex statement on multiple lines
1280 You may write a statement on more than one line if you put a
1281 backslash (@kbd{\}) immediately in front of any newlines within the
1282 statement. When @code{@value{AS}} reads a backslashed newline both
1283 characters are ignored. You can even put backslashed newlines in
1284 the middle of symbol names without changing the meaning of your
1287 An empty statement is allowed, and may include whitespace. It is ignored.
1289 @cindex instructions and directives
1290 @cindex directives and instructions
1291 @c "key symbol" is not used elsewhere in the document; seems pedantic to
1292 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
1294 A statement begins with zero or more labels, optionally followed by a
1295 key symbol which determines what kind of statement it is. The key
1296 symbol determines the syntax of the rest of the statement. If the
1297 symbol begins with a dot @samp{.} then the statement is an assembler
1298 directive: typically valid for any computer. If the symbol begins with
1299 a letter the statement is an assembly language @dfn{instruction}: it
1300 assembles into a machine language instruction.
1302 Different versions of @code{@value{AS}} for different computers
1303 recognize different instructions. In fact, the same symbol may
1304 represent a different instruction in a different computer's assembly
1308 @cindex @code{:} (label)
1309 @cindex label (@code{:})
1310 A label is a symbol immediately followed by a colon (@code{:}).
1311 Whitespace before a label or after a colon is permitted, but you may not
1312 have whitespace between a label's symbol and its colon. @xref{Labels}.
1315 For HPPA targets, labels need not be immediately followed by a colon, but
1316 the definition of a label must begin in column zero. This also implies that
1317 only one label may be defined on each line.
1321 label: .directive followed by something
1322 another_label: # This is an empty statement.
1323 instruction operand_1, operand_2, @dots{}
1330 A constant is a number, written so that its value is known by
1331 inspection, without knowing any context. Like this:
1334 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
1335 .ascii "Ring the bell\7" # A string constant.
1336 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
1337 .float 0f-314159265358979323846264338327\
1338 95028841971.693993751E-40 # - pi, a flonum.
1343 * Characters:: Character Constants
1344 * Numbers:: Number Constants
1348 @subsection Character Constants
1350 @cindex character constants
1351 @cindex constants, character
1352 There are two kinds of character constants. A @dfn{character} stands
1353 for one character in one byte and its value may be used in
1354 numeric expressions. String constants (properly called string
1355 @emph{literals}) are potentially many bytes and their values may not be
1356 used in arithmetic expressions.
1360 * Chars:: Characters
1364 @subsubsection Strings
1366 @cindex string constants
1367 @cindex constants, string
1368 A @dfn{string} is written between double-quotes. It may contain
1369 double-quotes or null characters. The way to get special characters
1370 into a string is to @dfn{escape} these characters: precede them with
1371 a backslash @samp{\} character. For example @samp{\\} represents
1372 one backslash: the first @code{\} is an escape which tells
1373 @code{@value{AS}} to interpret the second character literally as a backslash
1374 (which prevents @code{@value{AS}} from recognizing the second @code{\} as an
1375 escape character). The complete list of escapes follows.
1377 @cindex escape codes, character
1378 @cindex character escape codes
1381 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1384 @cindex @code{\b} (backspace character)
1385 @cindex backspace (@code{\b})
1386 Mnemonic for backspace; for ASCII this is octal code 010.
1389 @c Mnemonic for EOText; for ASCII this is octal code 004.
1392 @cindex @code{\f} (formfeed character)
1393 @cindex formfeed (@code{\f})
1394 Mnemonic for FormFeed; for ASCII this is octal code 014.
1397 @cindex @code{\n} (newline character)
1398 @cindex newline (@code{\n})
1399 Mnemonic for newline; for ASCII this is octal code 012.
1402 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1405 @cindex @code{\r} (carriage return character)
1406 @cindex carriage return (@code{\r})
1407 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1410 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1411 @c other assemblers.
1414 @cindex @code{\t} (tab)
1415 @cindex tab (@code{\t})
1416 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1419 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1420 @c @item \x @var{digit} @var{digit} @var{digit}
1421 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1423 @item \ @var{digit} @var{digit} @var{digit}
1424 @cindex @code{\@var{ddd}} (octal character code)
1425 @cindex octal character code (@code{\@var{ddd}})
1426 An octal character code. The numeric code is 3 octal digits.
1427 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1428 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1431 @item \@code{x} @var{hex-digit} @var{hex-digit}
1432 @cindex @code{\@var{xdd}} (hex character code)
1433 @cindex hex character code (@code{\@var{xdd}})
1434 A hex character code. The numeric code is 2 hexadecimal digits. Either
1435 upper or lower case @code{x} works.
1439 @cindex @code{\\} (@samp{\} character)
1440 @cindex backslash (@code{\\})
1441 Represents one @samp{\} character.
1444 @c Represents one @samp{'} (accent acute) character.
1445 @c This is needed in single character literals
1446 @c (@xref{Characters,,Character Constants}.) to represent
1450 @cindex @code{\"} (doublequote character)
1451 @cindex doublequote (@code{\"})
1452 Represents one @samp{"} character. Needed in strings to represent
1453 this character, because an unescaped @samp{"} would end the string.
1455 @item \ @var{anything-else}
1456 Any other character when escaped by @kbd{\} gives a warning, but
1457 assembles as if the @samp{\} was not present. The idea is that if
1458 you used an escape sequence you clearly didn't want the literal
1459 interpretation of the following character. However @code{@value{AS}} has no
1460 other interpretation, so @code{@value{AS}} knows it is giving you the wrong
1461 code and warns you of the fact.
1464 Which characters are escapable, and what those escapes represent,
1465 varies widely among assemblers. The current set is what we think
1466 the BSD 4.2 assembler recognizes, and is a subset of what most C
1467 compilers recognize. If you are in doubt, do not use an escape
1471 @subsubsection Characters
1473 @cindex single character constant
1474 @cindex character, single
1475 @cindex constant, single character
1476 A single character may be written as a single quote immediately
1477 followed by that character. The same escapes apply to characters as
1478 to strings. So if you want to write the character backslash, you
1479 must write @kbd{'\\} where the first @code{\} escapes the second
1480 @code{\}. As you can see, the quote is an acute accent, not a
1481 grave accent. A newline
1483 @ifclear abnormal-separator
1484 (or semicolon @samp{;})
1486 @ifset abnormal-separator
1488 (or at sign @samp{@@})
1491 (or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
1497 immediately following an acute accent is taken as a literal character
1498 and does not count as the end of a statement. The value of a character
1499 constant in a numeric expression is the machine's byte-wide code for
1500 that character. @code{@value{AS}} assumes your character code is ASCII:
1501 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1504 @subsection Number Constants
1506 @cindex constants, number
1507 @cindex number constants
1508 @code{@value{AS}} distinguishes three kinds of numbers according to how they
1509 are stored in the target machine. @emph{Integers} are numbers that
1510 would fit into an @code{int} in the C language. @emph{Bignums} are
1511 integers, but they are stored in more than 32 bits. @emph{Flonums}
1512 are floating point numbers, described below.
1515 * Integers:: Integers
1520 * Bit Fields:: Bit Fields
1526 @subsubsection Integers
1528 @cindex constants, integer
1530 @cindex binary integers
1531 @cindex integers, binary
1532 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1533 the binary digits @samp{01}.
1535 @cindex octal integers
1536 @cindex integers, octal
1537 An octal integer is @samp{0} followed by zero or more of the octal
1538 digits (@samp{01234567}).
1540 @cindex decimal integers
1541 @cindex integers, decimal
1542 A decimal integer starts with a non-zero digit followed by zero or
1543 more digits (@samp{0123456789}).
1545 @cindex hexadecimal integers
1546 @cindex integers, hexadecimal
1547 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1548 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1550 Integers have the usual values. To denote a negative integer, use
1551 the prefix operator @samp{-} discussed under expressions
1552 (@pxref{Prefix Ops,,Prefix Operators}).
1555 @subsubsection Bignums
1558 @cindex constants, bignum
1559 A @dfn{bignum} has the same syntax and semantics as an integer
1560 except that the number (or its negative) takes more than 32 bits to
1561 represent in binary. The distinction is made because in some places
1562 integers are permitted while bignums are not.
1565 @subsubsection Flonums
1567 @cindex floating point numbers
1568 @cindex constants, floating point
1570 @cindex precision, floating point
1571 A @dfn{flonum} represents a floating point number. The translation is
1572 indirect: a decimal floating point number from the text is converted by
1573 @code{@value{AS}} to a generic binary floating point number of more than
1574 sufficient precision. This generic floating point number is converted
1575 to a particular computer's floating point format (or formats) by a
1576 portion of @code{@value{AS}} specialized to that computer.
1578 A flonum is written by writing (in order)
1583 (@samp{0} is optional on the HPPA.)
1587 A letter, to tell @code{@value{AS}} the rest of the number is a flonum.
1589 @kbd{e} is recommended. Case is not important.
1591 @c FIXME: verify if flonum syntax really this vague for most cases
1592 (Any otherwise illegal letter works here, but that might be changed. Vax BSD
1593 4.2 assembler seems to allow any of @samp{defghDEFGH}.)
1596 On the H8/300, H8/500,
1598 and AMD 29K architectures, the letter must be
1599 one of the letters @samp{DFPRSX} (in upper or lower case).
1601 On the Intel 960 architecture, the letter must be
1602 one of the letters @samp{DFT} (in upper or lower case).
1604 On the HPPA architecture, the letter must be @samp{E} (upper case only).
1608 One of the letters @samp{DFPRSX} (in upper or lower case).
1611 One of the letters @samp{DFPRSX} (in upper or lower case).
1614 One of the letters @samp{DFT} (in upper or lower case).
1617 The letter @samp{E} (upper case only).
1622 An optional sign: either @samp{+} or @samp{-}.
1625 An optional @dfn{integer part}: zero or more decimal digits.
1628 An optional @dfn{fractional part}: @samp{.} followed by zero
1629 or more decimal digits.
1632 An optional exponent, consisting of:
1636 An @samp{E} or @samp{e}.
1637 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1638 @c principle this can perfectly well be different on different targets.
1640 Optional sign: either @samp{+} or @samp{-}.
1642 One or more decimal digits.
1647 At least one of the integer part or the fractional part must be
1648 present. The floating point number has the usual base-10 value.
1650 @code{@value{AS}} does all processing using integers. Flonums are computed
1651 independently of any floating point hardware in the computer running
1656 @c Bit fields are written as a general facility but are also controlled
1657 @c by a conditional-compilation flag---which is as of now (21mar91)
1658 @c turned on only by the i960 config of GAS.
1660 @subsubsection Bit Fields
1663 @cindex constants, bit field
1664 You can also define numeric constants as @dfn{bit fields}.
1665 specify two numbers separated by a colon---
1667 @var{mask}:@var{value}
1670 @code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
1673 The resulting number is then packed
1675 @c this conditional paren in case bit fields turned on elsewhere than 960
1676 (in host-dependent byte order)
1678 into a field whose width depends on which assembler directive has the
1679 bit-field as its argument. Overflow (a result from the bitwise and
1680 requiring more binary digits to represent) is not an error; instead,
1681 more constants are generated, of the specified width, beginning with the
1682 least significant digits.@refill
1684 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1685 @code{.short}, and @code{.word} accept bit-field arguments.
1690 @chapter Sections and Relocation
1695 * Secs Background:: Background
1696 * Ld Sections:: @value{LD} Sections
1697 * As Sections:: @value{AS} Internal Sections
1698 * Sub-Sections:: Sub-Sections
1702 @node Secs Background
1705 Roughly, a section is a range of addresses, with no gaps; all data
1706 ``in'' those addresses is treated the same for some particular purpose.
1707 For example there may be a ``read only'' section.
1709 @cindex linker, and assembler
1710 @cindex assembler, and linker
1711 The linker @code{@value{LD}} reads many object files (partial programs) and
1712 combines their contents to form a runnable program. When @code{@value{AS}}
1713 emits an object file, the partial program is assumed to start at address 0.
1714 @code{@value{LD}} assigns the final addresses for the partial program, so that
1715 different partial programs do not overlap. This is actually an
1716 oversimplification, but it suffices to explain how @code{@value{AS}} uses
1719 @code{@value{LD}} moves blocks of bytes of your program to their run-time
1720 addresses. These blocks slide to their run-time addresses as rigid
1721 units; their length does not change and neither does the order of bytes
1722 within them. Such a rigid unit is called a @emph{section}. Assigning
1723 run-time addresses to sections is called @dfn{relocation}. It includes
1724 the task of adjusting mentions of object-file addresses so they refer to
1725 the proper run-time addresses.
1727 For the H8/300 and H8/500,
1728 and for the Hitachi SH,
1729 @code{@value{AS}} pads sections if needed to
1730 ensure they end on a word (sixteen bit) boundary.
1733 @cindex standard @code{@value{AS}} sections
1734 An object file written by @code{@value{AS}} has at least three sections, any
1735 of which may be empty. These are named @dfn{text}, @dfn{data} and
1740 When it generates COFF output,
1742 @code{@value{AS}} can also generate whatever other named sections you specify
1743 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1744 If you do not use any directives that place output in the @samp{.text}
1745 or @samp{.data} sections, these sections still exist, but are empty.
1750 When @code{@value{AS}} generates SOM or ELF output for the HPPA,
1752 @code{@value{AS}} can also generate whatever other named sections you
1753 specify using the @samp{.space} and @samp{.subspace} directives. See
1754 @cite{HP9000 Series 800 Assembly Language Reference Manual}
1755 (HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
1756 assembler directives.
1759 Additionally, @code{@value{AS}} uses different names for the standard
1760 text, data, and bss sections when generating SOM output. Program text
1761 is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
1762 BSS into @samp{$BSS$}.
1766 Within the object file, the text section starts at address @code{0}, the
1767 data section follows, and the bss section follows the data section.
1770 When generating either SOM or ELF output files on the HPPA, the text
1771 section starts at address @code{0}, the data section at address
1772 @code{0x4000000}, and the bss section follows the data section.
1775 To let @code{@value{LD}} know which data changes when the sections are
1776 relocated, and how to change that data, @code{@value{AS}} also writes to the
1777 object file details of the relocation needed. To perform relocation
1778 @code{@value{LD}} must know, each time an address in the object
1782 Where in the object file is the beginning of this reference to
1785 How long (in bytes) is this reference?
1787 Which section does the address refer to? What is the numeric value of
1789 (@var{address}) @minus{} (@var{start-address of section})?
1792 Is the reference to an address ``Program-Counter relative''?
1795 @cindex addresses, format of
1796 @cindex section-relative addressing
1797 In fact, every address @code{@value{AS}} ever uses is expressed as
1799 (@var{section}) + (@var{offset into section})
1802 Further, most expressions @code{@value{AS}} computes have this section-relative
1805 (For some object formats, such as SOM for the HPPA, some expressions are
1806 symbol-relative instead.)
1809 In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset
1810 @var{N} into section @var{secname}.''
1812 Apart from text, data and bss sections you need to know about the
1813 @dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
1814 addresses in the absolute section remain unchanged. For example, address
1815 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
1816 @code{@value{LD}}. Although the linker never arranges two partial programs'
1817 data sections with overlapping addresses after linking, @emph{by definition}
1818 their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one
1819 part of a program is always the same address when the program is running as
1820 address @code{@{absolute@ 239@}} in any other part of the program.
1822 The idea of sections is extended to the @dfn{undefined} section. Any
1823 address whose section is unknown at assembly time is by definition
1824 rendered @{undefined @var{U}@}---where @var{U} is filled in later.
1825 Since numbers are always defined, the only way to generate an undefined
1826 address is to mention an undefined symbol. A reference to a named
1827 common block would be such a symbol: its value is unknown at assembly
1828 time so it has section @emph{undefined}.
1830 By analogy the word @emph{section} is used to describe groups of sections in
1831 the linked program. @code{@value{LD}} puts all partial programs' text
1832 sections in contiguous addresses in the linked program. It is
1833 customary to refer to the @emph{text section} of a program, meaning all
1834 the addresses of all partial programs' text sections. Likewise for
1835 data and bss sections.
1837 Some sections are manipulated by @code{@value{LD}}; others are invented for
1838 use of @code{@value{AS}} and have no meaning except during assembly.
1841 @section @value{LD} Sections
1842 @code{@value{LD}} deals with just four kinds of sections, summarized below.
1847 @cindex named sections
1848 @cindex sections, named
1849 @item named sections
1852 @cindex text section
1853 @cindex data section
1857 These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as
1858 separate but equal sections. Anything you can say of one section is
1861 When the program is running, however, it is
1862 customary for the text section to be unalterable. The
1863 text section is often shared among processes: it contains
1864 instructions, constants and the like. The data section of a running
1865 program is usually alterable: for example, C variables would be stored
1866 in the data section.
1871 This section contains zeroed bytes when your program begins running. It
1872 is used to hold unitialized variables or common storage. The length of
1873 each partial program's bss section is important, but because it starts
1874 out containing zeroed bytes there is no need to store explicit zero
1875 bytes in the object file. The bss section was invented to eliminate
1876 those explicit zeros from object files.
1878 @cindex absolute section
1879 @item absolute section
1880 Address 0 of this section is always ``relocated'' to runtime address 0.
1881 This is useful if you want to refer to an address that @code{@value{LD}} must
1882 not change when relocating. In this sense we speak of absolute
1883 addresses being ``unrelocatable'': they do not change during relocation.
1885 @cindex undefined section
1886 @item undefined section
1887 This ``section'' is a catch-all for address references to objects not in
1888 the preceding sections.
1889 @c FIXME: ref to some other doc on obj-file formats could go here.
1892 @cindex relocation example
1893 An idealized example of three relocatable sections follows.
1895 The example uses the traditional section names @samp{.text} and @samp{.data}.
1897 Memory addresses are on the horizontal axis.
1901 @c END TEXI2ROFF-KILL
1904 partial program # 1: |ttttt|dddd|00|
1911 partial program # 2: |TTT|DDD|000|
1914 +--+---+-----+--+----+---+-----+~~
1915 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1916 +--+---+-----+--+----+---+-----+~~
1918 addresses: 0 @dots{}
1925 \line{\it Partial program \#1: \hfil}
1926 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1927 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1929 \line{\it Partial program \#2: \hfil}
1930 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1931 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1933 \line{\it linked program: \hfil}
1934 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1935 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1936 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1937 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1939 \line{\it addresses: \hfil}
1943 @c END TEXI2ROFF-KILL
1946 @section @value{AS} Internal Sections
1948 @cindex internal @code{@value{AS}} sections
1949 @cindex sections in messages, internal
1950 These sections are meant only for the internal use of @code{@value{AS}}. They
1951 have no meaning at run-time. You do not really need to know about these
1952 sections for most purposes; but they can be mentioned in @code{@value{AS}}
1953 warning messages, so it might be helpful to have an idea of their
1954 meanings to @code{@value{AS}}. These sections are used to permit the
1955 value of every expression in your assembly language program to be a
1956 section-relative address.
1959 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
1960 @cindex assembler internal logic error
1961 An internal assembler logic error has been found. This means there is a
1962 bug in the assembler.
1965 @cindex expr (internal section)
1966 The assembler stores complex expression internally as combinations of
1967 symbols. When it needs to represent an expression as a symbol, it puts
1968 it in the expr section.
1970 @c FIXME item transfer[t] vector preload
1971 @c FIXME item transfer[t] vector postload
1972 @c FIXME item register
1976 @section Sub-Sections
1978 @cindex numbered subsections
1979 @cindex grouping data
1985 fall into two sections: text and data.
1987 You may have separate groups of
1989 data in named sections
1993 data in named sections
1999 that you want to end up near to each other in the object file, even though they
2000 are not contiguous in the assembler source. @code{@value{AS}} allows you to
2001 use @dfn{subsections} for this purpose. Within each section, there can be
2002 numbered subsections with values from 0 to 8192. Objects assembled into the
2003 same subsection go into the object file together with other objects in the same
2004 subsection. For example, a compiler might want to store constants in the text
2005 section, but might not want to have them interspersed with the program being
2006 assembled. In this case, the compiler could issue a @samp{.text 0} before each
2007 section of code being output, and a @samp{.text 1} before each group of
2008 constants being output.
2010 Subsections are optional. If you do not use subsections, everything
2011 goes in subsection number zero.
2014 Each subsection is zero-padded up to a multiple of four bytes.
2015 (Subsections may be padded a different amount on different flavors
2016 of @code{@value{AS}}.)
2020 On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
2021 boundary (two bytes).
2022 The same is true on the Hitachi SH.
2025 @c FIXME section padding (alignment)?
2026 @c Rich Pixley says padding here depends on target obj code format; that
2027 @c doesn't seem particularly useful to say without further elaboration,
2028 @c so for now I say nothing about it. If this is a generic BFD issue,
2029 @c these paragraphs might need to vanish from this manual, and be
2030 @c discussed in BFD chapter of binutils (or some such).
2033 On the AMD 29K family, no particular padding is added to section or
2034 subsection sizes; @value{AS} forces no alignment on this platform.
2038 Subsections appear in your object file in numeric order, lowest numbered
2039 to highest. (All this to be compatible with other people's assemblers.)
2040 The object file contains no representation of subsections; @code{@value{LD}} and
2041 other programs that manipulate object files see no trace of them.
2042 They just see all your text subsections as a text section, and all your
2043 data subsections as a data section.
2045 To specify which subsection you want subsequent statements assembled
2046 into, use a numeric argument to specify it, in a @samp{.text
2047 @var{expression}} or a @samp{.data @var{expression}} statement.
2050 When generating COFF output, you
2055 can also use an extra subsection
2056 argument with arbitrary named sections: @samp{.section @var{name},
2059 @var{Expression} should be an absolute expression.
2060 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
2061 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
2062 begins in @code{text 0}. For instance:
2064 .text 0 # The default subsection is text 0 anyway.
2065 .ascii "This lives in the first text subsection. *"
2067 .ascii "But this lives in the second text subsection."
2069 .ascii "This lives in the data section,"
2070 .ascii "in the first data subsection."
2072 .ascii "This lives in the first text section,"
2073 .ascii "immediately following the asterisk (*)."
2076 Each section has a @dfn{location counter} incremented by one for every byte
2077 assembled into that section. Because subsections are merely a convenience
2078 restricted to @code{@value{AS}} there is no concept of a subsection location
2079 counter. There is no way to directly manipulate a location counter---but the
2080 @code{.align} directive changes it, and any label definition captures its
2081 current value. The location counter of the section where statements are being
2082 assembled is said to be the @dfn{active} location counter.
2085 @section bss Section
2088 @cindex common variable storage
2089 The bss section is used for local common variable storage.
2090 You may allocate address space in the bss section, but you may
2091 not dictate data to load into it before your program executes. When
2092 your program starts running, all the contents of the bss
2093 section are zeroed bytes.
2095 Addresses in the bss section are allocated with special directives; you
2096 may not assemble anything directly into the bss section. Hence there
2097 are no bss subsections. @xref{Comm,,@code{.comm}},
2098 @pxref{Lcomm,,@code{.lcomm}}.
2104 Symbols are a central concept: the programmer uses symbols to name
2105 things, the linker uses symbols to link, and the debugger uses symbols
2109 @cindex debuggers, and symbol order
2110 @emph{Warning:} @code{@value{AS}} does not place symbols in the object file in
2111 the same order they were declared. This may break some debuggers.
2116 * Setting Symbols:: Giving Symbols Other Values
2117 * Symbol Names:: Symbol Names
2118 * Dot:: The Special Dot Symbol
2119 * Symbol Attributes:: Symbol Attributes
2126 A @dfn{label} is written as a symbol immediately followed by a colon
2127 @samp{:}. The symbol then represents the current value of the
2128 active location counter, and is, for example, a suitable instruction
2129 operand. You are warned if you use the same symbol to represent two
2130 different locations: the first definition overrides any other
2134 On the HPPA, the usual form for a label need not be immediately followed by a
2135 colon, but instead must start in column zero. Only one label may be defined on
2136 a single line. To work around this, the HPPA version of @code{@value{AS}} also
2137 provides a special directive @code{.label} for defining labels more flexibly.
2140 @node Setting Symbols
2141 @section Giving Symbols Other Values
2143 @cindex assigning values to symbols
2144 @cindex symbol values, assigning
2145 A symbol can be given an arbitrary value by writing a symbol, followed
2146 by an equals sign @samp{=}, followed by an expression
2147 (@pxref{Expressions}). This is equivalent to using the @code{.set}
2148 directive. @xref{Set,,@code{.set}}.
2151 @section Symbol Names
2153 @cindex symbol names
2154 @cindex names, symbol
2155 @ifclear SPECIAL-SYMS
2156 Symbol names begin with a letter or with one of @samp{._}. On most
2157 machines, you can also use @code{$} in symbol names; exceptions are
2158 noted in @ref{Machine Dependencies}. That character may be followed by any
2159 string of digits, letters, dollar signs (unless otherwise noted in
2160 @ref{Machine Dependencies}), and underscores.
2163 For the AMD 29K family, @samp{?} is also allowed in the
2164 body of a symbol name, though not at its beginning.
2169 Symbol names begin with a letter or with one of @samp{._}. On the
2171 H8/500, you can also use @code{$} in symbol names. That character may
2172 be followed by any string of digits, letters, dollar signs (save on the
2173 H8/300), and underscores.
2177 Case of letters is significant: @code{foo} is a different symbol name
2180 Each symbol has exactly one name. Each name in an assembly language program
2181 refers to exactly one symbol. You may use that symbol name any number of times
2184 @subheading Local Symbol Names
2186 @cindex local symbol names
2187 @cindex symbol names, local
2188 @cindex temporary symbol names
2189 @cindex symbol names, temporary
2190 Local symbols help compilers and programmers use names temporarily.
2191 There are ten local symbol names, which are re-used throughout the
2192 program. You may refer to them using the names @samp{0} @samp{1}
2193 @dots{} @samp{9}. To define a local symbol, write a label of the form
2194 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
2195 recent previous definition of that symbol write @samp{@b{N}b}, using the
2196 same digit as when you defined the label. To refer to the next
2197 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
2198 a choice of 10 forward references. The @samp{b} stands for
2199 ``backwards'' and the @samp{f} stands for ``forwards''.
2201 Local symbols are not emitted by the current @sc{gnu} C compiler.
2203 There is no restriction on how you can use these labels, but
2204 remember that at any point in the assembly you can refer to at most
2205 10 prior local labels and to at most 10 forward local labels.
2207 Local symbol names are only a notation device. They are immediately
2208 transformed into more conventional symbol names before the assembler
2209 uses them. The symbol names stored in the symbol table, appearing in
2210 error messages and optionally emitted to the object file have these
2215 All local labels begin with @samp{L}. Normally both @code{@value{AS}} and
2216 @code{@value{LD}} forget symbols that start with @samp{L}. These labels are
2217 used for symbols you are never intended to see. If you use the
2218 @samp{-L} option then @code{@value{AS}} retains these symbols in the
2219 object file. If you also instruct @code{@value{LD}} to retain these symbols,
2220 you may use them in debugging.
2223 If the label is written @samp{0:} then the digit is @samp{0}.
2224 If the label is written @samp{1:} then the digit is @samp{1}.
2225 And so on up through @samp{9:}.
2228 This unusual character is included so you do not accidentally invent
2229 a symbol of the same name. The character has ASCII value
2232 @item @emph{ordinal number}
2233 This is a serial number to keep the labels distinct. The first
2234 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
2235 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
2239 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
2240 @code{3:} is named @code{L3@ctrl{A}44}.
2243 @section The Special Dot Symbol
2245 @cindex dot (symbol)
2246 @cindex @code{.} (symbol)
2247 @cindex current address
2248 @cindex location counter
2249 The special symbol @samp{.} refers to the current address that
2250 @code{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
2251 .long .} defines @code{melvin} to contain its own address.
2252 Assigning a value to @code{.} is treated the same as a @code{.org}
2253 directive. Thus, the expression @samp{.=.+4} is the same as saying
2254 @ifclear no-space-dir
2263 @node Symbol Attributes
2264 @section Symbol Attributes
2266 @cindex symbol attributes
2267 @cindex attributes, symbol
2268 Every symbol has, as well as its name, the attributes ``Value'' and
2269 ``Type''. Depending on output format, symbols can also have auxiliary
2272 The detailed definitions are in @file{a.out.h}.
2275 If you use a symbol without defining it, @code{@value{AS}} assumes zero for
2276 all these attributes, and probably won't warn you. This makes the
2277 symbol an externally defined symbol, which is generally what you
2281 * Symbol Value:: Value
2282 * Symbol Type:: Type
2285 * a.out Symbols:: Symbol Attributes: @code{a.out}
2289 * a.out Symbols:: Symbol Attributes: @code{a.out}
2292 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
2297 * COFF Symbols:: Symbol Attributes for COFF
2300 * SOM Symbols:: Symbol Attributes for SOM
2307 @cindex value of a symbol
2308 @cindex symbol value
2309 The value of a symbol is (usually) 32 bits. For a symbol which labels a
2310 location in the text, data, bss or absolute sections the value is the
2311 number of addresses from the start of that section to the label.
2312 Naturally for text, data and bss sections the value of a symbol changes
2313 as @code{@value{LD}} changes section base addresses during linking. Absolute
2314 symbols' values do not change during linking: that is why they are
2317 The value of an undefined symbol is treated in a special way. If it is
2318 0 then the symbol is not defined in this assembler source file, and
2319 @code{@value{LD}} tries to determine its value from other files linked into the
2320 same program. You make this kind of symbol simply by mentioning a symbol
2321 name without defining it. A non-zero value represents a @code{.comm}
2322 common declaration. The value is how much common storage to reserve, in
2323 bytes (addresses). The symbol refers to the first address of the
2329 @cindex type of a symbol
2331 The type attribute of a symbol contains relocation (section)
2332 information, any flag settings indicating that a symbol is external, and
2333 (optionally), other information for linkers and debuggers. The exact
2334 format depends on the object-code output format in use.
2339 @c The following avoids a "widow" subsection title. @group would be
2340 @c better if it were available outside examples.
2343 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
2345 @cindex @code{b.out} symbol attributes
2346 @cindex symbol attributes, @code{b.out}
2347 These symbol attributes appear only when @code{@value{AS}} is configured for
2348 one of the Berkeley-descended object output formats---@code{a.out} or
2354 @subsection Symbol Attributes: @code{a.out}
2356 @cindex @code{a.out} symbol attributes
2357 @cindex symbol attributes, @code{a.out}
2363 @subsection Symbol Attributes: @code{a.out}
2365 @cindex @code{a.out} symbol attributes
2366 @cindex symbol attributes, @code{a.out}
2370 * Symbol Desc:: Descriptor
2371 * Symbol Other:: Other
2375 @subsubsection Descriptor
2377 @cindex descriptor, of @code{a.out} symbol
2378 This is an arbitrary 16-bit value. You may establish a symbol's
2379 descriptor value by using a @code{.desc} statement
2380 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
2384 @subsubsection Other
2386 @cindex other attribute, of @code{a.out} symbol
2387 This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}.
2392 @subsection Symbol Attributes for COFF
2394 @cindex COFF symbol attributes
2395 @cindex symbol attributes, COFF
2397 The COFF format supports a multitude of auxiliary symbol attributes;
2398 like the primary symbol attributes, they are set between @code{.def} and
2399 @code{.endef} directives.
2401 @subsubsection Primary Attributes
2403 @cindex primary attributes, COFF symbols
2404 The symbol name is set with @code{.def}; the value and type,
2405 respectively, with @code{.val} and @code{.type}.
2407 @subsubsection Auxiliary Attributes
2409 @cindex auxiliary attributes, COFF symbols
2410 The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
2411 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2412 information for COFF.
2417 @subsection Symbol Attributes for SOM
2419 @cindex SOM symbol attributes
2420 @cindex symbol attributes, SOM
2422 The SOM format for the HPPA supports a multitude of symbol attributes set with
2423 the @code{.EXPORT} and @code{.IMPORT} directives.
2425 The attributes are described in @cite{HP9000 Series 800 Assembly
2426 Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
2427 @code{EXPORT} assembler directive documentation.
2431 @chapter Expressions
2435 @cindex numeric values
2436 An @dfn{expression} specifies an address or numeric value.
2437 Whitespace may precede and/or follow an expression.
2439 The result of an expression must be an absolute number, or else an offset into
2440 a particular section. If an expression is not absolute, and there is not
2441 enough information when @code{@value{AS}} sees the expression to know its
2442 section, a second pass over the source program might be necessary to interpret
2443 the expression---but the second pass is currently not implemented.
2444 @code{@value{AS}} aborts with an error message in this situation.
2447 * Empty Exprs:: Empty Expressions
2448 * Integer Exprs:: Integer Expressions
2452 @section Empty Expressions
2454 @cindex empty expressions
2455 @cindex expressions, empty
2456 An empty expression has no value: it is just whitespace or null.
2457 Wherever an absolute expression is required, you may omit the
2458 expression, and @code{@value{AS}} assumes a value of (absolute) 0. This
2459 is compatible with other assemblers.
2462 @section Integer Expressions
2464 @cindex integer expressions
2465 @cindex expressions, integer
2466 An @dfn{integer expression} is one or more @emph{arguments} delimited
2467 by @emph{operators}.
2470 * Arguments:: Arguments
2471 * Operators:: Operators
2472 * Prefix Ops:: Prefix Operators
2473 * Infix Ops:: Infix Operators
2477 @subsection Arguments
2479 @cindex expression arguments
2480 @cindex arguments in expressions
2481 @cindex operands in expressions
2482 @cindex arithmetic operands
2483 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2484 contexts arguments are sometimes called ``arithmetic operands''. In
2485 this manual, to avoid confusing them with the ``instruction operands'' of
2486 the machine language, we use the term ``argument'' to refer to parts of
2487 expressions only, reserving the word ``operand'' to refer only to machine
2488 instruction operands.
2490 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2491 @var{section} is one of text, data, bss, absolute,
2492 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2495 Numbers are usually integers.
2497 A number can be a flonum or bignum. In this case, you are warned
2498 that only the low order 32 bits are used, and @code{@value{AS}} pretends
2499 these 32 bits are an integer. You may write integer-manipulating
2500 instructions that act on exotic constants, compatible with other
2503 @cindex subexpressions
2504 Subexpressions are a left parenthesis @samp{(} followed by an integer
2505 expression, followed by a right parenthesis @samp{)}; or a prefix
2506 operator followed by an argument.
2509 @subsection Operators
2511 @cindex operators, in expressions
2512 @cindex arithmetic functions
2513 @cindex functions, in expressions
2514 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2515 operators are followed by an argument. Infix operators appear
2516 between their arguments. Operators may be preceded and/or followed by
2520 @subsection Prefix Operator
2522 @cindex prefix operators
2523 @code{@value{AS}} has the following @dfn{prefix operators}. They each take
2524 one argument, which must be absolute.
2526 @c the tex/end tex stuff surrounding this small table is meant to make
2527 @c it align, on the printed page, with the similar table in the next
2528 @c section (which is inside an enumerate).
2530 \global\advance\leftskip by \itemindent
2535 @dfn{Negation}. Two's complement negation.
2537 @dfn{Complementation}. Bitwise not.
2541 \global\advance\leftskip by -\itemindent
2545 @subsection Infix Operators
2547 @cindex infix operators
2548 @cindex operators, permitted arguments
2549 @dfn{Infix operators} take two arguments, one on either side. Operators
2550 have precedence, but operations with equal precedence are performed left
2551 to right. Apart from @code{+} or @code{-}, both arguments must be
2552 absolute, and the result is absolute.
2555 @cindex operator precedence
2556 @cindex precedence of operators
2563 @dfn{Multiplication}.
2566 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2573 @dfn{Shift Left}. Same as the C operator @samp{<<}.
2577 @dfn{Shift Right}. Same as the C operator @samp{>>}.
2581 Intermediate precedence
2586 @dfn{Bitwise Inclusive Or}.
2592 @dfn{Bitwise Exclusive Or}.
2595 @dfn{Bitwise Or Not}.
2603 @cindex addition, permitted arguments
2604 @cindex plus, permitted arguments
2605 @cindex arguments for addition
2606 @dfn{Addition}. If either argument is absolute, the result has the section of
2607 the other argument. You may not add together arguments from different
2611 @cindex subtraction, permitted arguments
2612 @cindex minus, permitted arguments
2613 @cindex arguments for subtraction
2614 @dfn{Subtraction}. If the right argument is absolute, the
2615 result has the section of the left argument.
2616 If both arguments are in the same section, the result is absolute.
2617 You may not subtract arguments from different sections.
2618 @c FIXME is there still something useful to say about undefined - undefined ?
2622 In short, it's only meaningful to add or subtract the @emph{offsets} in an
2623 address; you can only have a defined section in one of the two arguments.
2626 @chapter Assembler Directives
2628 @cindex directives, machine independent
2629 @cindex pseudo-ops, machine independent
2630 @cindex machine independent directives
2631 All assembler directives have names that begin with a period (@samp{.}).
2632 The rest of the name is letters, usually in lower case.
2634 This chapter discusses directives that are available regardless of the
2635 target machine configuration for the @sc{gnu} assembler.
2637 Some machine configurations provide additional directives.
2638 @xref{Machine Dependencies}.
2641 @ifset machine-directives
2642 @xref{Machine Dependencies} for additional directives.
2647 * Abort:: @code{.abort}
2649 * ABORT:: @code{.ABORT}
2652 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2653 * App-File:: @code{.app-file @var{string}}
2654 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2655 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2656 * Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}}
2657 * Byte:: @code{.byte @var{expressions}}
2658 * Comm:: @code{.comm @var{symbol} , @var{length} }
2659 * Data:: @code{.data @var{subsection}}
2661 * Def:: @code{.def @var{name}}
2664 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2670 * Double:: @code{.double @var{flonums}}
2671 * Eject:: @code{.eject}
2672 * Else:: @code{.else}
2674 * Endef:: @code{.endef}
2677 * Endif:: @code{.endif}
2678 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2679 * Extern:: @code{.extern}
2680 @ifclear no-file-dir
2681 * File:: @code{.file @var{string}}
2684 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2685 * Float:: @code{.float @var{flonums}}
2686 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2687 * hword:: @code{.hword @var{expressions}}
2688 * Ident:: @code{.ident}
2689 * If:: @code{.if @var{absolute expression}}
2690 * Include:: @code{.include "@var{file}"}
2691 * Int:: @code{.int @var{expressions}}
2692 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2693 * Lflags:: @code{.lflags}
2694 @ifclear no-line-dir
2695 * Line:: @code{.line @var{line-number}}
2698 * Ln:: @code{.ln @var{line-number}}
2699 * List:: @code{.list}
2700 * Long:: @code{.long @var{expressions}}
2702 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2705 * Nolist:: @code{.nolist}
2706 * Octa:: @code{.octa @var{bignums}}
2707 * Org:: @code{.org @var{new-lc} , @var{fill}}
2708 * P2align:: @code{.p2align @var{abs-expr} , @var{abs-expr}}
2709 * Psize:: @code{.psize @var{lines}, @var{columns}}
2710 * Quad:: @code{.quad @var{bignums}}
2711 * Sbttl:: @code{.sbttl "@var{subheading}"}
2713 * Scl:: @code{.scl @var{class}}
2716 * Section:: @code{.section @var{name}, @var{subsection}}
2719 * Set:: @code{.set @var{symbol}, @var{expression}}
2720 * Short:: @code{.short @var{expressions}}
2721 * Single:: @code{.single @var{flonums}}
2723 * Size:: @code{.size}
2726 * Space:: @code{.space @var{size} , @var{fill}}
2728 * Stab:: @code{.stabd, .stabn, .stabs}
2731 * String:: @code{.string "@var{str}"}
2733 * Tag:: @code{.tag @var{structname}}
2736 * Text:: @code{.text @var{subsection}}
2737 * Title:: @code{.title "@var{heading}"}
2739 * Type:: @code{.type @var{int}}
2740 * Val:: @code{.val @var{addr}}
2743 * Word:: @code{.word @var{expressions}}
2744 * Deprecated:: Deprecated Directives
2748 @section @code{.abort}
2750 @cindex @code{abort} directive
2751 @cindex stopping the assembly
2752 This directive stops the assembly immediately. It is for
2753 compatibility with other assemblers. The original idea was that the
2754 assembly language source would be piped into the assembler. If the sender
2755 of the source quit, it could use this directive tells @code{@value{AS}} to
2756 quit also. One day @code{.abort} will not be supported.
2760 @section @code{.ABORT}
2762 @cindex @code{ABORT} directive
2763 When producing COFF output, @code{@value{AS}} accepts this directive as a
2764 synonym for @samp{.abort}.
2767 When producing @code{b.out} output, @code{@value{AS}} accepts this directive,
2773 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2775 @cindex padding the location counter
2776 @cindex @code{align} directive
2777 Pad the location counter (in the current subsection) to a particular
2778 storage boundary. The first expression (which must be absolute) is the
2779 alignment required, as described below.
2780 The second expression (also absolute) gives the value to be stored in
2781 the padding bytes. It (and the comma) may be omitted. If it is
2782 omitted, the padding bytes are zero.
2784 The way the required alignment is specified varies from system to system.
2785 For the a29k, HPPA, m86k, m88k, w65, sparc, and i386 using ELF format,
2786 the first expression is the
2787 alignment request in bytes. For example @samp{.align 8} advances
2788 the location counter until it is a multiple of 8. If the location counter
2789 is already a multiple of 8, no change is needed.
2791 For other systems, including the i386 using a.out format, it is the
2792 number of low-order zero bits the location counter must have after
2793 advancement. For example @samp{.align 3} advances the location
2794 counter until it a multiple of 8. If the location counter is already a
2795 multiple of 8, no change is needed.
2797 This inconsistency is due to the different behaviors of the various
2798 native assemblers for these systems which GAS must emulate.
2799 GAS also provides @code{.balign} and @code{.p2align} directives,
2800 described later, which have a consistent behavior across all
2801 architectures (but are specific to GAS).
2804 @section @code{.app-file @var{string}}
2806 @cindex logical file name
2807 @cindex file name, logical
2808 @cindex @code{app-file} directive
2810 @ifclear no-file-dir
2811 (which may also be spelled @samp{.file})
2813 tells @code{@value{AS}} that we are about to start a new
2814 logical file. @var{string} is the new file name. In general, the
2815 filename is recognized whether or not it is surrounded by quotes @samp{"};
2816 but if you wish to specify an empty file name is permitted,
2817 you must give the quotes--@code{""}. This statement may go away in
2818 future: it is only recognized to be compatible with old @code{@value{AS}}
2822 @section @code{.ascii "@var{string}"}@dots{}
2824 @cindex @code{ascii} directive
2825 @cindex string literals
2826 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2827 separated by commas. It assembles each string (with no automatic
2828 trailing zero byte) into consecutive addresses.
2831 @section @code{.asciz "@var{string}"}@dots{}
2833 @cindex @code{asciz} directive
2834 @cindex zero-terminated strings
2835 @cindex null-terminated strings
2836 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2837 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2840 @section @code{.balign @var{abs-expr} , @var{abs-expr}}
2842 @cindex padding the location counter given number of bytes
2843 @cindex @code{balign} directive
2844 Pad the location counter (in the current subsection) to a particular
2845 storage boundary. The first expression (which must be absolute) is the
2846 alignment request in bytes. For example @samp{.balign 8} advances
2847 the location counter until it is a multiple of 8. If the location counter
2848 is already a multiple of 8, no change is needed.
2850 The second expression (also absolute) gives the value to be stored in
2851 the padding bytes. It (and the comma) may be omitted. If it is
2852 omitted, the padding bytes are zero.
2855 @section @code{.byte @var{expressions}}
2857 @cindex @code{byte} directive
2858 @cindex integers, one byte
2859 @code{.byte} expects zero or more expressions, separated by commas.
2860 Each expression is assembled into the next byte.
2863 @section @code{.comm @var{symbol} , @var{length} }
2865 @cindex @code{comm} directive
2866 @cindex symbol, common
2867 @code{.comm} declares a named common area in the bss section. Normally
2868 @code{@value{LD}} reserves memory addresses for it during linking, so no partial
2869 program defines the location of the symbol. Use @code{.comm} to tell
2870 @code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}}
2871 allocates space for each @code{.comm} symbol that is at least as
2872 long as the longest @code{.comm} request in any of the partial programs
2873 linked. @var{length} is an absolute expression.
2876 The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
2877 @samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
2881 @section @code{.data @var{subsection}}
2883 @cindex @code{data} directive
2884 @code{.data} tells @code{@value{AS}} to assemble the following statements onto the
2885 end of the data subsection numbered @var{subsection} (which is an
2886 absolute expression). If @var{subsection} is omitted, it defaults
2891 @section @code{.def @var{name}}
2893 @cindex @code{def} directive
2894 @cindex COFF symbols, debugging
2895 @cindex debugging COFF symbols
2896 Begin defining debugging information for a symbol @var{name}; the
2897 definition extends until the @code{.endef} directive is encountered.
2900 This directive is only observed when @code{@value{AS}} is configured for COFF
2901 format output; when producing @code{b.out}, @samp{.def} is recognized,
2908 @section @code{.desc @var{symbol}, @var{abs-expression}}
2910 @cindex @code{desc} directive
2911 @cindex COFF symbol descriptor
2912 @cindex symbol descriptor, COFF
2913 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2914 to the low 16 bits of an absolute expression.
2917 The @samp{.desc} directive is not available when @code{@value{AS}} is
2918 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2919 object format. For the sake of compatibility, @code{@value{AS}} accepts
2920 it, but produces no output, when configured for COFF.
2926 @section @code{.dim}
2928 @cindex @code{dim} directive
2929 @cindex COFF auxiliary symbol information
2930 @cindex auxiliary symbol information, COFF
2931 This directive is generated by compilers to include auxiliary debugging
2932 information in the symbol table. It is only permitted inside
2933 @code{.def}/@code{.endef} pairs.
2936 @samp{.dim} is only meaningful when generating COFF format output; when
2937 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
2943 @section @code{.double @var{flonums}}
2945 @cindex @code{double} directive
2946 @cindex floating point numbers (double)
2947 @code{.double} expects zero or more flonums, separated by commas. It
2948 assembles floating point numbers.
2950 The exact kind of floating point numbers emitted depends on how
2951 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
2955 On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
2956 in @sc{ieee} format.
2961 @section @code{.eject}
2963 @cindex @code{eject} directive
2964 @cindex new page, in listings
2965 @cindex page, in listings
2966 @cindex listing control: new page
2967 Force a page break at this point, when generating assembly listings.
2970 @section @code{.else}
2972 @cindex @code{else} directive
2973 @code{.else} is part of the @code{@value{AS}} support for conditional
2974 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2975 of code to be assembled if the condition for the preceding @code{.if}
2979 @node End, Endef, Else, Pseudo Ops
2980 @section @code{.end}
2982 @cindex @code{end} directive
2983 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2984 meant to do something eventually (which is why it isn't documented here
2985 as "for compatibility with blah").
2990 @section @code{.endef}
2992 @cindex @code{endef} directive
2993 This directive flags the end of a symbol definition begun with
2997 @samp{.endef} is only meaningful when generating COFF format output; if
2998 @code{@value{AS}} is configured to generate @code{b.out}, it accepts this
2999 directive but ignores it.
3004 @section @code{.endif}
3006 @cindex @code{endif} directive
3007 @code{.endif} is part of the @code{@value{AS}} support for conditional assembly;
3008 it marks the end of a block of code that is only assembled
3009 conditionally. @xref{If,,@code{.if}}.
3012 @section @code{.equ @var{symbol}, @var{expression}}
3014 @cindex @code{equ} directive
3015 @cindex assigning values to symbols
3016 @cindex symbols, assigning values to
3017 This directive sets the value of @var{symbol} to @var{expression}.
3018 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
3021 The syntax for @code{equ} on the HPPA is
3022 @samp{@var{symbol} .equ @var{expression}}.
3026 @section @code{.extern}
3028 @cindex @code{extern} directive
3029 @code{.extern} is accepted in the source program---for compatibility
3030 with other assemblers---but it is ignored. @code{@value{AS}} treats
3031 all undefined symbols as external.
3033 @ifclear no-file-dir
3035 @section @code{.file @var{string}}
3037 @cindex @code{file} directive
3038 @cindex logical file name
3039 @cindex file name, logical
3040 @code{.file} (which may also be spelled @samp{.app-file}) tells
3041 @code{@value{AS}} that we are about to start a new logical file.
3042 @var{string} is the new file name. In general, the filename is
3043 recognized whether or not it is surrounded by quotes @samp{"}; but if
3044 you wish to specify an empty file name, you must give the
3045 quotes--@code{""}. This statement may go away in future: it is only
3046 recognized to be compatible with old @code{@value{AS}} programs.
3048 In some configurations of @code{@value{AS}}, @code{.file} has already been
3049 removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}.
3054 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
3056 @cindex @code{fill} directive
3057 @cindex writing patterns in memory
3058 @cindex patterns, writing in memory
3059 @var{result}, @var{size} and @var{value} are absolute expressions.
3060 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
3061 may be zero or more. @var{Size} may be zero or more, but if it is
3062 more than 8, then it is deemed to have the value 8, compatible with
3063 other people's assemblers. The contents of each @var{repeat} bytes
3064 is taken from an 8-byte number. The highest order 4 bytes are
3065 zero. The lowest order 4 bytes are @var{value} rendered in the
3066 byte-order of an integer on the computer @code{@value{AS}} is assembling for.
3067 Each @var{size} bytes in a repetition is taken from the lowest order
3068 @var{size} bytes of this number. Again, this bizarre behavior is
3069 compatible with other people's assemblers.
3071 @var{size} and @var{value} are optional.
3072 If the second comma and @var{value} are absent, @var{value} is
3073 assumed zero. If the first comma and following tokens are absent,
3074 @var{size} is assumed to be 1.
3077 @section @code{.float @var{flonums}}
3079 @cindex floating point numbers (single)
3080 @cindex @code{float} directive
3081 This directive assembles zero or more flonums, separated by commas. It
3082 has the same effect as @code{.single}.
3084 The exact kind of floating point numbers emitted depends on how
3085 @code{@value{AS}} is configured.
3086 @xref{Machine Dependencies}.
3090 On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
3091 in @sc{ieee} format.
3096 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
3098 @cindex @code{global} directive
3099 @cindex symbol, making visible to linker
3100 @code{.global} makes the symbol visible to @code{@value{LD}}. If you define
3101 @var{symbol} in your partial program, its value is made available to
3102 other partial programs that are linked with it. Otherwise,
3103 @var{symbol} takes its attributes from a symbol of the same name
3104 from another file linked into the same program.
3106 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
3107 compatibility with other assemblers.
3110 On the HPPA, @code{.global} is not always enough to make it accessible to other
3111 partial programs. You may need the HPPA-only @code{.EXPORT} directive as well.
3112 @xref{HPPA Directives,, HPPA Assembler Directives}.
3116 @section @code{.hword @var{expressions}}
3118 @cindex @code{hword} directive
3119 @cindex integers, 16-bit
3120 @cindex numbers, 16-bit
3121 @cindex sixteen bit integers
3122 This expects zero or more @var{expressions}, and emits
3123 a 16 bit number for each.
3126 This directive is a synonym for @samp{.short}; depending on the target
3127 architecture, it may also be a synonym for @samp{.word}.
3131 This directive is a synonym for @samp{.short}.
3134 This directive is a synonym for both @samp{.short} and @samp{.word}.
3139 @section @code{.ident}
3141 @cindex @code{ident} directive
3142 This directive is used by some assemblers to place tags in object files.
3143 @code{@value{AS}} simply accepts the directive for source-file
3144 compatibility with such assemblers, but does not actually emit anything
3148 @section @code{.if @var{absolute expression}}
3150 @cindex conditional assembly
3151 @cindex @code{if} directive
3152 @code{.if} marks the beginning of a section of code which is only
3153 considered part of the source program being assembled if the argument
3154 (which must be an @var{absolute expression}) is non-zero. The end of
3155 the conditional section of code must be marked by @code{.endif}
3156 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
3157 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
3159 The following variants of @code{.if} are also supported:
3161 @item .ifdef @var{symbol}
3162 @cindex @code{ifdef} directive
3163 Assembles the following section of code if the specified @var{symbol}
3168 @cindex @code{ifeqs} directive
3169 Not yet implemented.
3172 @item .ifndef @var{symbol}
3173 @itemx ifnotdef @var{symbol}
3174 @cindex @code{ifndef} directive
3175 @cindex @code{ifnotdef} directive
3176 Assembles the following section of code if the specified @var{symbol}
3177 has not been defined. Both spelling variants are equivalent.
3181 Not yet implemented.
3186 @section @code{.include "@var{file}"}
3188 @cindex @code{include} directive
3189 @cindex supporting files, including
3190 @cindex files, including
3191 This directive provides a way to include supporting files at specified
3192 points in your source program. The code from @var{file} is assembled as
3193 if it followed the point of the @code{.include}; when the end of the
3194 included file is reached, assembly of the original file continues. You
3195 can control the search paths used with the @samp{-I} command-line option
3196 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
3200 @section @code{.int @var{expressions}}
3202 @cindex @code{int} directive
3203 @cindex integers, 32-bit
3204 Expect zero or more @var{expressions}, of any section, separated by commas.
3205 For each expression, emit a number that, at run time, is the value of that
3206 expression. The byte order and bit size of the number depends on what kind
3207 of target the assembly is for.
3211 On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
3212 integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits
3218 @section @code{.lcomm @var{symbol} , @var{length}}
3220 @cindex @code{lcomm} directive
3221 @cindex local common symbols
3222 @cindex symbols, local common
3223 Reserve @var{length} (an absolute expression) bytes for a local common
3224 denoted by @var{symbol}. The section and value of @var{symbol} are
3225 those of the new local common. The addresses are allocated in the bss
3226 section, so that at run-time the bytes start off zeroed. @var{Symbol}
3227 is not declared global (@pxref{Global,,@code{.global}}), so is normally
3228 not visible to @code{@value{LD}}.
3231 The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
3232 @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
3236 @section @code{.lflags}
3238 @cindex @code{lflags} directive (ignored)
3239 @code{@value{AS}} accepts this directive, for compatibility with other
3240 assemblers, but ignores it.
3242 @ifclear no-line-dir
3244 @section @code{.line @var{line-number}}
3246 @cindex @code{line} directive
3250 @section @code{.ln @var{line-number}}
3252 @cindex @code{ln} directive
3254 @cindex logical line number
3256 Change the logical line number. @var{line-number} must be an absolute
3257 expression. The next line has that logical line number. Therefore any other
3258 statements on the current line (after a statement separator character) are
3259 reported as on logical line number @var{line-number} @minus{} 1. One day
3260 @code{@value{AS}} will no longer support this directive: it is recognized only
3261 for compatibility with existing assembler programs.
3265 @emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
3266 not available; use the synonym @code{.ln} in that context.
3271 @ifclear no-line-dir
3272 Even though this is a directive associated with the @code{a.out} or
3273 @code{b.out} object-code formats, @code{@value{AS}} still recognizes it
3274 when producing COFF output, and treats @samp{.line} as though it
3275 were the COFF @samp{.ln} @emph{if} it is found outside a
3276 @code{.def}/@code{.endef} pair.
3278 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
3279 used by compilers to generate auxiliary symbol information for
3284 @section @code{.ln @var{line-number}}
3286 @cindex @code{ln} directive
3287 @ifclear no-line-dir
3288 @samp{.ln} is a synonym for @samp{.line}.
3291 Tell @code{@value{AS}} to change the logical line number. @var{line-number}
3292 must be an absolute expression. The next line has that logical
3293 line number, so any other statements on the current line (after a
3294 statement separator character @code{;}) are reported as on logical
3295 line number @var{line-number} @minus{} 1.
3298 This directive is accepted, but ignored, when @code{@value{AS}} is
3299 configured for @code{b.out}; its effect is only associated with COFF
3305 @section @code{.list}
3307 @cindex @code{list} directive
3308 @cindex listing control, turning on
3309 Control (in conjunction with the @code{.nolist} directive) whether or
3310 not assembly listings are generated. These two directives maintain an
3311 internal counter (which is zero initially). @code{.list} increments the
3312 counter, and @code{.nolist} decrements it. Assembly listings are
3313 generated whenever the counter is greater than zero.
3315 By default, listings are disabled. When you enable them (with the
3316 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
3317 the initial value of the listing counter is one.
3320 @section @code{.long @var{expressions}}
3322 @cindex @code{long} directive
3323 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
3326 @c no one seems to know what this is for or whether this description is
3327 @c what it really ought to do
3329 @section @code{.lsym @var{symbol}, @var{expression}}
3331 @cindex @code{lsym} directive
3332 @cindex symbol, not referenced in assembly
3333 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
3334 the hash table, ensuring it cannot be referenced by name during the
3335 rest of the assembly. This sets the attributes of the symbol to be
3336 the same as the expression value:
3338 @var{other} = @var{descriptor} = 0
3339 @var{type} = @r{(section of @var{expression})}
3340 @var{value} = @var{expression}
3343 The new symbol is not flagged as external.
3347 @section @code{.nolist}
3349 @cindex @code{nolist} directive
3350 @cindex listing control, turning off
3351 Control (in conjunction with the @code{.list} directive) whether or
3352 not assembly listings are generated. These two directives maintain an
3353 internal counter (which is zero initially). @code{.list} increments the
3354 counter, and @code{.nolist} decrements it. Assembly listings are
3355 generated whenever the counter is greater than zero.
3358 @section @code{.octa @var{bignums}}
3360 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
3361 @cindex @code{octa} directive
3362 @cindex integer, 16-byte
3363 @cindex sixteen byte integer
3364 This directive expects zero or more bignums, separated by commas. For each
3365 bignum, it emits a 16-byte integer.
3367 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
3368 hence @emph{octa}-word for 16 bytes.
3371 @section @code{.org @var{new-lc} , @var{fill}}
3373 @cindex @code{org} directive
3374 @cindex location counter, advancing
3375 @cindex advancing location counter
3376 @cindex current address, advancing
3377 Advance the location counter of the current section to
3378 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3379 expression with the same section as the current subsection. That is,
3380 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3381 wrong section, the @code{.org} directive is ignored. To be compatible
3382 with former assemblers, if the section of @var{new-lc} is absolute,
3383 @code{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
3384 is the same as the current subsection.
3386 @code{.org} may only increase the location counter, or leave it
3387 unchanged; you cannot use @code{.org} to move the location counter
3390 @c double negative used below "not undefined" because this is a specific
3391 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3392 @c section. pesch@cygnus.com 18feb91
3393 Because @code{@value{AS}} tries to assemble programs in one pass, @var{new-lc}
3394 may not be undefined. If you really detest this restriction we eagerly await
3395 a chance to share your improved assembler.
3397 Beware that the origin is relative to the start of the section, not
3398 to the start of the subsection. This is compatible with other
3399 people's assemblers.
3401 When the location counter (of the current subsection) is advanced, the
3402 intervening bytes are filled with @var{fill} which should be an
3403 absolute expression. If the comma and @var{fill} are omitted,
3404 @var{fill} defaults to zero.
3407 @section @code{.p2align @var{abs-expr} , @var{abs-expr}}
3409 @cindex padding the location counter given a power of two
3410 @cindex @code{p2align} directive
3411 Pad the location counter (in the current subsection) to a particular
3412 storage boundary. The first expression (which must be absolute) is the
3413 number of low-order zero bits the location counter must have after
3414 advancement. For example @samp{.p2align 3} advances the location
3415 counter until it a multiple of 8. If the location counter is already a
3416 multiple of 8, no change is needed.
3418 The second expression (also absolute) gives the value to be stored in
3419 the padding bytes. It (and the comma) may be omitted. If it is
3420 omitted, the padding bytes are zero.
3423 @section @code{.psize @var{lines} , @var{columns}}
3425 @cindex @code{psize} directive
3426 @cindex listing control: paper size
3427 @cindex paper size, for listings
3428 Use this directive to declare the number of lines---and, optionally, the
3429 number of columns---to use for each page, when generating listings.
3431 If you do not use @code{.psize}, listings use a default line-count
3432 of 60. You may omit the comma and @var{columns} specification; the
3433 default width is 200 columns.
3435 @code{@value{AS}} generates formfeeds whenever the specified number of
3436 lines is exceeded (or whenever you explicitly request one, using
3439 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3440 those explicitly specified with @code{.eject}.
3443 @section @code{.quad @var{bignums}}
3445 @cindex @code{quad} directive
3446 @code{.quad} expects zero or more bignums, separated by commas. For
3447 each bignum, it emits
3449 an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
3450 warning message; and just takes the lowest order 8 bytes of the bignum.
3451 @cindex eight-byte integer
3452 @cindex integer, 8-byte
3454 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3455 hence @emph{quad}-word for 8 bytes.
3458 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3459 warning message; and just takes the lowest order 16 bytes of the bignum.
3460 @cindex sixteen-byte integer
3461 @cindex integer, 16-byte
3465 @section @code{.sbttl "@var{subheading}"}
3467 @cindex @code{sbttl} directive
3468 @cindex subtitles for listings
3469 @cindex listing control: subtitle
3470 Use @var{subheading} as the title (third line, immediately after the
3471 title line) when generating assembly listings.
3473 This directive affects subsequent pages, as well as the current page if
3474 it appears within ten lines of the top of a page.
3478 @section @code{.scl @var{class}}
3480 @cindex @code{scl} directive
3481 @cindex symbol storage class (COFF)
3482 @cindex COFF symbol storage class
3483 Set the storage-class value for a symbol. This directive may only be
3484 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3485 whether a symbol is static or external, or it may record further
3486 symbolic debugging information.
3489 The @samp{.scl} directive is primarily associated with COFF output; when
3490 configured to generate @code{b.out} output format, @code{@value{AS}}
3491 accepts this directive but ignores it.
3497 @section @code{.section @var{name}, @var{subsection}}
3499 @cindex @code{section} directive
3500 @cindex named section (COFF)
3501 @cindex COFF named section
3502 Assemble the following code into end of subsection numbered
3503 @var{subsection} in the COFF named section @var{name}. If you omit
3504 @var{subsection}, @code{@value{AS}} uses subsection number zero.
3505 @samp{.section .text} is equivalent to the @code{.text} directive;
3506 @samp{.section .data} is equivalent to the @code{.data} directive.
3508 This directive is only supported for targets that actually support arbitrarily
3509 named sections; on @code{a.out} targets, for example, it is not accepted, even
3510 with a standard @code{a.out} section name as its parameter.
3515 @section @code{.set @var{symbol}, @var{expression}}
3517 @cindex @code{set} directive
3518 @cindex symbol value, setting
3519 Set the value of @var{symbol} to @var{expression}. This
3520 changes @var{symbol}'s value and type to conform to
3521 @var{expression}. If @var{symbol} was flagged as external, it remains
3522 flagged. (@xref{Symbol Attributes}.)
3524 You may @code{.set} a symbol many times in the same assembly.
3526 If you @code{.set} a global symbol, the value stored in the object
3527 file is the last value stored into it.
3530 The syntax for @code{set} on the HPPA is
3531 @samp{@var{symbol} .set @var{expression}}.
3535 @section @code{.short @var{expressions}}
3537 @cindex @code{short} directive
3539 @code{.short} is normally the same as @samp{.word}.
3540 @xref{Word,,@code{.word}}.
3542 In some configurations, however, @code{.short} and @code{.word} generate
3543 numbers of different lengths; @pxref{Machine Dependencies}.
3547 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3550 This expects zero or more @var{expressions}, and emits
3551 a 16 bit number for each.
3556 @section @code{.single @var{flonums}}
3558 @cindex @code{single} directive
3559 @cindex floating point numbers (single)
3560 This directive assembles zero or more flonums, separated by commas. It
3561 has the same effect as @code{.float}.
3563 The exact kind of floating point numbers emitted depends on how
3564 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
3568 On the @value{TARGET} family, @code{.single} emits 32-bit floating point
3569 numbers in @sc{ieee} format.
3575 @section @code{.size}
3577 @cindex @code{size} directive
3578 This directive is generated by compilers to include auxiliary debugging
3579 information in the symbol table. It is only permitted inside
3580 @code{.def}/@code{.endef} pairs.
3583 @samp{.size} is only meaningful when generating COFF format output; when
3584 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3589 @ifclear no-space-dir
3591 @section @code{.space @var{size} , @var{fill}}
3593 @cindex @code{space} directive
3594 @cindex filling memory
3595 This directive emits @var{size} bytes, each of value @var{fill}. Both
3596 @var{size} and @var{fill} are absolute expressions. If the comma
3597 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3601 @emph{Warning:} @code{.space} has a completely different meaning for HPPA
3602 targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800
3603 Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the
3604 @code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives},
3613 @section @code{.space}
3614 @cindex @code{space} directive
3616 On the AMD 29K, this directive is ignored; it is accepted for
3617 compatibility with other AMD 29K assemblers.
3620 @emph{Warning:} In most versions of the @sc{gnu} assembler, the directive
3621 @code{.space} has the effect of @code{.block} @xref{Machine Dependencies}.
3627 @section @code{.stabd, .stabn, .stabs}
3629 @cindex symbolic debuggers, information for
3630 @cindex @code{stab@var{x}} directives
3631 There are three directives that begin @samp{.stab}.
3632 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3633 The symbols are not entered in the @code{@value{AS}} hash table: they
3634 cannot be referenced elsewhere in the source file.
3635 Up to five fields are required:
3639 This is the symbol's name. It may contain any character except
3640 @samp{\000}, so is more general than ordinary symbol names. Some
3641 debuggers used to code arbitrarily complex structures into symbol names
3645 An absolute expression. The symbol's type is set to the low 8 bits of
3646 this expression. Any bit pattern is permitted, but @code{@value{LD}}
3647 and debuggers choke on silly bit patterns.
3650 An absolute expression. The symbol's ``other'' attribute is set to the
3651 low 8 bits of this expression.
3654 An absolute expression. The symbol's descriptor is set to the low 16
3655 bits of this expression.
3658 An absolute expression which becomes the symbol's value.
3661 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3662 or @code{.stabs} statement, the symbol has probably already been created;
3663 you get a half-formed symbol in your object file. This is
3664 compatible with earlier assemblers!
3667 @cindex @code{stabd} directive
3668 @item .stabd @var{type} , @var{other} , @var{desc}
3670 The ``name'' of the symbol generated is not even an empty string.
3671 It is a null pointer, for compatibility. Older assemblers used a
3672 null pointer so they didn't waste space in object files with empty
3675 The symbol's value is set to the location counter,
3676 relocatably. When your program is linked, the value of this symbol
3677 is the address of the location counter when the @code{.stabd} was
3680 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3681 @cindex @code{stabn} directive
3682 The name of the symbol is set to the empty string @code{""}.
3684 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3685 @cindex @code{stabs} directive
3686 All five fields are specified.
3692 @section @code{.string} "@var{str}"
3694 @cindex string, copying to object file
3695 @cindex @code{string} directive
3697 Copy the characters in @var{str} to the object file. You may specify more than
3698 one string to copy, separated by commas. Unless otherwise specified for a
3699 particular machine, the assembler marks the end of each string with a 0 byte.
3700 You can use any of the escape sequences described in @ref{Strings,,Strings}.
3704 @section @code{.tag @var{structname}}
3706 @cindex COFF structure debugging
3707 @cindex structure debugging, COFF
3708 @cindex @code{tag} directive
3709 This directive is generated by compilers to include auxiliary debugging
3710 information in the symbol table. It is only permitted inside
3711 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3712 definitions in the symbol table with instances of those structures.
3715 @samp{.tag} is only used when generating COFF format output; when
3716 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3722 @section @code{.text @var{subsection}}
3724 @cindex @code{text} directive
3725 Tells @code{@value{AS}} to assemble the following statements onto the end of
3726 the text subsection numbered @var{subsection}, which is an absolute
3727 expression. If @var{subsection} is omitted, subsection number zero
3731 @section @code{.title "@var{heading}"}
3733 @cindex @code{title} directive
3734 @cindex listing control: title line
3735 Use @var{heading} as the title (second line, immediately after the
3736 source file name and pagenumber) when generating assembly listings.
3738 This directive affects subsequent pages, as well as the current page if
3739 it appears within ten lines of the top of a page.
3743 @section @code{.type @var{int}}
3745 @cindex COFF symbol type
3746 @cindex symbol type, COFF
3747 @cindex @code{type} directive
3748 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3749 records the integer @var{int} as the type attribute of a symbol table entry.
3752 @samp{.type} is associated only with COFF format output; when
3753 @code{@value{AS}} is configured for @code{b.out} output, it accepts this
3754 directive but ignores it.
3760 @section @code{.val @var{addr}}
3762 @cindex @code{val} directive
3763 @cindex COFF value attribute
3764 @cindex value attribute, COFF
3765 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3766 records the address @var{addr} as the value attribute of a symbol table
3770 @samp{.val} is used only for COFF output; when @code{@value{AS}} is
3771 configured for @code{b.out}, it accepts this directive but ignores it.
3776 @section @code{.word @var{expressions}}
3778 @cindex @code{word} directive
3779 This directive expects zero or more @var{expressions}, of any section,
3780 separated by commas.
3783 For each expression, @code{@value{AS}} emits a 32-bit number.
3786 For each expression, @code{@value{AS}} emits a 16-bit number.
3791 The size of the number emitted, and its byte order,
3792 depend on what target computer the assembly is for.
3795 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3796 @c happen---32-bit addressability, period; no long/short jumps.
3797 @ifset DIFF-TBL-KLUGE
3798 @cindex difference tables altered
3799 @cindex altered difference tables
3801 @emph{Warning: Special Treatment to support Compilers}
3805 Machines with a 32-bit address space, but that do less than 32-bit
3806 addressing, require the following special treatment. If the machine of
3807 interest to you does 32-bit addressing (or doesn't require it;
3808 @pxref{Machine Dependencies}), you can ignore this issue.
3811 In order to assemble compiler output into something that works,
3812 @code{@value{AS}} occasionlly does strange things to @samp{.word} directives.
3813 Directives of the form @samp{.word sym1-sym2} are often emitted by
3814 compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a
3815 directive of the form @samp{.word sym1-sym2}, and the difference between
3816 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}}
3817 creates a @dfn{secondary jump table}, immediately before the next label.
3818 This secondary jump table is preceded by a short-jump to the
3819 first byte after the secondary table. This short-jump prevents the flow
3820 of control from accidentally falling into the new table. Inside the
3821 table is a long-jump to @code{sym2}. The original @samp{.word}
3822 contains @code{sym1} minus the address of the long-jump to
3825 If there were several occurrences of @samp{.word sym1-sym2} before the
3826 secondary jump table, all of them are adjusted. If there was a
3827 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3828 long-jump to @code{sym4} is included in the secondary jump table,
3829 and the @code{.word} directives are adjusted to contain @code{sym3}
3830 minus the address of the long-jump to @code{sym4}; and so on, for as many
3831 entries in the original jump table as necessary.
3834 @emph{This feature may be disabled by compiling @code{@value{AS}} with the
3835 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3836 assembly language programmers.
3839 @c end DIFF-TBL-KLUGE
3842 @section Deprecated Directives
3844 @cindex deprecated directives
3845 @cindex obsolescent directives
3846 One day these directives won't work.
3847 They are included for compatibility with older assemblers.
3855 @node Machine Dependencies
3856 @chapter Machine Dependent Features
3858 @cindex machine dependencies
3859 The machine instruction sets are (almost by definition) different on
3860 each machine where @code{@value{AS}} runs. Floating point representations
3861 vary as well, and @code{@value{AS}} often supports a few additional
3862 directives or command-line options for compatibility with other
3863 assemblers on a particular platform. Finally, some versions of
3864 @code{@value{AS}} support special pseudo-instructions for branch
3867 This chapter discusses most of these differences, though it does not
3868 include details on any machine's instruction set. For details on that
3869 subject, see the hardware manufacturer's manual.
3873 * Vax-Dependent:: VAX Dependent Features
3876 * AMD29K-Dependent:: AMD 29K Dependent Features
3879 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
3882 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
3885 * HPPA-Dependent:: HPPA Dependent Features
3888 * SH-Dependent:: Hitachi SH Dependent Features
3891 * i960-Dependent:: Intel 80960 Dependent Features
3894 * M68K-Dependent:: M680x0 Dependent Features
3897 * Sparc-Dependent:: SPARC Dependent Features
3900 * Z8000-Dependent:: Z8000 Dependent Features
3903 * MIPS-Dependent:: MIPS Dependent Features
3906 * i386-Dependent:: 80386 Dependent Features
3913 @c The following major nodes are *sections* in the GENERIC version, *chapters*
3914 @c in single-cpu versions. This is mainly achieved by @lowersections. There is a
3915 @c peculiarity: to preserve cross-references, there must be a node called
3916 @c "Machine Dependencies". Hence the conditional nodenames in each
3917 @c major node below. Node defaulting in makeinfo requires adjacency of
3918 @c node and sectioning commands; hence the repetition of @chapter BLAH
3919 @c in both conditional blocks.
3924 @chapter VAX Dependent Features
3929 @node Machine Dependencies
3930 @chapter VAX Dependent Features
3936 * Vax-Opts:: VAX Command-Line Options
3937 * VAX-float:: VAX Floating Point
3938 * VAX-directives:: Vax Machine Directives
3939 * VAX-opcodes:: VAX Opcodes
3940 * VAX-branch:: VAX Branch Improvement
3941 * VAX-operands:: VAX Operands
3942 * VAX-no:: Not Supported on VAX
3947 @section VAX Command-Line Options
3949 @cindex command-line options ignored, VAX
3950 @cindex VAX command-line options ignored
3951 The Vax version of @code{@value{AS}} accepts any of the following options,
3952 gives a warning message that the option was ignored and proceeds.
3953 These options are for compatibility with scripts designed for other
3954 people's assemblers.
3957 @item @code{-D} (Debug)
3958 @itemx @code{-S} (Symbol Table)
3959 @itemx @code{-T} (Token Trace)
3960 @cindex @code{-D}, ignored on VAX
3961 @cindex @code{-S}, ignored on VAX
3962 @cindex @code{-T}, ignored on VAX
3963 These are obsolete options used to debug old assemblers.
3965 @item @code{-d} (Displacement size for JUMPs)
3966 @cindex @code{-d}, VAX option
3967 This option expects a number following the @samp{-d}. Like options
3968 that expect filenames, the number may immediately follow the
3969 @samp{-d} (old standard) or constitute the whole of the command line
3970 argument that follows @samp{-d} (@sc{gnu} standard).
3972 @item @code{-V} (Virtualize Interpass Temporary File)
3973 @cindex @code{-V}, redundant on VAX
3974 Some other assemblers use a temporary file. This option
3975 commanded them to keep the information in active memory rather
3976 than in a disk file. @code{@value{AS}} always does this, so this
3977 option is redundant.
3979 @item @code{-J} (JUMPify Longer Branches)
3980 @cindex @code{-J}, ignored on VAX
3981 Many 32-bit computers permit a variety of branch instructions
3982 to do the same job. Some of these instructions are short (and
3983 fast) but have a limited range; others are long (and slow) but
3984 can branch anywhere in virtual memory. Often there are 3
3985 flavors of branch: short, medium and long. Some other
3986 assemblers would emit short and medium branches, unless told by
3987 this option to emit short and long branches.
3989 @item @code{-t} (Temporary File Directory)
3990 @cindex @code{-t}, ignored on VAX
3991 Some other assemblers may use a temporary file, and this option
3992 takes a filename being the directory to site the temporary
3993 file. Since @code{@value{AS}} does not use a temporary disk file, this
3994 option makes no difference. @samp{-t} needs exactly one
3998 @cindex VMS (VAX) options
3999 @cindex options for VAX/VMS
4000 @cindex VAX/VMS options
4001 @cindex @code{-h} option, VAX/VMS
4002 @cindex @code{-+} option, VAX/VMS
4003 @cindex Vax-11 C compatibility
4004 @cindex symbols with lowercase, VAX/VMS
4005 @c FIXME! look into "I think" below, correct if needed, delete.
4006 The Vax version of the assembler accepts two options when
4007 compiled for VMS. They are @samp{-h}, and @samp{-+}. The
4008 @samp{-h} option prevents @code{@value{AS}} from modifying the
4009 symbol-table entries for symbols that contain lowercase
4010 characters (I think). The @samp{-+} option causes @code{@value{AS}} to
4011 print warning messages if the FILENAME part of the object file,
4012 or any symbol name is larger than 31 characters. The @samp{-+}
4013 option also inserts some code following the @samp{_main}
4014 symbol so that the object file is compatible with Vax-11
4018 @section VAX Floating Point
4020 @cindex VAX floating point
4021 @cindex floating point, VAX
4022 Conversion of flonums to floating point is correct, and
4023 compatible with previous assemblers. Rounding is
4024 towards zero if the remainder is exactly half the least significant bit.
4026 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
4029 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
4030 are rendered correctly. Again, rounding is towards zero in the
4033 @cindex @code{float} directive, VAX
4034 @cindex @code{double} directive, VAX
4035 The @code{.float} directive produces @code{f} format numbers.
4036 The @code{.double} directive produces @code{d} format numbers.
4038 @node VAX-directives
4039 @section Vax Machine Directives
4041 @cindex machine directives, VAX
4042 @cindex VAX machine directives
4043 The Vax version of the assembler supports four directives for
4044 generating Vax floating point constants. They are described in the
4047 @cindex wide floating point directives, VAX
4050 @cindex @code{dfloat} directive, VAX
4051 This expects zero or more flonums, separated by commas, and
4052 assembles Vax @code{d} format 64-bit floating point constants.
4055 @cindex @code{ffloat} directive, VAX
4056 This expects zero or more flonums, separated by commas, and
4057 assembles Vax @code{f} format 32-bit floating point constants.
4060 @cindex @code{gfloat} directive, VAX
4061 This expects zero or more flonums, separated by commas, and
4062 assembles Vax @code{g} format 64-bit floating point constants.
4065 @cindex @code{hfloat} directive, VAX
4066 This expects zero or more flonums, separated by commas, and
4067 assembles Vax @code{h} format 128-bit floating point constants.
4072 @section VAX Opcodes
4074 @cindex VAX opcode mnemonics
4075 @cindex opcode mnemonics, VAX
4076 @cindex mnemonics for opcodes, VAX
4077 All DEC mnemonics are supported. Beware that @code{case@dots{}}
4078 instructions have exactly 3 operands. The dispatch table that
4079 follows the @code{case@dots{}} instruction should be made with
4080 @code{.word} statements. This is compatible with all unix
4081 assemblers we know of.
4084 @section VAX Branch Improvement
4086 @cindex VAX branch improvement
4087 @cindex branch improvement, VAX
4088 @cindex pseudo-ops for branch, VAX
4089 Certain pseudo opcodes are permitted. They are for branch
4090 instructions. They expand to the shortest branch instruction that
4091 reaches the target. Generally these mnemonics are made by
4092 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
4093 This feature is included both for compatibility and to help
4094 compilers. If you do not need this feature, avoid these
4095 opcodes. Here are the mnemonics, and the code they can expand into.
4099 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
4101 @item (byte displacement)
4103 @item (word displacement)
4105 @item (long displacement)
4110 Unconditional branch.
4112 @item (byte displacement)
4114 @item (word displacement)
4116 @item (long displacement)
4120 @var{COND} may be any one of the conditional branches
4121 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
4122 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
4123 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
4124 @var{COND} may also be one of the bit tests
4125 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
4126 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
4127 @var{NOTCOND} is the opposite condition to @var{COND}.
4129 @item (byte displacement)
4130 @kbd{b@var{COND} @dots{}}
4131 @item (word displacement)
4132 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
4133 @item (long displacement)
4134 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
4137 @var{X} may be one of @code{b d f g h l w}.
4139 @item (word displacement)
4140 @kbd{@var{OPCODE} @dots{}}
4141 @item (long displacement)
4143 @var{OPCODE} @dots{}, foo ;
4150 @var{YYY} may be one of @code{lss leq}.
4152 @var{ZZZ} may be one of @code{geq gtr}.
4154 @item (byte displacement)
4155 @kbd{@var{OPCODE} @dots{}}
4156 @item (word displacement)
4158 @var{OPCODE} @dots{}, foo ;
4160 foo: brw @var{destination} ;
4163 @item (long displacement)
4165 @var{OPCODE} @dots{}, foo ;
4167 foo: jmp @var{destination} ;
4176 @item (byte displacement)
4177 @kbd{@var{OPCODE} @dots{}}
4178 @item (word displacement)
4180 @var{OPCODE} @dots{}, foo ;
4182 foo: brw @var{destination} ;
4185 @item (long displacement)
4187 @var{OPCODE} @dots{}, foo ;
4189 foo: jmp @var{destination} ;
4196 @section VAX Operands
4198 @cindex VAX operand notation
4199 @cindex operand notation, VAX
4200 @cindex immediate character, VAX
4201 @cindex VAX immediate character
4202 The immediate character is @samp{$} for Unix compatibility, not
4203 @samp{#} as DEC writes it.
4205 @cindex indirect character, VAX
4206 @cindex VAX indirect character
4207 The indirect character is @samp{*} for Unix compatibility, not
4208 @samp{@@} as DEC writes it.
4210 @cindex displacement sizing character, VAX
4211 @cindex VAX displacement sizing character
4212 The displacement sizing character is @samp{`} (an accent grave) for
4213 Unix compatibility, not @samp{^} as DEC writes it. The letter
4214 preceding @samp{`} may have either case. @samp{G} is not
4215 understood, but all other letters (@code{b i l s w}) are understood.
4217 @cindex register names, VAX
4218 @cindex VAX register names
4219 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
4220 pc}. Upper and lower case letters are equivalent.
4227 Any expression is permitted in an operand. Operands are comma
4230 @c There is some bug to do with recognizing expressions
4231 @c in operands, but I forget what it is. It is
4232 @c a syntax clash because () is used as an address mode
4233 @c and to encapsulate sub-expressions.
4236 @section Not Supported on VAX
4238 @cindex VAX bitfields not supported
4239 @cindex bitfields, not supported on VAX
4240 Vax bit fields can not be assembled with @code{@value{AS}}. Someone
4241 can add the required code if they really need it.
4247 @node AMD29K-Dependent
4248 @chapter AMD 29K Dependent Features
4251 @node Machine Dependencies
4252 @chapter AMD 29K Dependent Features
4255 @cindex AMD 29K support
4258 * AMD29K Options:: Options
4259 * AMD29K Syntax:: Syntax
4260 * AMD29K Floating Point:: Floating Point
4261 * AMD29K Directives:: AMD 29K Machine Directives
4262 * AMD29K Opcodes:: Opcodes
4265 @node AMD29K Options
4267 @cindex AMD 29K options (none)
4268 @cindex options for AMD29K (none)
4269 @code{@value{AS}} has no additional command-line options for the AMD
4275 * AMD29K-Chars:: Special Characters
4276 * AMD29K-Regs:: Register Names
4280 @subsection Special Characters
4282 @cindex line comment character, AMD 29K
4283 @cindex AMD 29K line comment character
4284 @samp{;} is the line comment character.
4286 @cindex line separator, AMD 29K
4287 @cindex AMD 29K line separator
4288 @cindex statement separator, AMD 29K
4289 @cindex AMD 29K statement separator
4290 @samp{@@} can be used instead of a newline to separate statements.
4292 @cindex identifiers, AMD 29K
4293 @cindex AMD 29K identifiers
4294 The character @samp{?} is permitted in identifiers (but may not begin
4298 @subsection Register Names
4300 @cindex AMD 29K register names
4301 @cindex register names, AMD 29K
4302 General-purpose registers are represented by predefined symbols of the
4303 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
4304 (for local registers), where @var{nnn} represents a number between
4305 @code{0} and @code{127}, written with no leading zeros. The leading
4306 letters may be in either upper or lower case; for example, @samp{gr13}
4307 and @samp{LR7} are both valid register names.
4309 You may also refer to general-purpose registers by specifying the
4310 register number as the result of an expression (prefixed with @samp{%%}
4311 to flag the expression as a register number):
4316 ---where @var{expression} must be an absolute expression evaluating to a
4317 number between @code{0} and @code{255}. The range [0, 127] refers to
4318 global registers, and the range [128, 255] to local registers.
4320 @cindex special purpose registers, AMD 29K
4321 @cindex AMD 29K special purpose registers
4322 @cindex protected registers, AMD 29K
4323 @cindex AMD 29K protected registers
4324 In addition, @code{@value{AS}} understands the following protected
4325 special-purpose register names for the AMD 29K family:
4335 These unprotected special-purpose register names are also recognized:
4343 @node AMD29K Floating Point
4344 @section Floating Point
4346 @cindex floating point, AMD 29K (@sc{ieee})
4347 @cindex AMD 29K floating point (@sc{ieee})
4348 The AMD 29K family uses @sc{ieee} floating-point numbers.
4350 @node AMD29K Directives
4351 @section AMD 29K Machine Directives
4353 @cindex machine directives, AMD 29K
4354 @cindex AMD 29K machine directives
4356 @item .block @var{size} , @var{fill}
4357 @cindex @code{block} directive, AMD 29K
4358 This directive emits @var{size} bytes, each of value @var{fill}. Both
4359 @var{size} and @var{fill} are absolute expressions. If the comma
4360 and @var{fill} are omitted, @var{fill} is assumed to be zero.
4362 In other versions of the @sc{gnu} assembler, this directive is called
4368 @cindex @code{cputype} directive, AMD 29K
4369 This directive is ignored; it is accepted for compatibility with other
4373 @cindex @code{file} directive, AMD 29K
4374 This directive is ignored; it is accepted for compatibility with other
4378 @emph{Warning:} in other versions of the @sc{gnu} assembler, @code{.file} is
4379 used for the directive called @code{.app-file} in the AMD 29K support.
4383 @cindex @code{line} directive, AMD 29K
4384 This directive is ignored; it is accepted for compatibility with other
4388 @c since we're ignoring .lsym...
4389 @item .reg @var{symbol}, @var{expression}
4390 @cindex @code{reg} directive, AMD 29K
4391 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
4395 @cindex @code{sect} directive, AMD 29K
4396 This directive is ignored; it is accepted for compatibility with other
4399 @item .use @var{section name}
4400 @cindex @code{use} directive, AMD 29K
4401 Establishes the section and subsection for the following code;
4402 @var{section name} may be one of @code{.text}, @code{.data},
4403 @code{.data1}, or @code{.lit}. With one of the first three @var{section
4404 name} options, @samp{.use} is equivalent to the machine directive
4405 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
4409 @node AMD29K Opcodes
4412 @cindex AMD 29K opcodes
4413 @cindex opcodes for AMD 29K
4414 @code{@value{AS}} implements all the standard AMD 29K opcodes. No
4415 additional pseudo-instructions are needed on this family.
4417 For information on the 29K machine instruction set, see @cite{Am29000
4418 User's Manual}, Advanced Micro Devices, Inc.
4423 @node Machine Dependencies
4424 @chapter Machine Dependent Features
4426 The machine instruction sets are different on each Hitachi chip family,
4427 and there are also some syntax differences among the families. This
4428 chapter describes the specific @code{@value{AS}} features for each
4432 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
4433 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
4434 * SH-Dependent:: Hitachi SH Dependent Features
4444 @node H8/300-Dependent
4445 @chapter H8/300 Dependent Features
4447 @cindex H8/300 support
4449 * H8/300 Options:: Options
4450 * H8/300 Syntax:: Syntax
4451 * H8/300 Floating Point:: Floating Point
4452 * H8/300 Directives:: H8/300 Machine Directives
4453 * H8/300 Opcodes:: Opcodes
4456 @node H8/300 Options
4459 @cindex H8/300 options (none)
4460 @cindex options, H8/300 (none)
4461 @code{@value{AS}} has no additional command-line options for the Hitachi
4467 * H8/300-Chars:: Special Characters
4468 * H8/300-Regs:: Register Names
4469 * H8/300-Addressing:: Addressing Modes
4473 @subsection Special Characters
4475 @cindex line comment character, H8/300
4476 @cindex H8/300 line comment character
4477 @samp{;} is the line comment character.
4479 @cindex line separator, H8/300
4480 @cindex statement separator, H8/300
4481 @cindex H8/300 line separator
4482 @samp{$} can be used instead of a newline to separate statements.
4483 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4486 @subsection Register Names
4488 @cindex H8/300 registers
4489 @cindex register names, H8/300
4490 You can use predefined symbols of the form @samp{r@var{n}h} and
4491 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4492 general-purpose registers. @var{n} is a digit from @samp{0} to
4493 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4496 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4497 to the H8/300 registers as 16-bit registers (you must use this form for
4500 On the H8/300H, you can also use the eight predefined symbols
4501 @samp{er@var{n}} (@samp{er0} @dots{} @samp{er7}) to refer to the 32-bit
4502 general purpose registers.
4504 The two control registers are called @code{pc} (program counter; a
4505 16-bit register, except on the H8/300H where it is 24 bits) and
4506 @code{ccr} (condition code register; an 8-bit register). @code{r7} is
4507 used as the stack pointer, and can also be called @code{sp}.
4509 @node H8/300-Addressing
4510 @subsection Addressing Modes
4512 @cindex addressing modes, H8/300
4513 @cindex H8/300 addressing modes
4514 @value{AS} understands the following addressing modes for the H8/300:
4522 @item @@(@var{d}, r@var{n})
4523 @itemx @@(@var{d}:16, r@var{n})
4524 @itemx @@(@var{d}:24, r@var{n})
4525 Register indirect: 16-bit or 24-bit displacement @var{d} from register
4526 @var{n}. (24-bit displacements are only meaningful on the H8/300H.)
4529 Register indirect with post-increment
4532 Register indirect with pre-decrement
4534 @item @code{@@}@var{aa}
4535 @itemx @code{@@}@var{aa}:8
4536 @itemx @code{@@}@var{aa}:16
4537 @itemx @code{@@}@var{aa}:24
4538 Absolute address @code{aa}. (The address size @samp{:24} only makes
4539 sense on the H8/300H.)
4545 Immediate data @var{xx}. You may specify the @samp{:8}, @samp{:16}, or
4546 @samp{:32} for clarity, if you wish; but @code{@value{AS}} neither
4547 requires this nor uses it---the data size required is taken from
4550 @item @code{@@}@code{@@}@var{aa}
4551 @itemx @code{@@}@code{@@}@var{aa}:8
4552 Memory indirect. You may specify the @samp{:8} for clarity, if you
4553 wish; but @code{@value{AS}} neither requires this nor uses it.
4556 @node H8/300 Floating Point
4557 @section Floating Point
4559 @cindex floating point, H8/300 (@sc{ieee})
4560 @cindex H8/300 floating point (@sc{ieee})
4561 The H8/300 family has no hardware floating point, but the @code{.float}
4562 directive generates @sc{ieee} floating-point numbers for compatibility
4563 with other development tools.
4566 @node H8/300 Directives
4567 @section H8/300 Machine Directives
4569 @cindex H8/300 machine directives (none)
4570 @cindex machine directives, H8/300 (none)
4571 @cindex @code{word} directive, H8/300
4572 @cindex @code{int} directive, H8/300
4573 @code{@value{AS}} has only one machine-dependent directive for the
4577 @cindex H8/300H, assembling for
4579 Recognize and emit additional instructions for the H8/300H variant, and
4580 also make @code{.int} emit 32-bit numbers rather than the usual (16-bit)
4581 for the H8/300 family.
4584 On the H8/300 family (including the H8/300H) @samp{.word} directives
4585 generate 16-bit numbers.
4587 @node H8/300 Opcodes
4590 @cindex H8/300 opcode summary
4591 @cindex opcode summary, H8/300
4592 @cindex mnemonics, H8/300
4593 @cindex instruction summary, H8/300
4594 For detailed information on the H8/300 machine instruction set, see
4595 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025). For
4596 information specific to the H8/300H, see @cite{H8/300H Series
4597 Programming Manual} (Hitachi).
4599 @code{@value{AS}} implements all the standard H8/300 opcodes. No additional
4600 pseudo-instructions are needed on this family.
4603 @c this table, due to the multi-col faking and hardcoded order, looks silly
4604 @c except in smallbook. See comments below "@set SMALL" near top of this file.
4606 The following table summarizes the H8/300 opcodes, and their arguments.
4607 Entries marked @samp{*} are opcodes used only on the H8/300H.
4610 @c Using @group seems to use the normal baselineskip, not the smallexample
4611 @c baselineskip; looks approx doublespaced.
4613 Rs @r{source register}
4614 Rd @r{destination register}
4615 abs @r{absolute address}
4616 imm @r{immediate data}
4617 disp:N @r{N-bit displacement from a register}
4618 pcrel:N @r{N-bit displacement relative to program counter}
4620 add.b #imm,rd * andc #imm,ccr
4621 add.b rs,rd band #imm,rd
4622 add.w rs,rd band #imm,@@rd
4623 * add.w #imm,rd band #imm,@@abs:8
4624 * add.l rs,rd bra pcrel:8
4625 * add.l #imm,rd * bra pcrel:16
4626 adds #imm,rd bt pcrel:8
4627 addx #imm,rd * bt pcrel:16
4628 addx rs,rd brn pcrel:8
4629 and.b #imm,rd * brn pcrel:16
4630 and.b rs,rd bf pcrel:8
4631 * and.w rs,rd * bf pcrel:16
4632 * and.w #imm,rd bhi pcrel:8
4633 * and.l #imm,rd * bhi pcrel:16
4634 * and.l rs,rd bls pcrel:8
4636 * bls pcrel:16 bld #imm,rd
4637 bcc pcrel:8 bld #imm,@@rd
4638 * bcc pcrel:16 bld #imm,@@abs:8
4639 bhs pcrel:8 bnot #imm,rd
4640 * bhs pcrel:16 bnot #imm,@@rd
4641 bcs pcrel:8 bnot #imm,@@abs:8
4642 * bcs pcrel:16 bnot rs,rd
4643 blo pcrel:8 bnot rs,@@rd
4644 * blo pcrel:16 bnot rs,@@abs:8
4645 bne pcrel:8 bor #imm,rd
4646 * bne pcrel:16 bor #imm,@@rd
4647 beq pcrel:8 bor #imm,@@abs:8
4648 * beq pcrel:16 bset #imm,rd
4649 bvc pcrel:8 bset #imm,@@rd
4650 * bvc pcrel:16 bset #imm,@@abs:8
4651 bvs pcrel:8 bset rs,rd
4652 * bvs pcrel:16 bset rs,@@rd
4653 bpl pcrel:8 bset rs,@@abs:8
4654 * bpl pcrel:16 bsr pcrel:8
4655 bmi pcrel:8 bsr pcrel:16
4656 * bmi pcrel:16 bst #imm,rd
4657 bge pcrel:8 bst #imm,@@rd
4658 * bge pcrel:16 bst #imm,@@abs:8
4659 blt pcrel:8 btst #imm,rd
4660 * blt pcrel:16 btst #imm,@@rd
4661 bgt pcrel:8 btst #imm,@@abs:8
4662 * bgt pcrel:16 btst rs,rd
4663 ble pcrel:8 btst rs,@@rd
4664 * ble pcrel:16 btst rs,@@abs:8
4665 bclr #imm,rd bxor #imm,rd
4666 bclr #imm,@@rd bxor #imm,@@rd
4667 bclr #imm,@@abs:8 bxor #imm,@@abs:8
4668 bclr rs,rd cmp.b #imm,rd
4669 bclr rs,@@rd cmp.b rs,rd
4670 bclr rs,@@abs:8 cmp.w rs,rd
4671 biand #imm,rd cmp.w rs,rd
4672 biand #imm,@@rd * cmp.w #imm,rd
4673 biand #imm,@@abs:8 * cmp.l #imm,rd
4674 bild #imm,rd * cmp.l rs,rd
4675 bild #imm,@@rd daa rs
4676 bild #imm,@@abs:8 das rs
4677 bior #imm,rd dec.b rs
4678 bior #imm,@@rd * dec.w #imm,rd
4679 bior #imm,@@abs:8 * dec.l #imm,rd
4680 bist #imm,rd divxu.b rs,rd
4681 bist #imm,@@rd * divxu.w rs,rd
4682 bist #imm,@@abs:8 * divxs.b rs,rd
4683 bixor #imm,rd * divxs.w rs,rd
4684 bixor #imm,@@rd eepmov
4685 bixor #imm,@@abs:8 * eepmovw
4687 * exts.w rd mov.w rs,@@abs:16
4688 * exts.l rd * mov.l #imm,rd
4689 * extu.w rd * mov.l rs,rd
4690 * extu.l rd * mov.l @@rs,rd
4691 inc rs * mov.l @@(disp:16,rs),rd
4692 * inc.w #imm,rd * mov.l @@(disp:24,rs),rd
4693 * inc.l #imm,rd * mov.l @@rs+,rd
4694 jmp @@rs * mov.l @@abs:16,rd
4695 jmp abs * mov.l @@abs:24,rd
4696 jmp @@@@abs:8 * mov.l rs,@@rd
4697 jsr @@rs * mov.l rs,@@(disp:16,rd)
4698 jsr abs * mov.l rs,@@(disp:24,rd)
4699 jsr @@@@abs:8 * mov.l rs,@@-rd
4700 ldc #imm,ccr * mov.l rs,@@abs:16
4701 ldc rs,ccr * mov.l rs,@@abs:24
4702 * ldc @@abs:16,ccr movfpe @@abs:16,rd
4703 * ldc @@abs:24,ccr movtpe rs,@@abs:16
4704 * ldc @@(disp:16,rs),ccr mulxu.b rs,rd
4705 * ldc @@(disp:24,rs),ccr * mulxu.w rs,rd
4706 * ldc @@rs+,ccr * mulxs.b rs,rd
4707 * ldc @@rs,ccr * mulxs.w rs,rd
4708 * mov.b @@(disp:24,rs),rd neg.b rs
4709 * mov.b rs,@@(disp:24,rd) * neg.w rs
4710 mov.b @@abs:16,rd * neg.l rs
4712 mov.b @@abs:8,rd not.b rs
4713 mov.b rs,@@abs:8 * not.w rs
4714 mov.b rs,rd * not.l rs
4715 mov.b #imm,rd or.b #imm,rd
4716 mov.b @@rs,rd or.b rs,rd
4717 mov.b @@(disp:16,rs),rd * or.w #imm,rd
4718 mov.b @@rs+,rd * or.w rs,rd
4719 mov.b @@abs:8,rd * or.l #imm,rd
4720 mov.b rs,@@rd * or.l rs,rd
4721 mov.b rs,@@(disp:16,rd) orc #imm,ccr
4722 mov.b rs,@@-rd pop.w rs
4723 mov.b rs,@@abs:8 * pop.l rs
4724 mov.w rs,@@rd push.w rs
4725 * mov.w @@(disp:24,rs),rd * push.l rs
4726 * mov.w rs,@@(disp:24,rd) rotl.b rs
4727 * mov.w @@abs:24,rd * rotl.w rs
4728 * mov.w rs,@@abs:24 * rotl.l rs
4729 mov.w rs,rd rotr.b rs
4730 mov.w #imm,rd * rotr.w rs
4731 mov.w @@rs,rd * rotr.l rs
4732 mov.w @@(disp:16,rs),rd rotxl.b rs
4733 mov.w @@rs+,rd * rotxl.w rs
4734 mov.w @@abs:16,rd * rotxl.l rs
4735 mov.w rs,@@(disp:16,rd) rotxr.b rs
4736 mov.w rs,@@-rd * rotxr.w rs
4738 * rotxr.l rs * stc ccr,@@(disp:24,rd)
4740 rte * stc ccr,@@abs:16
4741 rts * stc ccr,@@abs:24
4742 shal.b rs sub.b rs,rd
4743 * shal.w rs sub.w rs,rd
4744 * shal.l rs * sub.w #imm,rd
4745 shar.b rs * sub.l rs,rd
4746 * shar.w rs * sub.l #imm,rd
4747 * shar.l rs subs #imm,rd
4748 shll.b rs subx #imm,rd
4749 * shll.w rs subx rs,rd
4750 * shll.l rs * trapa #imm
4751 shlr.b rs xor #imm,rd
4752 * shlr.w rs xor rs,rd
4753 * shlr.l rs * xor.w #imm,rd
4755 stc ccr,rd * xor.l #imm,rd
4756 * stc ccr,@@rs * xor.l rs,rd
4757 * stc ccr,@@(disp:16,rd) xorc #imm,ccr
4761 @cindex size suffixes, H8/300
4762 @cindex H8/300 size suffixes
4763 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4764 @code{sub}) are defined with variants using the suffixes @samp{.b},
4765 @samp{.w}, and @samp{.l} to specify the size of a memory operand.
4766 @code{@value{AS}} supports these suffixes, but does not require them;
4767 since one of the operands is always a register, @code{@value{AS}} can
4768 deduce the correct size.
4770 For example, since @code{r0} refers to a 16-bit register,
4773 @exdent is equivalent to
4777 If you use the size suffixes, @code{@value{AS}} issues a warning when
4778 the suffix and the register size do not match.
4783 @node H8/500-Dependent
4784 @chapter H8/500 Dependent Features
4786 @cindex H8/500 support
4788 * H8/500 Options:: Options
4789 * H8/500 Syntax:: Syntax
4790 * H8/500 Floating Point:: Floating Point
4791 * H8/500 Directives:: H8/500 Machine Directives
4792 * H8/500 Opcodes:: Opcodes
4795 @node H8/500 Options
4798 @cindex H8/500 options (none)
4799 @cindex options, H8/500 (none)
4800 @code{@value{AS}} has no additional command-line options for the Hitachi
4807 * H8/500-Chars:: Special Characters
4808 * H8/500-Regs:: Register Names
4809 * H8/500-Addressing:: Addressing Modes
4813 @subsection Special Characters
4815 @cindex line comment character, H8/500
4816 @cindex H8/500 line comment character
4817 @samp{!} is the line comment character.
4819 @cindex line separator, H8/500
4820 @cindex statement separator, H8/500
4821 @cindex H8/500 line separator
4822 @samp{;} can be used instead of a newline to separate statements.
4824 @cindex symbol names, @samp{$} in
4825 @cindex @code{$} in symbol names
4826 Since @samp{$} has no special meaning, you may use it in symbol names.
4829 @subsection Register Names
4831 @cindex H8/500 registers
4832 @cindex registers, H8/500
4833 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
4834 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, and @samp{r7} to refer to
4835 the H8/500 registers.
4837 The H8/500 also has these control registers:
4859 condition code register
4862 All registers are 16 bits long. To represent 32 bit numbers, use two
4863 adjacent registers; for distant memory addresses, use one of the segment
4864 pointers (@code{cp} for the program counter; @code{dp} for
4865 @code{r0}--@code{r3}; @code{ep} for @code{r4} and @code{r5}; and
4866 @code{tp} for @code{r6} and @code{r7}.
4868 @node H8/500-Addressing
4869 @subsection Addressing Modes
4871 @cindex addressing modes, H8/500
4872 @cindex H8/500 addressing modes
4873 @value{AS} understands the following addressing modes for the H8/500:
4881 @item @@(d:8, R@var{n})
4882 Register indirect with 8 bit signed displacement
4884 @item @@(d:16, R@var{n})
4885 Register indirect with 16 bit signed displacement
4888 Register indirect with pre-decrement
4891 Register indirect with post-increment
4894 8 bit absolute address
4897 16 bit absolute address
4906 @node H8/500 Floating Point
4907 @section Floating Point
4909 @cindex floating point, H8/500 (@sc{ieee})
4910 @cindex H8/500 floating point (@sc{ieee})
4911 The H8/500 family uses @sc{ieee} floating-point numbers.
4913 @node H8/500 Directives
4914 @section H8/500 Machine Directives
4916 @cindex H8/500 machine directives (none)
4917 @cindex machine directives, H8/500 (none)
4918 @cindex @code{word} directive, H8/500
4919 @cindex @code{int} directive, H8/500
4920 @code{@value{AS}} has no machine-dependent directives for the H8/500.
4921 However, on this platform the @samp{.int} and @samp{.word} directives
4922 generate 16-bit numbers.
4924 @node H8/500 Opcodes
4927 @cindex H8/500 opcode summary
4928 @cindex opcode summary, H8/500
4929 @cindex mnemonics, H8/500
4930 @cindex instruction summary, H8/500
4931 For detailed information on the H8/500 machine instruction set, see
4932 @cite{H8/500 Series Programming Manual} (Hitachi M21T001).
4934 @code{@value{AS}} implements all the standard H8/500 opcodes. No additional
4935 pseudo-instructions are needed on this family.
4938 @c this table, due to the multi-col faking and hardcoded order, looks silly
4939 @c except in smallbook. See comments below "@set SMALL" near top of this file.
4941 The following table summarizes H8/500 opcodes and their operands:
4943 @c Use @group if it ever works, instead of @page
4947 abs8 @r{8-bit absolute address}
4948 abs16 @r{16-bit absolute address}
4949 abs24 @r{24-bit absolute address}
4950 crb @r{@code{ccr}, @code{br}, @code{ep}, @code{dp}, @code{tp}, @code{dp}}
4951 disp8 @r{8-bit displacement}
4952 ea @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4953 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16},}
4954 @r{@code{#xx:8}, @code{#xx:16}}
4955 ea_mem @r{@code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4956 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4957 ea_noimm @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
4958 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
4960 imm4 @r{4-bit immediate data}
4961 imm8 @r{8-bit immediate data}
4962 imm16 @r{16-bit immediate data}
4963 pcrel8 @r{8-bit offset from program counter}
4964 pcrel16 @r{16-bit offset from program counter}
4965 qim @r{@code{-2}, @code{-1}, @code{1}, @code{2}}
4967 rs @r{a register distinct from rd}
4968 rlist @r{comma-separated list of registers in parentheses;}
4969 @r{register ranges @code{rd-rs} are allowed}
4970 sp @r{stack pointer (@code{r7})}
4971 sr @r{status register}
4972 sz @r{size; @samp{.b} or @samp{.w}. If omitted, default @samp{.w}}
4974 ldc[.b] ea,crb bcc[.w] pcrel16
4975 ldc[.w] ea,sr bcc[.b] pcrel8
4976 add[:q] sz qim,ea_noimm bhs[.w] pcrel16
4977 add[:g] sz ea,rd bhs[.b] pcrel8
4978 adds sz ea,rd bcs[.w] pcrel16
4979 addx sz ea,rd bcs[.b] pcrel8
4980 and sz ea,rd blo[.w] pcrel16
4981 andc[.b] imm8,crb blo[.b] pcrel8
4982 andc[.w] imm16,sr bne[.w] pcrel16
4984 bra[.w] pcrel16 beq[.w] pcrel16
4985 bra[.b] pcrel8 beq[.b] pcrel8
4986 bt[.w] pcrel16 bvc[.w] pcrel16
4987 bt[.b] pcrel8 bvc[.b] pcrel8
4988 brn[.w] pcrel16 bvs[.w] pcrel16
4989 brn[.b] pcrel8 bvs[.b] pcrel8
4990 bf[.w] pcrel16 bpl[.w] pcrel16
4991 bf[.b] pcrel8 bpl[.b] pcrel8
4992 bhi[.w] pcrel16 bmi[.w] pcrel16
4993 bhi[.b] pcrel8 bmi[.b] pcrel8
4994 bls[.w] pcrel16 bge[.w] pcrel16
4995 bls[.b] pcrel8 bge[.b] pcrel8
4997 blt[.w] pcrel16 mov[:g][.b] imm8,ea_mem
4998 blt[.b] pcrel8 mov[:g][.w] imm16,ea_mem
4999 bgt[.w] pcrel16 movfpe[.b] ea,rd
5000 bgt[.b] pcrel8 movtpe[.b] rs,ea_noimm
5001 ble[.w] pcrel16 mulxu sz ea,rd
5002 ble[.b] pcrel8 neg sz ea
5003 bclr sz imm4,ea_noimm nop
5004 bclr sz rs,ea_noimm not sz ea
5005 bnot sz imm4,ea_noimm or sz ea,rd
5006 bnot sz rs,ea_noimm orc[.b] imm8,crb
5007 bset sz imm4,ea_noimm orc[.w] imm16,sr
5008 bset sz rs,ea_noimm pjmp abs24
5009 bsr[.b] pcrel8 pjmp @@rd
5010 bsr[.w] pcrel16 pjsr abs24
5011 btst sz imm4,ea_noimm pjsr @@rd
5012 btst sz rs,ea_noimm prtd imm8
5013 clr sz ea prtd imm16
5014 cmp[:e][.b] imm8,rd prts
5015 cmp[:i][.w] imm16,rd rotl sz ea
5016 cmp[:g].b imm8,ea_noimm rotr sz ea
5017 cmp[:g][.w] imm16,ea_noimm rotxl sz ea
5018 Cmp[:g] sz ea,rd rotxr sz ea
5020 divxu sz ea,rd rtd imm16
5022 exts[.b] rd scb/f rs,pcrel8
5023 extu[.b] rd scb/ne rs,pcrel8
5024 jmp @@rd scb/eq rs,pcrel8
5025 jmp @@(imm8,rd) shal sz ea
5026 jmp @@(imm16,rd) shar sz ea
5027 jmp abs16 shll sz ea
5029 jsr @@(imm8,rd) sleep
5030 jsr @@(imm16,rd) stc[.b] crb,ea_noimm
5031 jsr abs16 stc[.w] sr,ea_noimm
5032 ldm @@sp+,(rlist) stm (rlist),@@-sp
5033 link fp,imm8 sub sz ea,rd
5034 link fp,imm16 subs sz ea,rd
5035 mov[:e][.b] imm8,rd subx sz ea,rd
5036 mov[:i][.w] imm16,rd swap[.b] rd
5037 mov[:l][.w] abs8,rd tas[.b] ea
5038 mov[:l].b abs8,rd trapa imm4
5039 mov[:s][.w] rs,abs8 trap/vs
5040 mov[:s].b rs,abs8 tst sz ea
5041 mov[:f][.w] @@(disp8,fp),rd unlk fp
5042 mov[:f][.w] rs,@@(disp8,fp) xch[.w] rs,rd
5043 mov[:f].b @@(disp8,fp),rd xor sz ea,rd
5044 mov[:f].b rs,@@(disp8,fp) xorc.b imm8,crb
5045 mov[:g] sz rs,ea_mem xorc.w imm16,sr
5053 @node HPPA-Dependent
5054 @chapter HPPA Dependent Features
5058 * HPPA Notes:: Notes
5059 * HPPA Options:: Options
5060 * HPPA Syntax:: Syntax
5061 * HPPA Floating Point:: Floating Point
5062 * HPPA Directives:: HPPA Machine Directives
5063 * HPPA Opcodes:: Opcodes
5068 As a back end for @sc{gnu} @sc{cc} @code{@value{AS}} has been throughly tested and should
5069 work extremely well. We have tested it only minimally on hand written assembly
5070 code and no one has tested it much on the assembly output from the HP
5073 The format of the debugging sections has changed since the original
5074 @code{@value{AS}} port (version 1.3X) was released; therefore,
5075 you must rebuild all HPPA objects and libraries with the new
5076 assembler so that you can debug the final executable.
5078 The HPPA @code{@value{AS}} port generates a small subset of the relocations
5079 available in the SOM and ELF object file formats. Additional relocation
5080 support will be added as it becomes necessary.
5084 @code{@value{AS}} has no machine-dependent command-line options for the HPPA.
5089 The assembler syntax closely follows the HPPA instruction set
5090 reference manual; assembler directives and general syntax closely follow the
5091 HPPA assembly language reference manual, with a few noteworthy differences.
5093 First, a colon may immediately follow a label definition. This is
5094 simply for compatibility with how most assembly language programmers
5097 Some obscure expression parsing problems may affect hand written code which
5098 uses the @code{spop} instructions, or code which makes significant
5099 use of the @code{!} line separator.
5101 @code{@value{AS}} is much less forgiving about missing arguments and other
5102 similar oversights than the HP assembler. @code{@value{AS}} notifies you
5103 of missing arguments as syntax errors; this is regarded as a feature, not a
5106 Finally, @code{@value{AS}} allows you to use an external symbol without
5107 explicitly importing the symbol. @emph{Warning:} in the future this will be
5108 an error for HPPA targets.
5110 Special characters for HPPA targets include:
5112 @samp{;} is the line comment character.
5114 @samp{!} can be used instead of a newline to separate statements.
5116 Since @samp{$} has no special meaning, you may use it in symbol names.
5118 @node HPPA Floating Point
5119 @section Floating Point
5120 @cindex floating point, HPPA (@sc{ieee})
5121 @cindex HPPA floating point (@sc{ieee})
5122 The HPPA family uses @sc{ieee} floating-point numbers.
5124 @node HPPA Directives
5125 @section HPPA Assembler Directives
5127 @code{@value{AS}} for the HPPA supports many additional directives for
5128 compatibility with the native assembler. This section describes them only
5129 briefly. For detailed information on HPPA-specific assembler directives, see
5130 @cite{HP9000 Series 800 Assembly Language Reference Manual} (HP 92432-90001).
5132 @cindex HPPA directives not supported
5133 @code{@value{AS}} does @emph{not} support the following assembler directives
5134 described in the HP manual:
5143 @cindex @code{.param} on HPPA
5144 Beyond those implemented for compatibility, @code{@value{AS}} supports one
5145 additional assembler directive for the HPPA: @code{.param}. It conveys
5146 register argument locations for static functions. Its syntax closely follows
5147 the @code{.export} directive.
5149 @cindex HPPA-only directives
5150 These are the additional directives in @code{@value{AS}} for the HPPA:
5153 @item .block @var{n}
5154 @itemx .blockz @var{n}
5155 Reserve @var{n} bytes of storage, and initialize them to zero.
5158 Mark the beginning of a procedure call. Only the special case with @emph{no
5159 arguments} is allowed.
5161 @item .callinfo [ @var{param}=@var{value}, @dots{} ] [ @var{flag}, @dots{} ]
5162 Specify a number of parameters and flags that define the environment for a
5165 @var{param} may be any of @samp{frame} (frame size), @samp{entry_gr} (end of
5166 general register range), @samp{entry_fr} (end of float register range),
5167 @samp{entry_sr} (end of space register range).
5169 The values for @var{flag} are @samp{calls} or @samp{caller} (proc has
5170 subroutines), @samp{no_calls} (proc does not call subroutines), @samp{save_rp}
5171 (preserve return pointer), @samp{save_sp} (proc preserves stack pointer),
5172 @samp{no_unwind} (do not unwind this proc), @samp{hpux_int} (proc is interrupt
5176 Assemble into the standard section called @samp{$TEXT$}, subsection
5180 @item .copyright "@var{string}"
5181 In the SOM object format, insert @var{string} into the object code, marked as a
5186 @item .copyright "@var{string}"
5187 In the ELF object format, insert @var{string} into the object code, marked as a
5192 Not yet supported; the assembler rejects programs containing this directive.
5195 Mark the beginning of a procedure.
5198 Mark the end of a procedure.
5200 @item .export @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5201 Make a procedure @var{name} available to callers. @var{typ}, if present, must
5202 be one of @samp{absolute}, @samp{code} (ELF only, not SOM), @samp{data},
5203 @samp{entry}, @samp{data}, @samp{entry}, @samp{millicode}, @samp{plabel},
5204 @samp{pri_prog}, or @samp{sec_prog}.
5206 @var{param}, if present, provides either relocation information for the
5207 procedure arguments and result, or a privilege level. @var{param} may be
5208 @samp{argw@var{n}} (where @var{n} ranges from @code{0} to @code{3}, and
5209 indicates one of four one-word arguments); @samp{rtnval} (the procedure's
5210 result); or @samp{priv_lev} (privilege level). For arguments or the result,
5211 @var{r} specifies how to relocate, and must be one of @samp{no} (not
5212 relocatable), @samp{gr} (argument is in general register), @samp{fr} (in
5213 floating point register), or @samp{fu} (upper half of float register).
5214 For @samp{priv_lev}, @var{r} is an integer.
5217 Define a two-byte integer constant @var{n}; synonym for the portable
5218 @code{@value{AS}} directive @code{.short}.
5220 @item .import @var{name} [ ,@var{typ} ]
5221 Converse of @code{.export}; make a procedure available to call. The arguments
5222 use the same conventions as the first two arguments for @code{.export}.
5224 @item .label @var{name}
5225 Define @var{name} as a label for the current assembly location.
5228 Not yet supported; the assembler rejects programs containing this directive.
5230 @item .origin @var{lc}
5231 Advance location counter to @var{lc}. Synonym for the @code{@value{as}}
5232 portable directive @code{.org}.
5234 @item .param @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5235 @c Not in HP manual; GNU HPPA extension
5236 Similar to @code{.export}, but used for static procedures.
5239 Use preceding the first statement of a procedure.
5242 Use following the last statement of a procedure.
5244 @item @var{label} .reg @var{expr}
5245 @c ?? Not in HP manual (Jan 1988 vn)
5246 Synonym for @code{.equ}; define @var{label} with the absolute expression
5247 @var{expr} as its value.
5249 @item .space @var{secname} [ ,@var{params} ]
5250 Switch to section @var{secname}, creating a new section by that name if
5251 necessary. You may only use @var{params} when creating a new section, not
5252 when switching to an existing one. @var{secname} may identify a section by
5253 number rather than by name.
5255 If specified, the list @var{params} declares attributes of the section,
5256 identified by keywords. The keywords recognized are @samp{spnum=@var{exp}}
5257 (identify this section by the number @var{exp}, an absolute expression),
5258 @samp{sort=@var{exp}} (order sections according to this sort key when linking;
5259 @var{exp} is an absolute expression), @samp{unloadable} (section contains no
5260 loadable data), @samp{notdefined} (this section defined elsewhere), and
5261 @samp{private} (data in this section not available to other programs).
5263 @item .spnum @var{secnam}
5264 @c ?? Not in HP manual (Jan 1988)
5265 Allocate four bytes of storage, and initialize them with the section number of
5266 the section named @var{secnam}. (You can define the section number with the
5267 HPPA @code{.space} directive.)
5269 @item .string "@var{str}"
5270 @cindex @code{string} directive on HPPA
5271 Copy the characters in the string @var{str} to the object file.
5272 @xref{Strings,,Strings}, for information on escape sequences you can use in
5273 @code{@value{AS}} strings.
5275 @emph{Warning!} The HPPA version of @code{.string} differs from the
5276 usual @code{@value{AS}} definition: it does @emph{not} write a zero byte
5277 after copying @var{str}.
5279 @item .stringz "@var{str}"
5280 Like @code{.string}, but appends a zero byte after copying @var{str} to object
5283 @item .subspa @var{name} [ ,@var{params} ]
5284 Similar to @code{.space}, but selects a subsection @var{name} within the
5285 current section. You may only specify @var{params} when you create a
5286 subsection (in the first instance of @code{.subspa} for this @var{name}).
5288 If specified, the list @var{params} declares attributes of the subsection,
5289 identified by keywords. The keywords recognized are @samp{quad=@var{expr}}
5290 (``quadrant'' for this subsection), @samp{align=@var{expr}} (alignment for
5291 beginning of this subsection; a power of two), @samp{access=@var{expr}} (value
5292 for ``access rights'' field), @samp{sort=@var{expr}} (sorting order for this
5293 subspace in link), @samp{code_only} (subsection contains only code),
5294 @samp{unloadable} (subsection cannot be loaded into memory), @samp{common}
5295 (subsection is common block), @samp{dup_comm} (initialized data may have
5296 duplicate names), or @samp{zero} (subsection is all zeros, do not write in
5299 @item .version "@var{str}"
5300 Write @var{str} as version identifier in object code.
5305 For detailed information on the HPPA machine instruction set, see
5306 @cite{PA-RISC Architecture and Instruction Set Reference Manual}
5313 @chapter Hitachi SH Dependent Features
5317 * SH Options:: Options
5318 * SH Syntax:: Syntax
5319 * SH Floating Point:: Floating Point
5320 * SH Directives:: SH Machine Directives
5321 * SH Opcodes:: Opcodes
5327 @cindex SH options (none)
5328 @cindex options, SH (none)
5329 @code{@value{AS}} has no additional command-line options for the Hitachi
5336 * SH-Chars:: Special Characters
5337 * SH-Regs:: Register Names
5338 * SH-Addressing:: Addressing Modes
5342 @subsection Special Characters
5344 @cindex line comment character, SH
5345 @cindex SH line comment character
5346 @samp{!} is the line comment character.
5348 @cindex line separator, SH
5349 @cindex statement separator, SH
5350 @cindex SH line separator
5351 You can use @samp{;} instead of a newline to separate statements.
5353 @cindex symbol names, @samp{$} in
5354 @cindex @code{$} in symbol names
5355 Since @samp{$} has no special meaning, you may use it in symbol names.
5358 @subsection Register Names
5360 @cindex SH registers
5361 @cindex registers, SH
5362 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
5363 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, @samp{r7}, @samp{r8},
5364 @samp{r9}, @samp{r10}, @samp{r11}, @samp{r12}, @samp{r13}, @samp{r14},
5365 and @samp{r15} to refer to the SH registers.
5367 The SH also has these control registers:
5371 procedure register (holds return address)
5378 high and low multiply accumulator registers
5384 global base register
5387 vector base register (for interrupt vectors)
5391 @subsection Addressing Modes
5393 @cindex addressing modes, SH
5394 @cindex SH addressing modes
5395 @code{@value{AS}} understands the following addressing modes for the SH.
5396 @code{R@var{n}} in the following refers to any of the numbered
5397 registers, but @emph{not} the control registers.
5407 Register indirect with pre-decrement
5410 Register indirect with post-increment
5412 @item @@(@var{disp}, R@var{n})
5413 Register indirect with displacement
5415 @item @@(R0, R@var{n})
5418 @item @@(@var{disp}, GBR)
5425 @itemx @@(@var{disp}, PC)
5426 PC relative address (for branch or for addressing memory). The
5427 @code{@value{AS}} implementation allows you to use the simpler form
5428 @var{addr} anywhere a PC relative address is called for; the alternate
5429 form is supported for compatibility with other assemblers.
5435 @node SH Floating Point
5436 @section Floating Point
5438 @cindex floating point, SH (@sc{ieee})
5439 @cindex SH floating point (@sc{ieee})
5440 The SH family uses @sc{ieee} floating-point numbers.
5443 @section SH Machine Directives
5445 @cindex SH machine directives (none)
5446 @cindex machine directives, SH (none)
5447 @cindex @code{word} directive, SH
5448 @cindex @code{int} directive, SH
5449 @code{@value{AS}} has no machine-dependent directives for the SH.
5454 @cindex SH opcode summary
5455 @cindex opcode summary, SH
5456 @cindex mnemonics, SH
5457 @cindex instruction summary, SH
5458 For detailed information on the SH machine instruction set, see
5459 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
5461 @code{@value{AS}} implements all the standard SH opcodes. No additional
5462 pseudo-instructions are needed on this family. Note, however, that
5463 because @code{@value{AS}} supports a simpler form of PC-relative
5464 addressing, you may simply write (for example)
5471 where other assemblers might require an explicit displacement to
5472 @code{bar} from the program counter:
5475 mov.l @@(@var{disp}, PC)
5479 @c this table, due to the multi-col faking and hardcoded order, looks silly
5480 @c except in smallbook. See comments below "@set SMALL" near top of this file.
5482 Here is a summary of SH opcodes:
5487 Rn @r{a numbered register}
5488 Rm @r{another numbered register}
5489 #imm @r{immediate data}
5490 disp @r{displacement}
5491 disp8 @r{8-bit displacement}
5492 disp12 @r{12-bit displacement}
5494 add #imm,Rn lds.l @@Rn+,PR
5495 add Rm,Rn mac.w @@Rm+,@@Rn+
5496 addc Rm,Rn mov #imm,Rn
5497 addv Rm,Rn mov Rm,Rn
5498 and #imm,R0 mov.b Rm,@@(R0,Rn)
5499 and Rm,Rn mov.b Rm,@@-Rn
5500 and.b #imm,@@(R0,GBR) mov.b Rm,@@Rn
5501 bf disp8 mov.b @@(disp,Rm),R0
5502 bra disp12 mov.b @@(disp,GBR),R0
5503 bsr disp12 mov.b @@(R0,Rm),Rn
5504 bt disp8 mov.b @@Rm+,Rn
5505 clrmac mov.b @@Rm,Rn
5506 clrt mov.b R0,@@(disp,Rm)
5507 cmp/eq #imm,R0 mov.b R0,@@(disp,GBR)
5508 cmp/eq Rm,Rn mov.l Rm,@@(disp,Rn)
5509 cmp/ge Rm,Rn mov.l Rm,@@(R0,Rn)
5510 cmp/gt Rm,Rn mov.l Rm,@@-Rn
5511 cmp/hi Rm,Rn mov.l Rm,@@Rn
5512 cmp/hs Rm,Rn mov.l @@(disp,Rn),Rm
5513 cmp/pl Rn mov.l @@(disp,GBR),R0
5514 cmp/pz Rn mov.l @@(disp,PC),Rn
5515 cmp/str Rm,Rn mov.l @@(R0,Rm),Rn
5516 div0s Rm,Rn mov.l @@Rm+,Rn
5518 div1 Rm,Rn mov.l R0,@@(disp,GBR)
5519 exts.b Rm,Rn mov.w Rm,@@(R0,Rn)
5520 exts.w Rm,Rn mov.w Rm,@@-Rn
5521 extu.b Rm,Rn mov.w Rm,@@Rn
5522 extu.w Rm,Rn mov.w @@(disp,Rm),R0
5523 jmp @@Rn mov.w @@(disp,GBR),R0
5524 jsr @@Rn mov.w @@(disp,PC),Rn
5525 ldc Rn,GBR mov.w @@(R0,Rm),Rn
5526 ldc Rn,SR mov.w @@Rm+,Rn
5527 ldc Rn,VBR mov.w @@Rm,Rn
5528 ldc.l @@Rn+,GBR mov.w R0,@@(disp,Rm)
5529 ldc.l @@Rn+,SR mov.w R0,@@(disp,GBR)
5530 ldc.l @@Rn+,VBR mova @@(disp,PC),R0
5532 lds Rn,MACL muls Rm,Rn
5533 lds Rn,PR mulu Rm,Rn
5534 lds.l @@Rn+,MACH neg Rm,Rn
5535 lds.l @@Rn+,MACL negc Rm,Rn
5538 not Rm,Rn stc.l GBR,@@-Rn
5539 or #imm,R0 stc.l SR,@@-Rn
5540 or Rm,Rn stc.l VBR,@@-Rn
5541 or.b #imm,@@(R0,GBR) sts MACH,Rn
5542 rotcl Rn sts MACL,Rn
5544 rotl Rn sts.l MACH,@@-Rn
5545 rotr Rn sts.l MACL,@@-Rn
5550 shar Rn swap.b Rm,Rn
5551 shll Rn swap.w Rm,Rn
5552 shll16 Rn tas.b @@Rn
5554 shll8 Rn tst #imm,R0
5556 shlr16 Rn tst.b #imm,@@(R0,GBR)
5557 shlr2 Rn xor #imm,R0
5559 sleep xor.b #imm,@@(R0,GBR)
5560 stc GBR,Rn xtrct Rm,Rn
5575 @node i960-Dependent
5576 @chapter Intel 80960 Dependent Features
5579 @node Machine Dependencies
5580 @chapter Intel 80960 Dependent Features
5583 @cindex i960 support
5585 * Options-i960:: i960 Command-line Options
5586 * Floating Point-i960:: Floating Point
5587 * Directives-i960:: i960 Machine Directives
5588 * Opcodes for i960:: i960 Opcodes
5591 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
5592 @c long as they're not turned on for other machines than 960.
5596 @section i960 Command-line Options
5598 @cindex i960 options
5599 @cindex options, i960
5602 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
5603 @cindex i960 architecture options
5604 @cindex architecture options, i960
5605 @cindex @code{-A} options, i960
5606 Select the 80960 architecture. Instructions or features not supported
5607 by the selected architecture cause fatal errors.
5609 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
5610 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
5612 If you do not specify any of these options, @code{@value{AS}} generates code
5613 for any instruction or feature that is supported by @emph{some} version of the
5614 960 (even if this means mixing architectures!). In principle,
5615 @code{@value{AS}} attempts to deduce the minimal sufficient processor type if
5616 none is specified; depending on the object code format, the processor type may
5617 be recorded in the object file. If it is critical that the @code{@value{AS}}
5618 output match a specific architecture, specify that architecture explicitly.
5621 @cindex @code{-b} option, i960
5622 @cindex branch recording, i960
5623 @cindex i960 branch recording
5624 Add code to collect information about conditional branches taken, for
5625 later optimization using branch prediction bits. (The conditional branch
5626 instructions have branch prediction bits in the CA, CB, and CC
5627 architectures.) If @var{BR} represents a conditional branch instruction,
5628 the following represents the code generated by the assembler when
5629 @samp{-b} is specified:
5632 call @var{increment routine}
5633 .word 0 # pre-counter
5635 call @var{increment routine}
5636 .word 0 # post-counter
5639 The counter following a branch records the number of times that branch
5640 was @emph{not} taken; the differenc between the two counters is the
5641 number of times the branch @emph{was} taken.
5643 @cindex @code{gbr960}, i960 postprocessor
5644 @cindex branch statistics table, i960
5645 A table of every such @code{Label} is also generated, so that the
5646 external postprocessor @code{gbr960} (supplied by Intel) can locate all
5647 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
5648 this is a local symbol to permit collecting statistics for many separate
5649 object files. The table is word aligned, and begins with a two-word
5650 header. The first word, initialized to 0, is used in maintaining linked
5651 lists of branch tables. The second word is a count of the number of
5652 entries in the table, which follow immediately: each is a word, pointing
5653 to one of the labels illustrated above.
5657 @c END TEXI2ROFF-KILL
5659 +------------+------------+------------+ ... +------------+
5661 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
5663 +------------+------------+------------+ ... +------------+
5665 __BRANCH_TABLE__ layout
5672 \line{\leftskip=0pt\hskip\tableindent
5673 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
5674 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
5675 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
5677 @c END TEXI2ROFF-KILL
5679 The first word of the header is used to locate multiple branch tables,
5680 since each object file may contain one. Normally the links are
5681 maintained with a call to an initialization routine, placed at the
5682 beginning of each function in the file. The @sc{gnu} C compiler
5683 generates these calls automatically when you give it a @samp{-b} option.
5684 For further details, see the documentation of @samp{gbr960}.
5687 @cindex @code{-no-relax} option, i960
5688 Normally, Compare-and-Branch instructions with targets that require
5689 displacements greater than 13 bits (or that have external targets) are
5690 replaced with the corresponding compare (or @samp{chkbit}) and branch
5691 instructions. You can use the @samp{-no-relax} option to specify that
5692 @code{@value{AS}} should generate errors instead, if the target displacement
5693 is larger than 13 bits.
5695 This option does not affect the Compare-and-Jump instructions; the code
5696 emitted for them is @emph{always} adjusted when necessary (depending on
5697 displacement size), regardless of whether you use @samp{-no-relax}.
5700 @node Floating Point-i960
5701 @section Floating Point
5703 @cindex floating point, i960 (@sc{ieee})
5704 @cindex i960 floating point (@sc{ieee})
5705 @code{@value{AS}} generates @sc{ieee} floating-point numbers for the directives
5706 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
5708 @node Directives-i960
5709 @section i960 Machine Directives
5711 @cindex machine directives, i960
5712 @cindex i960 machine directives
5715 @cindex @code{bss} directive, i960
5716 @item .bss @var{symbol}, @var{length}, @var{align}
5717 Reserve @var{length} bytes in the bss section for a local @var{symbol},
5718 aligned to the power of two specified by @var{align}. @var{length} and
5719 @var{align} must be positive absolute expressions. This directive
5720 differs from @samp{.lcomm} only in that it permits you to specify
5721 an alignment. @xref{Lcomm,,@code{.lcomm}}.
5725 @item .extended @var{flonums}
5726 @cindex @code{extended} directive, i960
5727 @code{.extended} expects zero or more flonums, separated by commas; for
5728 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
5729 floating-point number.
5731 @item .leafproc @var{call-lab}, @var{bal-lab}
5732 @cindex @code{leafproc} directive, i960
5733 You can use the @samp{.leafproc} directive in conjunction with the
5734 optimized @code{callj} instruction to enable faster calls of leaf
5735 procedures. If a procedure is known to call no other procedures, you
5736 may define an entry point that skips procedure prolog code (and that does
5737 not depend on system-supplied saved context), and declare it as the
5738 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
5739 entry point that goes through the normal prolog, you can specify that
5740 entry point as @var{call-lab}.
5742 A @samp{.leafproc} declaration is meant for use in conjunction with the
5743 optimized call instruction @samp{callj}; the directive records the data
5744 needed later to choose between converting the @samp{callj} into a
5745 @code{bal} or a @code{call}.
5747 @var{call-lab} is optional; if only one argument is present, or if the
5748 two arguments are identical, the single argument is assumed to be the
5749 @code{bal} entry point.
5751 @item .sysproc @var{name}, @var{index}
5752 @cindex @code{sysproc} directive, i960
5753 The @samp{.sysproc} directive defines a name for a system procedure.
5754 After you define it using @samp{.sysproc}, you can use @var{name} to
5755 refer to the system procedure identified by @var{index} when calling
5756 procedures with the optimized call instruction @samp{callj}.
5758 Both arguments are required; @var{index} must be between 0 and 31
5762 @node Opcodes for i960
5763 @section i960 Opcodes
5765 @cindex opcodes, i960
5766 @cindex i960 opcodes
5767 All Intel 960 machine instructions are supported;
5768 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
5769 selecting the instruction subset for a particular 960
5770 architecture.@refill
5772 Some opcodes are processed beyond simply emitting a single corresponding
5773 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
5774 instructions with target displacements larger than 13 bits.
5777 * callj-i960:: @code{callj}
5778 * Compare-and-branch-i960:: Compare-and-Branch
5782 @subsection @code{callj}
5784 @cindex @code{callj}, i960 pseudo-opcode
5785 @cindex i960 @code{callj} pseudo-opcode
5786 You can write @code{callj} to have the assembler or the linker determine
5787 the most appropriate form of subroutine call: @samp{call},
5788 @samp{bal}, or @samp{calls}. If the assembly source contains
5789 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
5790 defining the operand---then @code{@value{AS}} translates the
5791 @code{callj}; if not, it simply emits the @code{callj}, leaving it
5792 for the linker to resolve.
5794 @node Compare-and-branch-i960
5795 @subsection Compare-and-Branch
5797 @cindex i960 compare/branch instructions
5798 @cindex compare/branch instructions, i960
5799 The 960 architectures provide combined Compare-and-Branch instructions
5800 that permit you to store the branch target in the lower 13 bits of the
5801 instruction word itself. However, if you specify a branch target far
5802 enough away that its address won't fit in 13 bits, the assembler can
5803 either issue an error, or convert your Compare-and-Branch instruction
5804 into separate instructions to do the compare and the branch.
5806 @cindex compare and jump expansions, i960
5807 @cindex i960 compare and jump expansions
5808 Whether @code{@value{AS}} gives an error or expands the instruction depends
5809 on two choices you can make: whether you use the @samp{-no-relax} option,
5810 and whether you use a ``Compare and Branch'' instruction or a ``Compare
5811 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
5812 expanded if necessary; the ``Branch'' instructions are expanded when
5813 necessary @emph{unless} you specify @code{-no-relax}---in which case
5814 @code{@value{AS}} gives an error instead.
5816 These are the Compare-and-Branch instructions, their ``Jump'' variants,
5817 and the instruction pairs they may expand into:
5821 @c END TEXI2ROFF-KILL
5824 Branch Jump Expanded to
5825 ------ ------ ------------
5828 cmpibe cmpije cmpi; be
5829 cmpibg cmpijg cmpi; bg
5830 cmpibge cmpijge cmpi; bge
5831 cmpibl cmpijl cmpi; bl
5832 cmpible cmpijle cmpi; ble
5833 cmpibno cmpijno cmpi; bno
5834 cmpibne cmpijne cmpi; bne
5835 cmpibo cmpijo cmpi; bo
5836 cmpobe cmpoje cmpo; be
5837 cmpobg cmpojg cmpo; bg
5838 cmpobge cmpojge cmpo; bge
5839 cmpobl cmpojl cmpo; bl
5840 cmpoble cmpojle cmpo; ble
5841 cmpobne cmpojne cmpo; bne
5847 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
5848 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
5849 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
5850 bbc& & chkbit; bno\cr
5851 bbs& & chkbit; bo\cr
5852 cmpibe& cmpije& cmpi; be\cr
5853 cmpibg& cmpijg& cmpi; bg\cr
5854 cmpibge& cmpijge& cmpi; bge\cr
5855 cmpibl& cmpijl& cmpi; bl\cr
5856 cmpible& cmpijle& cmpi; ble\cr
5857 cmpibno& cmpijno& cmpi; bno\cr
5858 cmpibne& cmpijne& cmpi; bne\cr
5859 cmpibo& cmpijo& cmpi; bo\cr
5860 cmpobe& cmpoje& cmpo; be\cr
5861 cmpobg& cmpojg& cmpo; bg\cr
5862 cmpobge& cmpojge& cmpo; bge\cr
5863 cmpobl& cmpojl& cmpo; bl\cr
5864 cmpoble& cmpojle& cmpo; ble\cr
5865 cmpobne& cmpojne& cmpo; bne\cr}
5867 @c END TEXI2ROFF-KILL
5873 @node M68K-Dependent
5874 @chapter M680x0 Dependent Features
5877 @node Machine Dependencies
5878 @chapter M680x0 Dependent Features
5881 @cindex M680x0 support
5883 * M68K-Opts:: M680x0 Options
5884 * M68K-Syntax:: Syntax
5885 * M68K-Moto-Syntax:: Motorola Syntax
5886 * M68K-Float:: Floating Point
5887 * M68K-Directives:: 680x0 Machine Directives
5888 * M68K-opcodes:: Opcodes
5892 @section M680x0 Options
5894 @cindex options, M680x0
5895 @cindex M680x0 options
5896 The Motorola 680x0 version of @code{@value{AS}} has two machine dependent options.
5897 One shortens undefined references from 32 to 16 bits, while the
5898 other is used to tell @code{@value{AS}} what kind of machine it is
5901 @cindex @code{-l} option, M680x0
5902 You can use the @samp{-l} option to shorten the size of references to undefined
5903 symbols. If you do not use the @samp{-l} option, references to undefined
5904 symbols are wide enough for a full @code{long} (32 bits). (Since
5905 @code{@value{AS}} cannot know where these symbols end up, @code{@value{AS}} can
5906 only allocate space for the linker to fill in later. Since @code{@value{AS}}
5907 does not know how far away these symbols are, it allocates as much space as it
5908 can.) If you use this option, the references are only one word wide (16 bits).
5909 This may be useful if you want the object file to be as small as possible, and
5910 you know that the relevant symbols are always less than 17 bits away.
5912 @cindex @code{-m68000} and related options
5913 @cindex architecture options, M680x0
5914 @cindex M680x0 architecture options
5915 The 680x0 version of @code{@value{AS}} is most frequently used to assemble
5916 programs for the Motorola MC68020 microprocessor. Occasionally it is
5917 used to assemble programs for the mostly similar, but slightly different
5918 MC68000 or MC68010 microprocessors. You can give @code{@value{AS}} the options
5919 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
5920 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
5927 This syntax for the Motorola 680x0 was developed at @sc{mit}.
5929 @cindex M680x0 syntax
5930 @cindex syntax, M680x0
5931 @cindex M680x0 size modifiers
5932 @cindex size modifiers, M680x0
5933 The 680x0 version of @code{@value{AS}} uses syntax compatible with the Sun
5934 assembler. Intervening periods are ignored; for example, @samp{movl} is
5935 equivalent to @samp{move.l}.
5938 If @code{@value{AS}} is compiled with SUN_ASM_SYNTAX defined, it
5939 also allows Sun-style local labels of the form @samp{1$} through
5943 In the following table @dfn{apc} stands for any of the address
5944 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
5945 Program Counter (@samp{pc}), or the zero-address relative to the
5946 program counter (@samp{zpc}).
5948 @cindex M680x0 addressing modes
5949 @cindex addressing modes, M680x0
5950 The following addressing modes are understood:
5953 @samp{#@var{digits}}
5956 @samp{%d0} through @samp{%d7}
5958 @item Address Register
5959 @samp{%a0} through @samp{%a7}@*
5960 @samp{%a7} is also known as @samp{%sp}, i.e. the Stack Pointer. @code{%a6}
5961 is also known as @samp{%fp}, the Frame Pointer.
5963 @item Address Register Indirect
5964 @samp{%a0@@} through @samp{%a7@@}
5966 @item Address Register Postincrement
5967 @samp{%a0@@+} through @samp{%a7@@+}
5969 @item Address Register Predecrement
5970 @samp{%a0@@-} through @samp{%a7@@-}
5972 @item Indirect Plus Offset
5973 @samp{%@var{apc}@@(@var{digits})}
5976 @samp{%@var{apc}@@(@var{digits},%@var{register}:@var{size}:@var{scale})}
5978 or @samp{%@var{apc}@@(%@var{register}:@var{size}:@var{scale})}
5981 @samp{%@var{apc}@@(@var{digits})@@(@var{digits},%@var{register}:@var{size}:@var{scale})}
5983 or @samp{%@var{apc}@@(@var{digits})@@(%@var{register}:@var{size}:@var{scale})}
5986 @samp{%@var{apc}@@(@var{digits},%@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5988 or @samp{%@var{apc}@@(%@var{register}:@var{size}:@var{scale})@@(@var{digits})}
5990 @item Memory Indirect
5991 @samp{%@var{apc}@@(@var{digits})@@(@var{digits})}
5994 @samp{@var{symbol}}, or @samp{@var{digits}}
5996 @c pesch@cygnus.com: gnu, rich concur the following needs careful
5997 @c research before documenting.
5998 , or either of the above followed
5999 by @samp{:b}, @samp{:w}, or @samp{:l}.
6003 For some configurations, especially those where the compiler normally does not
6004 prepend an underscore to the names of user variables, the assembler requires a
6005 @samp{%} before any use of a register name. This is intended to let the
6006 assembler distinguish between C variables and registers named @samp{a0} through
6007 @samp{a7}, and so on. The @samp{%} is always accepted, but is not required for
6008 certain configurations, notably @samp{sun3}.
6010 @node M68K-Moto-Syntax
6011 @section Motorola Syntax
6013 @cindex Motorola syntax for the 680x0
6014 @cindex alternate syntax for the 680x0
6016 The standard Motorola syntax for this chip differs from the syntax already
6017 discussed (@pxref{M68K-Syntax,,Syntax}). @code{@value{AS}} can accept some
6018 forms of Motorola syntax for operands, even if @sc{mit} syntax is used for
6019 other operands in the same instruction. The two kinds of syntax are fully
6020 compatible; our support for Motorola syntax is simply incomplete at present.
6022 @cindex M680x0 syntax
6023 @cindex syntax, M680x0
6024 In particular, you may write or generate M68K assembler with the
6025 following conventions:
6027 (In the following table @dfn{%apc} stands for any of the address registers
6028 (@samp{%a0} through @samp{%a7}), nothing (@samp{}), the Program Counter
6029 (@samp{%pc}), or the zero-address relative to the program counter
6032 @cindex M680x0 addressing modes
6033 @cindex addressing modes, M680x0
6034 The following additional addressing modes are understood:
6036 @item Address Register Indirect
6037 @samp{%a0} through @samp{%a7}@*
6038 @samp{%a7} is also known as @samp{%sp}, i.e. the Stack Pointer. @code{%a6}
6039 is also known as @samp{%fp}, the Frame Pointer.
6041 @item Address Register Postincrement
6042 @samp{(%a0)+} through @samp{(%a7)+}
6044 @item Address Register Predecrement
6045 @samp{-(%a0)} through @samp{-(%a7)}
6047 @item Indirect Plus Offset
6048 @samp{@var{digits}(%@var{apc})}
6051 @samp{@var{digits}(%@var{apc},(%@var{register}.@var{size}*@var{scale}))}@*
6052 or @samp{(%@var{apc},%@var{register}.@var{size}*@var{scale})}@*
6053 In either case, @var{size} and @var{scale} are optional
6054 (@var{scale} defaults to @samp{1}, @var{size} defaults to @samp{l}).
6055 @var{scale} can be @samp{1}, @samp{2}, @samp{4}, or @samp{8}.
6056 @var{size} can be @samp{w} or @samp{l}. @var{scale} is only supported
6057 on the 68020 and greater.
6060 Other, more complex addressing modes permitted in Motorola syntax are not
6064 @section Floating Point
6066 @cindex floating point, M680x0
6067 @cindex M680x0 floating point
6068 @c FIXME is this "not too well tested" crud STILL true?
6069 The floating point code is not too well tested, and may have
6072 Packed decimal (P) format floating literals are not supported.
6073 Feel free to add the code!
6075 The floating point formats generated by directives are these.
6079 @cindex @code{float} directive, M680x0
6080 @code{Single} precision floating point constants.
6083 @cindex @code{double} directive, M680x0
6084 @code{Double} precision floating point constants.
6087 There is no directive to produce regions of memory holding
6088 extended precision numbers, however they can be used as
6089 immediate operands to floating-point instructions. Adding a
6090 directive to create extended precision numbers would not be
6091 hard, but it has not yet seemed necessary.
6093 @node M68K-Directives
6094 @section 680x0 Machine Directives
6096 @cindex M680x0 directives
6097 @cindex directives, M680x0
6098 In order to be compatible with the Sun assembler the 680x0 assembler
6099 understands the following directives.
6103 @cindex @code{data1} directive, M680x0
6104 This directive is identical to a @code{.data 1} directive.
6107 @cindex @code{data2} directive, M680x0
6108 This directive is identical to a @code{.data 2} directive.
6111 @cindex @code{even} directive, M680x0
6112 This directive is identical to a @code{.align 1} directive.
6113 @c Is this true? does it work???
6116 @cindex @code{skip} directive, M680x0
6117 This directive is identical to a @code{.space} directive.
6124 @cindex M680x0 opcodes
6125 @cindex opcodes, M680x0
6126 @cindex instruction set, M680x0
6127 @c pesch@cygnus.com: I don't see any point in the following
6128 @c paragraph. Bugs are bugs; how does saying this
6131 Danger: Several bugs have been found in the opcode table (and
6132 fixed). More bugs may exist. Be careful when using obscure
6137 * M68K-Branch:: Branch Improvement
6138 * M68K-Chars:: Special Characters
6142 @subsection Branch Improvement
6144 @cindex pseudo-opcodes, M680x0
6145 @cindex M680x0 pseudo-opcodes
6146 @cindex branch improvement, M680x0
6147 @cindex M680x0 branch improvement
6148 Certain pseudo opcodes are permitted for branch instructions.
6149 They expand to the shortest branch instruction that reach the
6150 target. Generally these mnemonics are made by substituting @samp{j} for
6151 @samp{b} at the start of a Motorola mnemonic.
6153 The following table summarizes the pseudo-operations. A @code{*} flags
6154 cases that are more fully described after the table:
6158 +-------------------------------------------------
6160 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
6161 +-------------------------------------------------
6162 jbsr |bsrs bsr bsrl jsr jsr
6163 jra |bras bra bral jmp jmp
6164 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
6165 * dbXX |dbXX dbXX dbXX; bra; jmpl
6166 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
6169 NX: negative of condition XX
6172 @center @code{*}---see full description below
6177 These are the simplest jump pseudo-operations; they always map to one
6178 particular machine instruction, depending on the displacement to the
6182 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
6183 where @var{XX} is a conditional branch or condition-code test. The full
6184 list of pseudo-ops in this family is:
6186 jhi jls jcc jcs jne jeq jvc
6187 jvs jpl jmi jge jlt jgt jle
6190 For the cases of non-PC relative displacements and long displacements on
6191 the 68000 or 68010, @code{@value{AS}} issues a longer code fragment in terms of
6192 @var{NX}, the opposite condition to @var{XX}. For example, for the
6193 non-PC relative case:
6205 The full family of pseudo-operations covered here is
6207 dbhi dbls dbcc dbcs dbne dbeq dbvc
6208 dbvs dbpl dbmi dbge dblt dbgt dble
6212 Other than for word and byte displacements, when the source reads
6213 @samp{db@var{XX} foo}, @code{@value{AS}} emits
6222 This family includes
6224 fjne fjeq fjge fjlt fjgt fjle fjf
6225 fjt fjgl fjgle fjnge fjngl fjngle fjngt
6226 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
6227 fjor fjseq fjsf fjsne fjst fjueq fjuge
6228 fjugt fjule fjult fjun
6231 For branch targets that are not PC relative, @code{@value{AS}} emits
6237 when it encounters @samp{fj@var{XX} foo}.
6242 @subsection Special Characters
6244 @cindex special characters, M680x0
6245 @cindex M680x0 immediate character
6246 @cindex immediate character, M680x0
6247 @cindex M680x0 line comment character
6248 @cindex line comment character, M680x0
6249 @cindex comments, M680x0
6250 The immediate character is @samp{#} for Sun compatibility. The
6251 line-comment character is @samp{|}. If a @samp{#} appears at the
6252 beginning of a line, it is treated as a comment unless it looks like
6253 @samp{# line file}, in which case it is treated normally.
6257 @c FIXME! Stop ignoring when filled in.
6262 The 32x32 version of @code{@value{AS}} accepts a @samp{-m32032} option to
6263 specify thiat it is compiling for a 32032 processor, or a
6264 @samp{-m32532} to specify that it is compiling for a 32532 option.
6265 The default (if neither is specified) is chosen when the assembler
6269 I don't know anything about the 32x32 syntax assembled by
6270 @code{@value{AS}}. Someone who undersands the processor (I've never seen
6271 one) and the possible syntaxes should write this section.
6273 @section Floating Point
6274 The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{AS}}
6275 only creates single or double precision values. I don't know if the
6276 32x32 understands extended precision numbers.
6278 @section 32x32 Machine Directives
6279 The 32x32 has no machine dependent directives.
6285 @node Sparc-Dependent
6286 @chapter SPARC Dependent Features
6289 @node Machine Dependencies
6290 @chapter SPARC Dependent Features
6293 @cindex SPARC support
6295 * Sparc-Opts:: Options
6296 * Sparc-Float:: Floating Point
6297 * Sparc-Directives:: Sparc Machine Directives
6303 @cindex options for SPARC
6304 @cindex SPARC options
6305 @cindex architectures, SPARC
6306 @cindex SPARC architectures
6307 The SPARC chip family includes several successive levels (or other
6308 variants) of chip, using the same core instruction set, but including
6309 a few additional instructions at each level.
6311 By default, @code{@value{AS}} assumes the core instruction set (SPARC
6312 v6), but ``bumps'' the architecture level as needed: it switches to
6313 successively higher architectures as it encounters instructions that
6314 only exist in the higher levels.
6317 @item -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite
6323 Use one of the @samp{-A} options to select one of the SPARC
6324 architectures explicitly. If you select an architecture explicitly,
6325 @code{@value{AS}} reports a fatal error if it encounters an instruction
6326 or feature requiring a higher level.
6329 Permit the assembler to ``bump'' the architecture level as required, but
6330 warn whenever it is necessary to switch to another level.
6334 @c FIXME: (sparc) Fill in "syntax" section!
6335 @c subsection syntax
6336 I don't know anything about Sparc syntax. Someone who does
6337 will have to write this section.
6341 @section Floating Point
6343 @cindex floating point, SPARC (@sc{ieee})
6344 @cindex SPARC floating point (@sc{ieee})
6345 The Sparc uses @sc{ieee} floating-point numbers.
6347 @node Sparc-Directives
6348 @section Sparc Machine Directives
6350 @cindex SPARC machine directives
6351 @cindex machine directives, SPARC
6352 The Sparc version of @code{@value{AS}} supports the following additional
6357 @cindex @code{align} directive, SPARC
6358 This must be followed by the desired alignment in bytes.
6361 @cindex @code{common} directive, SPARC
6362 This must be followed by a symbol name, a positive number, and
6363 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
6364 syntax is different.
6367 @cindex @code{half} directive, SPARC
6368 This is functionally identical to @code{.short}.
6371 @cindex @code{proc} directive, SPARC
6372 This directive is ignored. Any text following it on the same
6373 line is also ignored.
6376 @cindex @code{reserve} directive, SPARC
6377 This must be followed by a symbol name, a positive number, and
6378 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
6379 syntax is different.
6382 @cindex @code{seg} directive, SPARC
6383 This must be followed by @code{"text"}, @code{"data"}, or
6384 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
6388 @cindex @code{skip} directive, SPARC
6389 This is functionally identical to the @code{.space} directive.
6392 @cindex @code{word} directive, SPARC
6393 On the Sparc, the @code{.word} directive produces 32 bit values,
6394 instead of the 16 bit values it produces on many other machines.
6397 @cindex @code{xword} directive, SPARC
6398 On the Sparc V9 processor, the @code{.xword} directive produces
6406 @node i386-Dependent
6407 @chapter 80386 Dependent Features
6410 @node Machine Dependencies
6411 @chapter 80386 Dependent Features
6414 @cindex i386 support
6415 @cindex i80306 support
6417 * i386-Options:: Options
6418 * i386-Syntax:: AT&T Syntax versus Intel Syntax
6419 * i386-Opcodes:: Opcode Naming
6420 * i386-Regs:: Register Naming
6421 * i386-prefixes:: Opcode Prefixes
6422 * i386-Memory:: Memory References
6423 * i386-jumps:: Handling of Jump Instructions
6424 * i386-Float:: Floating Point
6425 * i386-16bit:: Writing 16-bit Code
6426 * i386-Notes:: Notes
6432 @cindex options for i386 (none)
6433 @cindex i386 options (none)
6434 The 80386 has no machine dependent options.
6437 @section AT&T Syntax versus Intel Syntax
6439 @cindex i386 syntax compatibility
6440 @cindex syntax compatibility, i386
6441 In order to maintain compatibility with the output of @code{@value{GCC}},
6442 @code{@value{AS}} supports AT&T System V/386 assembler syntax. This is quite
6443 different from Intel syntax. We mention these differences because
6444 almost all 80386 documents used only Intel syntax. Notable differences
6445 between the two syntaxes are:
6449 @cindex immediate operands, i386
6450 @cindex i386 immediate operands
6451 @cindex register operands, i386
6452 @cindex i386 register operands
6453 @cindex jump/call operands, i386
6454 @cindex i386 jump/call operands
6455 @cindex operand delimiters, i386
6456 AT&T immediate operands are preceded by @samp{$}; Intel immediate
6457 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
6458 AT&T register operands are preceded by @samp{%}; Intel register operands
6459 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
6460 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
6463 @cindex i386 source, destination operands
6464 @cindex source, destination operands; i386
6465 AT&T and Intel syntax use the opposite order for source and destination
6466 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
6467 @samp{source, dest} convention is maintained for compatibility with
6468 previous Unix assemblers.
6471 @cindex opcode suffixes, i386
6472 @cindex sizes operands, i386
6473 @cindex i386 size suffixes
6474 In AT&T syntax the size of memory operands is determined from the last
6475 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
6476 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
6477 memory references. Intel syntax accomplishes this by prefixes memory
6478 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
6479 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
6480 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
6483 @cindex return instructions, i386
6484 @cindex i386 jump, call, return
6485 Immediate form long jumps and calls are
6486 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
6488 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
6490 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
6491 @samp{ret far @var{stack-adjust}}.
6494 @cindex sections, i386
6495 @cindex i386 sections
6496 The AT&T assembler does not provide support for multiple section
6497 programs. Unix style systems expect all programs to be single sections.
6501 @section Opcode Naming
6503 @cindex i386 opcode naming
6504 @cindex opcode naming, i386
6505 Opcode names are suffixed with one character modifiers which specify the
6506 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
6507 byte, word, and long operands. If no suffix is specified by an
6508 instruction and it contains no memory operands then @code{@value{AS}} tries to
6509 fill in the missing suffix based on the destination register operand
6510 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
6511 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
6512 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
6513 assembler which assumes that a missing opcode suffix implies long
6514 operand size. (This incompatibility does not affect compiler output
6515 since compilers always explicitly specify the opcode suffix.)
6517 Almost all opcodes have the same names in AT&T and Intel format. There
6518 are a few exceptions. The sign extend and zero extend instructions need
6519 two sizes to specify them. They need a size to sign/zero extend
6520 @emph{from} and a size to zero extend @emph{to}. This is accomplished
6521 by using two opcode suffixes in AT&T syntax. Base names for sign extend
6522 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
6523 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
6524 suffixes are tacked on to this base name, the @emph{from} suffix before
6525 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
6526 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
6527 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
6528 and @samp{wl} (from word to long).
6530 @cindex conversion instructions, i386
6531 @cindex i386 conversion instructions
6532 The Intel-syntax conversion instructions
6536 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
6539 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
6542 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
6545 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
6549 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
6550 AT&T naming. @code{@value{AS}} accepts either naming for these instructions.
6552 @cindex jump instructions, i386
6553 @cindex call instructions, i386
6554 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
6555 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
6559 @section Register Naming
6561 @cindex i386 registers
6562 @cindex registers, i386
6563 Register operands are always prefixes with @samp{%}. The 80386 registers
6568 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
6569 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
6570 frame pointer), and @samp{%esp} (the stack pointer).
6573 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
6574 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
6577 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
6578 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
6579 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
6580 @samp{%cx}, and @samp{%dx})
6583 the 6 section registers @samp{%cs} (code section), @samp{%ds}
6584 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
6588 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
6592 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
6593 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
6596 the 2 test registers @samp{%tr6} and @samp{%tr7}.
6599 the 8 floating point register stack @samp{%st} or equivalently
6600 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
6601 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
6605 @section Opcode Prefixes
6607 @cindex i386 opcode prefixes
6608 @cindex opcode prefixes, i386
6609 @cindex prefixes, i386
6610 Opcode prefixes are used to modify the following opcode. They are used
6611 to repeat string instructions, to provide section overrides, to perform
6612 bus lock operations, and to give operand and address size (16-bit
6613 operands are specified in an instruction by prefixing what would
6614 normally be 32-bit operands with a ``operand size'' opcode prefix).
6615 Opcode prefixes are usually given as single-line instructions with no
6616 operands, and must directly precede the instruction they act upon. For
6617 example, the @samp{scas} (scan string) instruction is repeated with:
6623 Here is a list of opcode prefixes:
6627 @cindex section override prefixes, i386
6628 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
6629 @samp{fs}, @samp{gs}. These are automatically added by specifying
6630 using the @var{section}:@var{memory-operand} form for memory references.
6633 @cindex size prefixes, i386
6634 Operand/Address size prefixes @samp{data16} and @samp{addr16}
6635 change 32-bit operands/addresses into 16-bit operands/addresses. Note
6636 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
6637 are not supported (yet).
6640 @cindex bus lock prefixes, i386
6641 @cindex inhibiting interrupts, i386
6642 The bus lock prefix @samp{lock} inhibits interrupts during
6643 execution of the instruction it precedes. (This is only valid with
6644 certain instructions; see a 80386 manual for details).
6647 @cindex coprocessor wait, i386
6648 The wait for coprocessor prefix @samp{wait} waits for the
6649 coprocessor to complete the current instruction. This should never be
6650 needed for the 80386/80387 combination.
6653 @cindex repeat prefixes, i386
6654 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
6655 to string instructions to make them repeat @samp{%ecx} times.
6659 @section Memory References
6661 @cindex i386 memory references
6662 @cindex memory references, i386
6663 An Intel syntax indirect memory reference of the form
6666 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
6670 is translated into the AT&T syntax
6673 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
6677 where @var{base} and @var{index} are the optional 32-bit base and
6678 index registers, @var{disp} is the optional displacement, and
6679 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
6680 to calculate the address of the operand. If no @var{scale} is
6681 specified, @var{scale} is taken to be 1. @var{section} specifies the
6682 optional section register for the memory operand, and may override the
6683 default section register (see a 80386 manual for section register
6684 defaults). Note that section overrides in AT&T syntax @emph{must} have
6685 be preceded by a @samp{%}. If you specify a section override which
6686 coincides with the default section register, @code{@value{AS}} does @emph{not}
6687 output any section register override prefixes to assemble the given
6688 instruction. Thus, section overrides can be specified to emphasize which
6689 section register is used for a given memory operand.
6691 Here are some examples of Intel and AT&T style memory references:
6694 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
6695 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
6696 missing, and the default section is used (@samp{%ss} for addressing with
6697 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
6699 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
6700 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
6701 @samp{foo}. All other fields are missing. The section register here
6702 defaults to @samp{%ds}.
6704 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
6705 This uses the value pointed to by @samp{foo} as a memory operand.
6706 Note that @var{base} and @var{index} are both missing, but there is only
6707 @emph{one} @samp{,}. This is a syntactic exception.
6709 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
6710 This selects the contents of the variable @samp{foo} with section
6711 register @var{section} being @samp{%gs}.
6714 Absolute (as opposed to PC relative) call and jump operands must be
6715 prefixed with @samp{*}. If no @samp{*} is specified, @code{@value{AS}}
6716 always chooses PC relative addressing for jump/call labels.
6718 Any instruction that has a memory operand @emph{must} specify its size (byte,
6719 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
6723 @section Handling of Jump Instructions
6725 @cindex jump optimization, i386
6726 @cindex i386 jump optimization
6727 Jump instructions are always optimized to use the smallest possible
6728 displacements. This is accomplished by using byte (8-bit) displacement
6729 jumps whenever the target is sufficiently close. If a byte displacement
6730 is insufficient a long (32-bit) displacement is used. We do not support
6731 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
6732 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
6733 @samp{%eip} to 16 bits after the word displacement is added.
6735 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
6736 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in byte
6737 displacements, so that if you use these instructions (@code{@value{GCC}} does
6738 not use them) you may get an error message (and incorrect code). The AT&T
6739 80386 assembler tries to get around this problem by expanding @samp{jcxz foo}
6750 @section Floating Point
6752 @cindex i386 floating point
6753 @cindex floating point, i386
6754 All 80387 floating point types except packed BCD are supported.
6755 (BCD support may be added without much difficulty). These data
6756 types are 16-, 32-, and 64- bit integers, and single (32-bit),
6757 double (64-bit), and extended (80-bit) precision floating point.
6758 Each supported type has an opcode suffix and a constructor
6759 associated with it. Opcode suffixes specify operand's data
6760 types. Constructors build these data types into memory.
6764 @cindex @code{float} directive, i386
6765 @cindex @code{single} directive, i386
6766 @cindex @code{double} directive, i386
6767 @cindex @code{tfloat} directive, i386
6768 Floating point constructors are @samp{.float} or @samp{.single},
6769 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
6770 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
6771 @samp{t} stands for temporary real, and that the 80387 only supports
6772 this format via the @samp{fldt} (load temporary real to stack top) and
6773 @samp{fstpt} (store temporary real and pop stack) instructions.
6776 @cindex @code{word} directive, i386
6777 @cindex @code{long} directive, i386
6778 @cindex @code{int} directive, i386
6779 @cindex @code{quad} directive, i386
6780 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
6781 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
6782 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
6783 (quad). As with the temporary real format the 64-bit @samp{q} format is
6784 only present in the @samp{fildq} (load quad integer to stack top) and
6785 @samp{fistpq} (store quad integer and pop stack) instructions.
6788 Register to register operations do not require opcode suffixes,
6789 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
6791 @cindex i386 @code{fwait} instruction
6792 @cindex @code{fwait instruction}, i386
6793 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
6794 instructions are almost never needed (this is not the case for the
6795 80286/80287 and 8086/8087 combinations). Therefore, @code{@value{AS}} suppresses
6796 the @samp{fwait} instruction whenever it is implicitly selected by one
6797 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
6798 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
6799 instructions are made equivalent to @samp{f@dots{}} instructions. If
6800 @samp{fwait} is desired it must be explicitly coded.
6803 @section Writing 16-bit Code
6805 @cindex i386 16-bit code
6806 @cindex 16-bit code, i386
6807 @cindex real-mode code, i386
6808 @cindex @code{code16} directive, i386
6809 @cindex @code{code32} directive, i386
6810 While GAS normally writes only ``pure'' 32-bit i386 code, it has limited
6811 support for writing code to run in real mode or in 16-bit protected mode
6812 code segments. To do this, insert a @samp{.code16} directive before the
6813 assembly language instructions to be run in 16-bit mode. You can switch
6814 GAS back to writing normal 32-bit code with the @samp{.code32} directive.
6816 GAS understands exactly the same assembly language syntax in 16-bit mode as
6817 in 32-bit mode. The function of any given instruction is exactly the same
6818 regardless of mode, as long as the resulting object code is executed in the
6819 mode for which GAS wrote it. So, for example, the @samp{ret} mnemonic
6820 produces a 32-bit return instruction regardless of whether it is to be run
6821 in 16-bit or 32-bit mode. (If GAS is in 16-bit mode, it will add an
6822 operand size prefix to the instruction to force it to be a 32-bit return.)
6824 This means, for one thing, that you can use GNU CC to write code to be run
6825 in real mode or 16-bit protected mode. Just insert the statement
6826 @samp{asm(".code16");} at the beginning of your C source file, and while
6827 GNU CC will still be generating 32-bit code, GAS will automatically add all
6828 the necessary size prefixes to make that code run in 16-bit mode. Of
6829 course, since GNU CC only writes small-model code (it doesn't know how to
6830 attach segment selectors to pointers like native x86 compilers do), any
6831 16-bit code you write with GNU CC will essentially be limited to a 64K
6832 address space. Also, there will be a code size and performance penalty
6833 due to all the extra address and operand size prefixes GAS has to add to
6836 Note that placing GAS in 16-bit mode does not mean that the resulting
6837 code will necessarily run on a 16-bit pre-80386 processor. To write code
6838 that runs on such a processor, you would have to refrain from using
6839 @emph{any} 32-bit constructs which require GAS to output address or
6840 operand size prefixes. At the moment this would be rather difficult,
6841 because GAS currently supports @emph{only} 32-bit addressing modes: when
6842 writing 16-bit code, it @emph{always} outputs address size prefixes for any
6843 instruction that uses a non-register addressing mode. So you can write
6844 code that runs on 16-bit processors, but only if that code never references
6850 @cindex i386 @code{mul}, @code{imul} instructions
6851 @cindex @code{mul} instruction, i386
6852 @cindex @code{imul} instruction, i386
6853 There is some trickery concerning the @samp{mul} and @samp{imul}
6854 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
6855 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
6856 for @samp{imul}) can be output only in the one operand form. Thus,
6857 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
6858 the expanding multiply would clobber the @samp{%edx} register, and this
6859 would confuse @code{@value{GCC}} output. Use @samp{imul %ebx} to get the
6860 64-bit product in @samp{%edx:%eax}.
6862 We have added a two operand form of @samp{imul} when the first operand
6863 is an immediate mode expression and the second operand is a register.
6864 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
6865 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
6872 @node Z8000-Dependent
6873 @chapter Z8000 Dependent Features
6876 @node Machine Dependencies
6877 @chapter Z8000 Dependent Features
6880 @cindex Z8000 support
6881 The Z8000 @value{AS} supports both members of the Z8000 family: the
6882 unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with
6885 When the assembler is in unsegmented mode (specified with the
6886 @code{unsegm} directive), an address takes up one word (16 bit)
6887 sized register. When the assembler is in segmented mode (specified with
6888 the @code{segm} directive), a 24-bit address takes up a long (32 bit)
6889 register. @xref{Z8000 Directives,,Assembler Directives for the Z8000},
6890 for a list of other Z8000 specific assembler directives.
6893 * Z8000 Options:: No special command-line options for Z8000
6894 * Z8000 Syntax:: Assembler syntax for the Z8000
6895 * Z8000 Directives:: Special directives for the Z8000
6896 * Z8000 Opcodes:: Opcodes
6902 @cindex Z8000 options
6903 @cindex options, Z8000
6904 @code{@value{AS}} has no additional command-line options for the Zilog
6910 * Z8000-Chars:: Special Characters
6911 * Z8000-Regs:: Register Names
6912 * Z8000-Addressing:: Addressing Modes
6916 @subsection Special Characters
6918 @cindex line comment character, Z8000
6919 @cindex Z8000 line comment character
6920 @samp{!} is the line comment character.
6922 @cindex line separator, Z8000
6923 @cindex statement separator, Z8000
6924 @cindex Z8000 line separator
6925 You can use @samp{;} instead of a newline to separate statements.
6928 @subsection Register Names
6930 @cindex Z8000 registers
6931 @cindex registers, Z8000
6932 The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer
6933 to different sized groups of registers by register number, with the
6934 prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and
6935 @samp{rq} for 64 bit registers. You can also refer to the contents of
6936 the first eight (of the sixteen 16 bit registers) by bytes. They are
6937 named @samp{r@var{n}h} and @samp{r@var{n}l}.
6940 @exdent @emph{byte registers}
6941 r0l r0h r1h r1l r2h r2l r3h r3l
6942 r4h r4l r5h r5l r6h r6l r7h r7l
6944 @exdent @emph{word registers}
6945 r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15
6947 @exdent @emph{long word registers}
6948 rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14
6950 @exdent @emph{quad word registers}
6954 @node Z8000-Addressing
6955 @subsection Addressing Modes
6957 @cindex addressing modes, Z8000
6958 @cindex Z800 addressing modes
6959 @value{AS} understands the following addressing modes for the Z8000:
6969 Direct: the 16 bit or 24 bit address (depending on whether the assembler
6970 is in segmented or unsegmented mode) of the operand is in the instruction.
6972 @item address(r@var{n})
6973 Indexed: the 16 or 24 bit address is added to the 16 bit register to produce
6974 the final address in memory of the operand.
6976 @item r@var{n}(#@var{imm})
6977 Base Address: the 16 or 24 bit register is added to the 16 bit sign
6978 extended immediate displacement to produce the final address in memory
6981 @item r@var{n}(r@var{m})
6982 Base Index: the 16 or 24 bit register r@var{n} is added to the sign
6983 extended 16 bit index register r@var{m} to produce the final address in
6984 memory of the operand.
6987 Immediate data @var{xx}.
6990 @node Z8000 Directives
6991 @section Assembler Directives for the Z8000
6993 @cindex Z8000 directives
6994 @cindex directives, Z8000
6995 The Z8000 port of @value{AS} includes these additional assembler directives,
6996 for compatibility with other Z8000 assemblers. As shown, these do not
6997 begin with @samp{.} (unlike the ordinary @value{AS} directives).
7002 Generates code for the segmented Z8001.
7006 Generates code for the unsegmented Z8002.
7010 Synonym for @code{.file}
7014 Synonum for @code{.global}
7018 Synonym for @code{.word}
7022 Synonym for @code{.long}
7026 Synonym for @code{.byte}
7030 Assemble a string. @code{sval} expects one string literal, delimited by
7031 single quotes. It assembles each byte of the string into consecutive
7032 addresses. You can use the escape sequence @samp{%@var{xx}} (where
7033 @var{xx} represents a two-digit hexadecimal number) to represent the
7034 character whose @sc{ascii} value is @var{xx}. Use this feature to
7035 describe single quote and other characters that may not appear in string
7036 literals as themselves. For example, the C statement @w{@samp{char *a =
7037 "he said \"it's 50% off\"";}} is represented in Z8000 assembly language
7038 (shown with the assembler output in hex at the left) as
7042 @let@nonarrowing=@comment
7045 68652073 sval 'he said %22it%27s 50%25 off%22%00'
7058 synonym for @code{.section}
7062 synonym for @code{.space}
7066 synonym for @code{.align 1}
7072 @cindex Z8000 opcode summary
7073 @cindex opcode summary, Z8000
7074 @cindex mnemonics, Z8000
7075 @cindex instruction summary, Z8000
7076 For detailed information on the Z8000 machine instruction set, see
7077 @cite{Z8000 Technical Manual}.
7080 @c this table, due to the multi-col faking and hardcoded order, looks silly
7081 @c except in smallbook. See comments below "@set SMALL" near top of this file.
7083 The following table summarizes the opcodes and their arguments:
7086 @let@nonarrowing=@comment
7090 rs @r{16 bit source register}
7091 rd @r{16 bit destination register}
7092 rbs @r{8 bit source register}
7093 rbd @r{8 bit destination register}
7094 rrs @r{32 bit source register}
7095 rrd @r{32 bit destination register}
7096 rqs @r{64 bit source register}
7097 rqd @r{64 bit destination register}
7098 addr @r{16/24 bit address}
7099 imm @r{immediate data}
7101 adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc
7102 adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc
7103 add rd,@@rs clrb rbd dab rbd
7104 add rd,addr com @@rd dbjnz rbd,disp7
7105 add rd,addr(rs) com addr dec @@rd,imm4m1
7106 add rd,imm16 com addr(rd) dec addr(rd),imm4m1
7107 add rd,rs com rd dec addr,imm4m1
7108 addb rbd,@@rs comb @@rd dec rd,imm4m1
7109 addb rbd,addr comb addr decb @@rd,imm4m1
7110 addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1
7111 addb rbd,imm8 comb rbd decb addr,imm4m1
7112 addb rbd,rbs comflg flags decb rbd,imm4m1
7113 addl rrd,@@rs cp @@rd,imm16 di i2
7114 addl rrd,addr cp addr(rd),imm16 div rrd,@@rs
7115 addl rrd,addr(rs) cp addr,imm16 div rrd,addr
7116 addl rrd,imm32 cp rd,@@rs div rrd,addr(rs)
7117 addl rrd,rrs cp rd,addr div rrd,imm16
7118 and rd,@@rs cp rd,addr(rs) div rrd,rs
7119 and rd,addr cp rd,imm16 divl rqd,@@rs
7120 and rd,addr(rs) cp rd,rs divl rqd,addr
7121 and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs)
7122 and rd,rs cpb addr(rd),imm8 divl rqd,imm32
7123 andb rbd,@@rs cpb addr,imm8 divl rqd,rrs
7124 andb rbd,addr cpb rbd,@@rs djnz rd,disp7
7125 andb rbd,addr(rs) cpb rbd,addr ei i2
7126 andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs
7127 andb rbd,rbs cpb rbd,imm8 ex rd,addr
7128 bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs)
7129 bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs
7130 bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs
7131 bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr
7132 bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs)
7133 bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs
7134 bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8
7135 bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8
7136 bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8
7137 bitb rbd,rs cpl rrd,@@rs ext8f imm8
7138 bpt cpl rrd,addr exts rrd
7139 call @@rd cpl rrd,addr(rs) extsb rd
7140 call addr cpl rrd,imm32 extsl rqd
7141 call addr(rd) cpl rrd,rrs halt
7142 calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs
7143 clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16
7144 clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs
7145 clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16
7146 clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1
7147 clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1
7148 inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs)
7149 inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16
7150 incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs
7151 incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs
7152 incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr
7153 incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs)
7154 ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32
7155 indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs
7156 inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd
7157 inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr
7158 iret ldib @@rd,@@rs,rr neg addr(rd)
7159 jp cc,@@rd ldir @@rd,@@rs,rr neg rd
7160 jp cc,addr ldirb @@rd,@@rs,rr negb @@rd
7161 jp cc,addr(rd) ldk rd,imm4 negb addr
7162 jr cc,disp8 ldl @@rd,rrs negb addr(rd)
7163 ld @@rd,imm16 ldl addr(rd),rrs negb rbd
7164 ld @@rd,rs ldl addr,rrs nop
7165 ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs
7166 ld addr(rd),rs ldl rd(rx),rrs or rd,addr
7167 ld addr,imm16 ldl rrd,@@rs or rd,addr(rs)
7168 ld addr,rs ldl rrd,addr or rd,imm16
7169 ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs
7170 ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs
7171 ld rd,@@rs ldl rrd,rrs orb rbd,addr
7172 ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs)
7173 ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8
7174 ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs
7175 ld rd,rs ldm addr(rd),rs,n out @@rd,rs
7176 ld rd,rs(imm16) ldm addr,rs,n out imm16,rs
7177 ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs
7178 lda rd,addr ldm rd,addr(rs),n outb imm16,rbs
7179 lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra
7180 lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba
7181 lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra
7182 ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra
7183 ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs
7184 ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs
7185 ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs
7186 ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs
7187 ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs
7188 ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs
7189 ldb rbd,@@rs mbit popl addr,@@rs
7190 ldb rbd,addr mreq rd popl rrd,@@rs
7191 ldb rbd,addr(rs) mres push @@rd,@@rs
7192 ldb rbd,imm8 mset push @@rd,addr
7193 ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs)
7194 ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16
7195 push @@rd,rs set addr,imm4 subl rrd,imm32
7196 pushl @@rd,@@rs set rd,imm4 subl rrd,rrs
7197 pushl @@rd,addr set rd,rs tcc cc,rd
7198 pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd
7199 pushl @@rd,rrs setb addr(rd),imm4 test @@rd
7200 res @@rd,imm4 setb addr,imm4 test addr
7201 res addr(rd),imm4 setb rbd,imm4 test addr(rd)
7202 res addr,imm4 setb rbd,rs test rd
7203 res rd,imm4 setflg imm4 testb @@rd
7204 res rd,rs sinb rbd,imm16 testb addr
7205 resb @@rd,imm4 sinb rd,imm16 testb addr(rd)
7206 resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd
7207 resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd
7208 resb rbd,imm4 sinib @@rd,@@rs,ra testl addr
7209 resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd)
7210 resflg imm4 sla rd,imm8 testl rrd
7211 ret cc slab rbd,imm8 trdb @@rd,@@rs,rba
7212 rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba
7213 rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr
7214 rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr
7215 rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr
7216 rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr
7217 rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr
7218 rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr
7219 rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd
7220 rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr
7221 rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd)
7222 rsvd36 sra rd,imm8 tset rd
7223 rsvd38 srab rbd,imm8 tsetb @@rd
7224 rsvd78 sral rrd,imm8 tsetb addr
7225 rsvd7e srl rd,imm8 tsetb addr(rd)
7226 rsvd9d srlb rbd,imm8 tsetb rbd
7227 rsvd9f srll rrd,imm8 xor rd,@@rs
7228 rsvdb9 sub rd,@@rs xor rd,addr
7229 rsvdbf sub rd,addr xor rd,addr(rs)
7230 sbc rd,rs sub rd,addr(rs) xor rd,imm16
7231 sbcb rbd,rbs sub rd,imm16 xor rd,rs
7232 sc imm8 sub rd,rs xorb rbd,@@rs
7233 sda rd,rs subb rbd,@@rs xorb rbd,addr
7234 sdab rbd,rs subb rbd,addr xorb rbd,addr(rs)
7235 sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8
7236 sdl rd,rs subb rbd,imm8 xorb rbd,rbs
7237 sdlb rbd,rs subb rbd,rbs xorb rbd,rbs
7238 sdll rrd,rs subl rrd,@@rs
7239 set @@rd,imm4 subl rrd,addr
7240 set addr(rd),imm4 subl rrd,addr(rs)
7252 @node MIPS-Dependent
7253 @chapter MIPS Dependent Features
7256 @node Machine Dependencies
7257 @chapter MIPS Dependent Features
7264 @sc{gnu} @code{@value{AS}} for @sc{mips} architectures supports the @sc{mips}
7265 @sc{r2000}, @sc{r3000}, @sc{r4000} and @sc{r6000} processors. For information
7266 about the @sc{mips} instruction set, see @cite{MIPS RISC Architecture}, by Kane
7267 and Heindrich (Prentice-Hall). For an overview of @sc{mips} assembly
7268 conventions, see ``Appendix D: Assembly Language Programming'' in the same
7272 * MIPS Opts:: Assembler options
7273 * MIPS Object:: ECOFF object code
7274 * MIPS Stabs:: Directives for debugging information
7275 * MIPS ISA:: Directives to override the ISA level
7279 @section Assembler options
7281 The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support these
7285 @cindex @code{-G} option (MIPS)
7287 This option sets the largest size of an object that can be referenced
7288 implicitly with the @code{gp} register. It is only accepted for targets
7289 that use @sc{ecoff} format. The default value is 8.
7291 @cindex @code{-EB} option (MIPS)
7292 @cindex @code{-EL} option (MIPS)
7293 @cindex MIPS big-endian output
7294 @cindex MIPS little-endian output
7295 @cindex big-endian output, MIPS
7296 @cindex little-endian output, MIPS
7299 Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or
7300 little-endian output at run time (unlike the other @sc{gnu} development
7301 tools, which must be configured for one or the other). Use @samp{-EB}
7302 to select big-endian output, and @samp{-EL} for little-endian.
7304 @cindex MIPS architecture options
7308 Generate code for a particular MIPS Instruction Set Architecture level.
7309 @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
7310 @samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000}
7311 processor. You can also switch instruction sets during the assembly; see
7312 @ref{MIPS ISA,, Directives to override the ISA level}.
7316 Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept
7317 the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
7318 instructions around accesses to the @samp{HI} and @samp{LO} registers.
7319 @samp{-no-m4650} turns off this option.
7321 @item -mcpu=@var{CPU}
7322 Generate code for a particular MIPS cpu. This has little effect on the
7323 assembler, but it is passed by @code{@value{GCC}}.
7325 @cindex @code{-nocpp} ignored (MIPS)
7327 This option is ignored. It is accepted for command-line compatibility with
7328 other assemblers, which use it to turn off C style preprocessing. With
7329 @sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the
7330 @sc{gnu} assembler itself never runs the C preprocessor.
7334 @c FIXME! (1) reflect these options (next item too) in option summaries;
7335 @c (2) stop teasing, say _which_ instructions expanded _how_.
7336 @code{@value{AS}} automatically macro expands certain division and
7337 multiplication instructions to check for overflow and division by zero. This
7338 option causes @code{@value{AS}} to generate code to take a trap exception
7339 rather than a break exception when an error is detected. The trap instructions
7340 are only supported at Instruction Set Architecture level 2 and higher.
7344 Generate code to take a break exception rather than a trap exception when an
7345 error is detected. This is the default.
7349 @section MIPS ECOFF object code
7351 @cindex ECOFF sections
7352 @cindex MIPS ECOFF sections
7353 Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections
7354 besides the usual @code{.text}, @code{.data} and @code{.bss}. The
7355 additional sections are @code{.rdata}, used for read-only data,
7356 @code{.sdata}, used for small data, and @code{.sbss}, used for small
7359 @cindex small objects, MIPS ECOFF
7360 @cindex @code{gp} register, MIPS
7361 When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28})
7362 register to form the address of a ``small object''. Any object in the
7363 @code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense.
7364 For external objects, or for objects in the @code{.bss} section, you can use
7365 the @code{@value{GCC}} @samp{-G} option to control the size of objects addressed via
7366 @code{$gp}; the default value is 8, meaning that a reference to any object
7367 eight bytes or smaller uses @code{$gp}. Passing @samp{-G 0} to
7368 @code{@value{AS}} prevents it from using the @code{$gp} register on the basis
7369 of object size (but the assembler uses @code{$gp} for objects in @code{.sdata}
7370 or @code{sbss} in any case). The size of an object in the @code{.bss} section
7371 is set by the @code{.comm} or @code{.lcomm} directive that defines it. The
7372 size of an external object may be set with the @code{.extern} directive. For
7373 example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes
7374 in length, whie leaving @code{sym} otherwise undefined.
7376 Using small @sc{ecoff} objects requires linker support, and assumes that the
7377 @code{$gp} register is correctly initialized (normally done automatically by
7378 the startup code). @sc{mips} @sc{ecoff} assembly code must not modify the
7379 @code{$gp} register.
7382 @section Directives for debugging information
7384 @cindex MIPS debugging directives
7385 @sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for
7386 generating debugging information which are not support by traditional @sc{mips}
7387 assemblers. These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file},
7388 @code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val},
7389 @code{.stabd}, @code{.stabn}, and @code{.stabs}. The debugging information
7390 generated by the three @code{.stab} directives can only be read by @sc{gdb},
7391 not by traditional @sc{mips} debuggers (this enhancement is required to fully
7392 support C++ debugging). These directives are primarily used by compilers, not
7393 assembly language programmers!
7396 @section Directives to override the ISA level
7398 @cindex MIPS ISA override
7399 @kindex @code{.set mips@var{n}}
7400 @sc{gnu} @code{@value{AS}} supports an additional directive to change the
7401 @sc{mips} Instruction Set Architecture level on the fly: @code{.set
7402 mips@var{n}}. @var{n} should be a number from 0 to 3. A value from 1 to 3
7403 makes the assembler accept instructions for the corresponding @sc{isa} level,
7404 from that point on in the assembly. @code{.set mips@var{n}} affects not only
7405 which instructions are permitted, but also how certain macros are expanded.
7406 @code{.set mips0} restores the @sc{isa} level to its original level: either the
7407 level you selected with command line options, or the default for your
7408 configuration. You can use this feature to permit specific @sc{r4000}
7409 instructions while assembling in 32 bit mode. Use this directive with care!
7411 Traditional @sc{mips} assemblers do not support this directive.
7415 @c reverse effect of @down at top of generic Machine-Dep chapter
7419 @node Acknowledgements
7420 @chapter Acknowledgements
7422 If you have contributed to @code{@value{AS}} and your name isn't listed here,
7423 it is not meant as a slight. We just don't know about it. Send mail to the
7424 maintainer, and we'll correct the situation. Currently (January 1994), the
7425 maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
7427 Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any more
7430 Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
7431 information and the 68k series machines, most of the preprocessing pass, and
7432 extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}.
7434 K. Richard Pixley maintained GAS for a while, adding various enhancements and
7435 many bug fixes, including merging support for several processors, breaking GAS
7436 up to handle multiple object file format back ends (including heavy rewrite,
7437 testing, an integration of the coff and b.out back ends), adding configuration
7438 including heavy testing and verification of cross assemblers and file splits
7439 and renaming, converted GAS to strictly ANSI C including full prototypes, added
7440 support for m680[34]0 and cpu32, did considerable work on i960 including a COFF
7441 port (including considerable amounts of reverse engineering), a SPARC opcode
7442 file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know''
7443 assertions and made them work, much other reorganization, cleanup, and lint.
7445 Ken Raeburn wrote the high-level BFD interface code to replace most of the code
7446 in format-specific I/O modules.
7448 The original VMS support was contributed by David L. Kashtan. Eric Youngdale
7449 has done much work with it since.
7451 The Intel 80386 machine description was written by Eliot Dresselhaus.
7453 Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
7455 The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
7456 University and Torbjorn Granlund of the Swedish Institute of Computer Science.
7458 Keith Knowles at the Open Software Foundation wrote the original MIPS back end
7459 (@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support
7460 (which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to
7461 support a.out format.
7463 Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k,
7464 tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
7465 Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
7466 use BFD for some low-level operations, for use with the H8/300 and AMD 29k
7469 John Gilmore built the AMD 29000 support, added @code{.include} support, and
7470 simplified the configuration of which versions accept which directives. He
7471 updated the 68k machine description so that Motorola's opcodes always produced
7472 fixed-size instructions (e.g. @code{jsr}), while synthetic instructions
7473 remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested
7474 cross-compilation support, and one bug in relaxation that took a week and
7475 required the proverbial one-bit fix.
7477 Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
7478 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
7479 added support for MIPS ECOFF and ELF targets, and made a few other minor
7482 Steve Chamberlain made @code{@value{AS}} able to generate listings.
7484 Hewlett-Packard contributed support for the HP9000/300.
7486 Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
7487 along with a fairly extensive HPPA testsuite (for both SOM and ELF object
7488 formats). This work was supported by both the Center for Software Science at
7489 the University of Utah and Cygnus Support.
7491 Support for ELF format files has been worked on by Mark Eichin of Cygnus
7492 Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
7493 Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
7494 Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
7495 and some initial 64-bit support).
7497 Several engineers at Cygnus Support have also provided many small bug fixes and
7498 configuration enhancements.
7500 Many others have contributed large or small bugfixes and enhancements. If
7501 you have contributed significant work and are not mentioned on this list, and
7502 want to be, let us know. Some of the history has been lost; we are not
7503 intentionally leaving anyone out.