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][=file] ] [ -D ] [ -f ] [ --help ]
198 [ -I @var{dir} ] [ -J ] [ -K ] [ -L ] [ -o @var{objfile} ]
199 [ -R ] [ --statistics ] [ -v ] [ -version ] [ --version ]
200 [ -W ] [ -w ] [ -x ] [ -Z ]
202 @c am29k has no machine-dependent assembler options
204 @c start-sanitize-arc
206 [ -mbig-endian | -mlittle-endian ]
210 @c Hitachi family chips have no machine-dependent assembler options
213 @c HPPA has no machine-dependent assembler options (yet).
216 [ -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite | -bump ]
219 @c Z8000 has no machine-dependent assembler options
222 @c see md_parse_option in tc-i960.c
223 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
227 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
230 [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ]
231 [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ]
232 [ --trap ] [ --break ]
233 [ --emulation=@var{name} ]
235 [ -- | @var{files} @dots{} ]
240 Turn on listings, in any of a variety of ways:
244 omit debugging directives
247 include high-level source
253 omit forms processing
259 set the name of the listing file
262 You may combine these options; for example, use @samp{-aln} for assembly
263 listing without forms processing. The @samp{=file} option, if used, must be
264 the last one. By itself, @samp{-a} defaults to @samp{-ahls}---that is, all
268 Ignored. This option is accepted for script compatibility with calls to
272 ``fast''---skip whitespace and comment preprocessing (assume source is
276 Print a summary of the command line options and exit.
279 Add directory @var{dir} to the search list for @code{.include} directives.
282 Don't warn about signed overflow.
285 @ifclear DIFF-TBL-KLUGE
286 This option is accepted but has no effect on the @value{TARGET} family.
288 @ifset DIFF-TBL-KLUGE
289 Issue warnings when difference tables altered for long displacements.
293 Keep (in the symbol table) local symbols, starting with @samp{L}.
295 @item -o @var{objfile}
296 Name the object-file output from @code{@value{AS}} @var{objfile}.
299 Fold the data section into the text section.
302 Print the maximum space (in bytes) and total time (in seconds) used by
307 Print the @code{as} version.
310 Print the @code{as} version and exit.
313 Suppress warning messages.
322 Generate an object file even after errors.
324 @item -- | @var{files} @dots{}
325 Standard input, or source files to assemble.
330 The following options are available when @value{AS} is configured for
335 @cindex ARC endianness
336 @cindex endianness, ARC
337 @cindex big endian output, ARC
339 Generate ``big endian'' format output.
341 @cindex little endian output, ARC
342 @item -mlittle-endian
343 Generate ``little endian'' format output.
349 The following options are available when @value{AS} is configured for the
350 Intel 80960 processor.
353 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
354 Specify which variant of the 960 architecture is the target.
357 Add code to collect statistics about branches taken.
360 Do not alter compare-and-branch instructions for long displacements;
367 The following options are available when @value{AS} is configured for the
368 Motorola 68000 series.
373 Shorten references to undefined symbols, to one word instead of two.
375 @item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040
376 @itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32
377 Specify what processor in the 68000 family is the target. The default
378 is normally the 68020, but this can be changed at configuration time.
380 @item -m68881 | -m68882 | -mno-68881 | -mno-68882
381 The target machine does (or does not) have a floating-point coprocessor.
382 The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
383 the basic 68000 is not compatible with the 68881, a combination of the
384 two can be specified, since it's possible to do emulation of the
385 coprocessor instructions with the main processor.
387 @item -m68851 | -mno-68851
388 The target machine does (or does not) have a memory-management
389 unit coprocessor. The default is to assume an MMU for 68020 and up.
395 The following options are available when @code{@value{AS}} is configured
396 for the SPARC architecture:
399 @item -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite
400 Explicitly select a variant of the SPARC architecture.
403 Warn when the assembler switches to another architecture.
408 The following options are available when @value{AS} is configured for
413 This option sets the largest size of an object that can be referenced
414 implicitly with the @code{gp} register. It is only accepted for targets that
415 use ECOFF format, such as a DECstation running Ultrix. The default value is 8.
417 @cindex MIPS endianness
418 @cindex endianness, MIPS
419 @cindex big endian output, MIPS
421 Generate ``big endian'' format output.
423 @cindex little endian output, MIPS
425 Generate ``little endian'' format output.
431 Generate code for a particular MIPS Instruction Set Architecture level.
432 @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
433 @samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000}
438 Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept
439 the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
440 instructions around accesses to the @samp{HI} and @samp{LO} registers.
441 @samp{-no-m4650} turns off this option.
443 @item -mcpu=@var{CPU}
444 Generate code for a particular MIPS cpu. This has little effect on the
445 assembler, but it is passed by @code{@value{GCC}}.
448 @item --emulation=@var{name}
449 This option causes @code{@value{AS}} to emulated @code{@value{AS}} configured
450 for some other target, in all respects, including output format (choosing
451 between ELF and ECOFF only), handling of pseudo-opcodes which may generate
452 debugging information or store symbol table information, and default
453 endianness. The available configuration names are: @samp{mipsecoff},
454 @samp{mipself}, @samp{mipslecoff}, @samp{mipsbecoff}, @samp{mipslelf},
455 @samp{mipsbelf}. The first two do not alter the default endianness from that
456 of the primary target for which the assembler was configured; the others change
457 the default to little- or big-endian as indicated by the @samp{b} or @samp{l}
458 in the name. Using @samp{-EB} or @samp{-EL} will override the endianness
459 selection in any case.
461 This option is currently supported only when the primary target
462 @code{@value{AS}} is configured for is a MIPS ELF or ECOFF target.
463 Furthermore, the primary target or others specified with
464 @samp{--enable-targets=@dots{}} at configuration time must include support for
465 the other format, if both are to be available. For example, the Irix 5
466 configuration includes support for both.
468 Eventually, this option will support more configurations, with more
469 fine-grained control over the assembler's behavior, and will be supported for
473 @code{@value{AS}} ignores this option. It is accepted for compatibility with
480 Control how to deal with multiplication overflow and division by zero.
481 @samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception
482 (and only work for Instruction Set Architecture level 2 and higher);
483 @samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a
489 * Manual:: Structure of this Manual
490 * GNU Assembler:: @value{AS}, the GNU Assembler
491 * Object Formats:: Object File Formats
492 * Command Line:: Command Line
493 * Input Files:: Input Files
494 * Object:: Output (Object) File
495 * Errors:: Error and Warning Messages
499 @section Structure of this Manual
501 @cindex manual, structure and purpose
502 This manual is intended to describe what you need to know to use
503 @sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including
504 notation for symbols, constants, and expressions; the directives that
505 @code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}.
508 We also cover special features in the @value{TARGET}
509 configuration of @code{@value{AS}}, including assembler directives.
512 This manual also describes some of the machine-dependent features of
513 various flavors of the assembler.
516 @cindex machine instructions (not covered)
517 On the other hand, this manual is @emph{not} intended as an introduction
518 to programming in assembly language---let alone programming in general!
519 In a similar vein, we make no attempt to introduce the machine
520 architecture; we do @emph{not} describe the instruction set, standard
521 mnemonics, registers or addressing modes that are standard to a
522 particular architecture.
524 You may want to consult the manufacturer's
525 machine architecture manual for this information.
529 For information on the H8/300 machine instruction set, see @cite{H8/300
530 Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H,
531 see @cite{H8/300H Series Programming Manual} (Hitachi).
534 For information on the H8/500 machine instruction set, see @cite{H8/500
535 Series Programming Manual} (Hitachi M21T001).
538 For information on the Hitachi SH machine instruction set, see
539 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
542 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
546 @c I think this is premature---pesch@cygnus.com, 17jan1991
548 Throughout this manual, we assume that you are running @dfn{GNU},
549 the portable operating system from the @dfn{Free Software
550 Foundation, Inc.}. This restricts our attention to certain kinds of
551 computer (in particular, the kinds of computers that @sc{gnu} can run on);
552 once this assumption is granted examples and definitions need less
555 @code{@value{AS}} is part of a team of programs that turn a high-level
556 human-readable series of instructions into a low-level
557 computer-readable series of instructions. Different versions of
558 @code{@value{AS}} are used for different kinds of computer.
561 @c There used to be a section "Terminology" here, which defined
562 @c "contents", "byte", "word", and "long". Defining "word" to any
563 @c particular size is confusing when the .word directive may generate 16
564 @c bits on one machine and 32 bits on another; in general, for the user
565 @c version of this manual, none of these terms seem essential to define.
566 @c They were used very little even in the former draft of the manual;
567 @c this draft makes an effort to avoid them (except in names of
571 @section @value{AS}, the GNU Assembler
573 @sc{gnu} @code{as} is really a family of assemblers.
575 This manual describes @code{@value{AS}}, a member of that family which is
576 configured for the @value{TARGET} architectures.
578 If you use (or have used) the @sc{gnu} assembler on one architecture, you
579 should find a fairly similar environment when you use it on another
580 architecture. Each version has much in common with the others,
581 including object file formats, most assembler directives (often called
582 @dfn{pseudo-ops}) and assembler syntax.@refill
584 @cindex purpose of @sc{gnu} @code{@value{AS}}
585 @code{@value{AS}} is primarily intended to assemble the output of the
586 @sc{gnu} C compiler @code{@value{GCC}} for use by the linker
587 @code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}}
588 assemble correctly everything that other assemblers for the same
589 machine would assemble.
591 Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
594 @c This remark should appear in generic version of manual; assumption
595 @c here is that generic version sets M680x0.
596 This doesn't mean @code{@value{AS}} always uses the same syntax as another
597 assembler for the same architecture; for example, we know of several
598 incompatible versions of 680x0 assembly language syntax.
601 Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
602 program in one pass of the source file. This has a subtle impact on the
603 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
606 @section Object File Formats
608 @cindex object file format
609 The @sc{gnu} assembler can be configured to produce several alternative
610 object file formats. For the most part, this does not affect how you
611 write assembly language programs; but directives for debugging symbols
612 are typically different in different file formats. @xref{Symbol
613 Attributes,,Symbol Attributes}.
616 On the @value{TARGET}, @code{@value{AS}} is configured to produce
617 @value{OBJ-NAME} format object files.
619 @c The following should exhaust all configs that set MULTI-OBJ, ideally
621 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
622 @code{a.out} or COFF format object files.
625 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
626 @code{b.out} or COFF format object files.
629 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
630 SOM or ELF format object files.
635 @section Command Line
637 @cindex command line conventions
638 After the program name @code{@value{AS}}, the command line may contain
639 options and file names. Options may appear in any order, and may be
640 before, after, or between file names. The order of file names is
643 @cindex standard input, as input file
645 @file{--} (two hyphens) by itself names the standard input file
646 explicitly, as one of the files for @code{@value{AS}} to assemble.
648 @cindex options, command line
649 Except for @samp{--} any command line argument that begins with a
650 hyphen (@samp{-}) is an option. Each option changes the behavior of
651 @code{@value{AS}}. No option changes the way another option works. An
652 option is a @samp{-} followed by one or more letters; the case of
653 the letter is important. All options are optional.
655 Some options expect exactly one file name to follow them. The file
656 name may either immediately follow the option's letter (compatible
657 with older assemblers) or it may be the next command argument (@sc{gnu}
658 standard). These two command lines are equivalent:
661 @value{AS} -o my-object-file.o mumble.s
662 @value{AS} -omy-object-file.o mumble.s
669 @cindex source program
671 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
672 describe the program input to one run of @code{@value{AS}}. The program may
673 be in one or more files; how the source is partitioned into files
674 doesn't change the meaning of the source.
676 @c I added "con" prefix to "catenation" just to prove I can overcome my
677 @c APL training... pesch@cygnus.com
678 The source program is a concatenation of the text in all the files, in the
681 Each time you run @code{@value{AS}} it assembles exactly one source
682 program. The source program is made up of one or more files.
683 (The standard input is also a file.)
685 You give @code{@value{AS}} a command line that has zero or more input file
686 names. The input files are read (from left file name to right). A
687 command line argument (in any position) that has no special meaning
688 is taken to be an input file name.
690 If you give @code{@value{AS}} no file names it attempts to read one input file
691 from the @code{@value{AS}} standard input, which is normally your terminal. You
692 may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program
695 Use @samp{--} if you need to explicitly name the standard input file
696 in your command line.
698 If the source is empty, @code{@value{AS}} produces a small, empty object
701 @subheading Filenames and Line-numbers
703 @cindex input file linenumbers
704 @cindex line numbers, in input files
705 There are two ways of locating a line in the input file (or files) and
706 either may be used in reporting error messages. One way refers to a line
707 number in a physical file; the other refers to a line number in a
708 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
710 @dfn{Physical files} are those files named in the command line given
711 to @code{@value{AS}}.
713 @dfn{Logical files} are simply names declared explicitly by assembler
714 directives; they bear no relation to physical files. Logical file names
715 help error messages reflect the original source file, when @code{@value{AS}}
716 source is itself synthesized from other files.
717 @xref{App-File,,@code{.app-file}}.
720 @section Output (Object) File
726 Every time you run @code{@value{AS}} it produces an output file, which is
727 your assembly language program translated into numbers. This file
728 is the object file. Its default name is
736 @code{b.out} when @code{@value{AS}} is configured for the Intel 80960.
738 You can give it another name by using the @code{-o} option. Conventionally,
739 object file names end with @file{.o}. The default name is used for historical
740 reasons: older assemblers were capable of assembling self-contained programs
741 directly into a runnable program. (For some formats, this isn't currently
742 possible, but it can be done for the @code{a.out} format.)
746 The object file is meant for input to the linker @code{@value{LD}}. It contains
747 assembled program code, information to help @code{@value{LD}} integrate
748 the assembled program into a runnable file, and (optionally) symbolic
749 information for the debugger.
751 @c link above to some info file(s) like the description of a.out.
752 @c don't forget to describe GNU info as well as Unix lossage.
755 @section Error and Warning Messages
757 @cindex error messsages
758 @cindex warning messages
759 @cindex messages from @code{@value{AS}}
760 @code{@value{AS}} may write warnings and error messages to the standard error
761 file (usually your terminal). This should not happen when a compiler
762 runs @code{@value{AS}} automatically. Warnings report an assumption made so
763 that @code{@value{AS}} could keep assembling a flawed program; errors report a
764 grave problem that stops the assembly.
766 @cindex format of warning messages
767 Warning messages have the format
770 file_name:@b{NNN}:Warning Message Text
774 @cindex line numbers, in warnings/errors
775 (where @b{NNN} is a line number). If a logical file name has been given
776 (@pxref{App-File,,@code{.app-file}}) it is used for the filename,
777 otherwise the name of the current input file is used. If a logical line
780 (@pxref{Line,,@code{.line}})
784 (@pxref{Line,,@code{.line}})
787 (@pxref{Ln,,@code{.ln}})
790 then it is used to calculate the number printed,
791 otherwise the actual line in the current source file is printed. The
792 message text is intended to be self explanatory (in the grand Unix
795 @cindex format of error messages
796 Error messages have the format
798 file_name:@b{NNN}:FATAL:Error Message Text
800 The file name and line number are derived as for warning
801 messages. The actual message text may be rather less explanatory
802 because many of them aren't supposed to happen.
805 @chapter Command-Line Options
807 @cindex options, all versions of @code{@value{AS}}
808 This chapter describes command-line options available in @emph{all}
809 versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific
811 to the @value{TARGET}.
814 to particular machine architectures.
817 If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2), you
818 can use the @samp{-Wa} option to pass arguments through to the
819 assembler. The assembler arguments must be separated from each other
820 (and the @samp{-Wa}) by commas. For example:
823 gcc -c -g -O -Wa,-alh,-L file.c
827 emits a listing to standard output with high-level
830 Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
831 command-line options are automatically passed to the assembler by the compiler.
832 (You can call the @sc{gnu} compiler driver with the @samp{-v} option to see
833 precisely what options it passes to each compilation pass, including the
837 * a:: -a[dhlns] enable listings
838 * D:: -D for compatibility
839 * f:: -f to work faster
840 * I:: -I for .include search path
841 @ifclear DIFF-TBL-KLUGE
842 * K:: -K for compatibility
844 @ifset DIFF-TBL-KLUGE
845 * K:: -K for difference tables
848 * L:: -L to retain local labels
849 * o:: -o to name the object file
850 * R:: -R to join data and text sections
851 * statistics:: --statistics to see statistics about assembly
852 * v:: -v to announce version
853 * W:: -W to suppress warnings
854 * Z:: -Z to make object file even after errors
858 @section Enable Listings: @code{-a[dhlns]}
866 @cindex listings, enabling
867 @cindex assembly listings, enabling
869 These options enable listing output from the assembler. By itself,
870 @samp{-a} requests high-level, assembly, and symbols listing.
871 You can use other letters to select specific options for the list:
872 @samp{-ah} requests a high-level language listing,
873 @samp{-al} requests an output-program assembly listing, and
874 @samp{-as} requests a symbol table listing.
875 High-level listings require that a compiler debugging option like
876 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
879 Use the @samp{-ad} option to omit debugging directives from the
882 Once you have specified one of these options, you can further control
883 listing output and its appearance using the directives @code{.list},
884 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
886 The @samp{-an} option turns off all forms processing.
887 If you do not request listing output with one of the @samp{-a} options, the
888 listing-control directives have no effect.
890 The letters after @samp{-a} may be combined into one option,
891 @emph{e.g.}, @samp{-aln}.
897 This option has no effect whatsoever, but it is accepted to make it more
898 likely that scripts written for other assemblers also work with
902 @section Work Faster: @code{-f}
905 @cindex trusted compiler
906 @cindex faster processing (@code{-f})
907 @samp{-f} should only be used when assembling programs written by a
908 (trusted) compiler. @samp{-f} stops the assembler from doing whitespace
909 and comment preprocessing on
910 the input file(s) before assembling them. @xref{Preprocessing,
914 @emph{Warning:} if you use @samp{-f} when the files actually need to be
915 preprocessed (if they contain comments, for example), @code{@value{AS}} does
920 @section @code{.include} search path: @code{-I} @var{path}
922 @kindex -I @var{path}
923 @cindex paths for @code{.include}
924 @cindex search path for @code{.include}
925 @cindex @code{include} directive search path
926 Use this option to add a @var{path} to the list of directories
927 @code{@value{AS}} searches for files specified in @code{.include}
928 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
929 many times as necessary to include a variety of paths. The current
930 working directory is always searched first; after that, @code{@value{AS}}
931 searches any @samp{-I} directories in the same order as they were
932 specified (left to right) on the command line.
935 @section Difference Tables: @code{-K}
938 @ifclear DIFF-TBL-KLUGE
939 On the @value{TARGET} family, this option is allowed, but has no effect. It is
940 permitted for compatibility with the @sc{gnu} assembler on other platforms,
941 where it can be used to warn when the assembler alters the machine code
942 generated for @samp{.word} directives in difference tables. The @value{TARGET}
943 family does not have the addressing limitations that sometimes lead to this
944 alteration on other platforms.
947 @ifset DIFF-TBL-KLUGE
948 @cindex difference tables, warning
949 @cindex warning for altered difference tables
950 @code{@value{AS}} sometimes alters the code emitted for directives of the form
951 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
952 You can use the @samp{-K} option if you want a warning issued when this
957 @section Include Local Labels: @code{-L}
960 @cindex local labels, retaining in output
961 Labels beginning with @samp{L} (upper case only) are called @dfn{local
962 labels}. @xref{Symbol Names}. Normally you do not see such labels when
963 debugging, because they are intended for the use of programs (like
964 compilers) that compose assembler programs, not for your notice.
965 Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not
966 normally debug with them.
968 This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols
969 in the object file. Usually if you do this you also tell the linker
970 @code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
972 By default, a local label is any label beginning with @samp{L}, but each
973 target is allowed to redefine the local label prefix.
975 On the HPPA local labels begin with @samp{L$}.
977 @c start-sanitize-arc
979 On the ARC local labels begin with @samp{.L}.
984 @section Name the Object File: @code{-o}
987 @cindex naming object file
988 @cindex object file name
989 There is always one object file output when you run @code{@value{AS}}. By
990 default it has the name
993 @file{a.out} (or @file{b.out}, for Intel 960 targets only).
1007 You use this option (which takes exactly one filename) to give the
1008 object file a different name.
1010 Whatever the object file is called, @code{@value{AS}} overwrites any
1011 existing file of the same name.
1014 @section Join Data and Text Sections: @code{-R}
1017 @cindex data and text sections, joining
1018 @cindex text and data sections, joining
1019 @cindex joining text and data sections
1020 @cindex merging text and data sections
1021 @code{-R} tells @code{@value{AS}} to write the object file as if all
1022 data-section data lives in the text section. This is only done at
1023 the very last moment: your binary data are the same, but data
1024 section parts are relocated differently. The data section part of
1025 your object file is zero bytes long because all its bytes are
1026 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
1028 When you specify @code{-R} it would be possible to generate shorter
1029 address displacements (because we do not have to cross between text and
1030 data section). We refrain from doing this simply for compatibility with
1031 older versions of @code{@value{AS}}. In future, @code{-R} may work this way.
1034 When @code{@value{AS}} is configured for COFF output,
1035 this option is only useful if you use sections named @samp{.text} and
1040 @code{-R} is not supported for any of the HPPA targets. Using
1041 @code{-R} generates a warning from @code{@value{AS}}.
1045 @section Display Assembly Statistics: @code{--statistics}
1047 @kindex --statistics
1048 @cindex statistics, about assembly
1049 @cindex time, total for assembly
1050 @cindex space used, maximum for assembly
1051 Use @samp{--statistics} to display two statistics about the resources used by
1052 @code{@value{AS}}: the maximum amount of space allocated during the assembly
1053 (in bytes), and the total execution time taken for the assembly (in @sc{cpu}
1057 @section Announce Version: @code{-v}
1061 @cindex @code{@value{AS}} version
1062 @cindex version of @code{@value{AS}}
1063 You can find out what version of as is running by including the
1064 option @samp{-v} (which you can also spell as @samp{-version}) on the
1068 @section Suppress Warnings: @code{-W}
1071 @cindex suppressing warnings
1072 @cindex warnings, suppressing
1073 @code{@value{AS}} should never give a warning or error message when
1074 assembling compiler output. But programs written by people often
1075 cause @code{@value{AS}} to give a warning that a particular assumption was
1076 made. All such warnings are directed to the standard error file.
1077 If you use this option, no warnings are issued. This option only
1078 affects the warning messages: it does not change any particular of how
1079 @code{@value{AS}} assembles your file. Errors, which stop the assembly, are
1083 @section Generate Object File in Spite of Errors: @code{-Z}
1084 @cindex object file, after errors
1085 @cindex errors, continuing after
1086 After an error message, @code{@value{AS}} normally produces no output. If for
1087 some reason you are interested in object file output even after
1088 @code{@value{AS}} gives an error message on your program, use the @samp{-Z}
1089 option. If there are any errors, @code{@value{AS}} continues anyways, and
1090 writes an object file after a final warning message of the form @samp{@var{n}
1091 errors, @var{m} warnings, generating bad object file.}
1096 @cindex machine-independent syntax
1097 @cindex syntax, machine-independent
1098 This chapter describes the machine-independent syntax allowed in a
1099 source file. @code{@value{AS}} syntax is similar to what many other
1100 assemblers use; it is inspired by the BSD 4.2
1105 assembler, except that @code{@value{AS}} does not assemble Vax bit-fields.
1109 * Preprocessing:: Preprocessing
1110 * Whitespace:: Whitespace
1111 * Comments:: Comments
1112 * Symbol Intro:: Symbols
1113 * Statements:: Statements
1114 * Constants:: Constants
1118 @section Preprocessing
1120 @cindex preprocessing
1121 The @code{@value{AS}} internal preprocessor:
1123 @cindex whitespace, removed by preprocessor
1125 adjusts and removes extra whitespace. It leaves one space or tab before
1126 the keywords on a line, and turns any other whitespace on the line into
1129 @cindex comments, removed by preprocessor
1131 removes all comments, replacing them with a single space, or an
1132 appropriate number of newlines.
1134 @cindex constants, converted by preprocessor
1136 converts character constants into the appropriate numeric values.
1139 It does not do macro processing, include file handling, or
1140 anything else you may get from your C compiler's preprocessor. You can
1141 do include file processing with the @code{.include} directive
1142 (@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver
1143 to get other ``CPP'' style preprocessing, by giving the input file a
1144 @samp{.S} suffix. @xref{Overall Options,, Options Controlling the Kind of
1145 Output, gcc.info, Using GNU CC}.
1147 Excess whitespace, comments, and character constants
1148 cannot be used in the portions of the input text that are not
1151 @cindex turning preprocessing on and off
1152 @cindex preprocessing, turning on and off
1155 If the first line of an input file is @code{#NO_APP} or if you use the
1156 @samp{-f} option, whitespace and comments are not removed from the input file.
1157 Within an input file, you can ask for whitespace and comment removal in
1158 specific portions of the by putting a line that says @code{#APP} before the
1159 text that may contain whitespace or comments, and putting a line that says
1160 @code{#NO_APP} after this text. This feature is mainly intend to support
1161 @code{asm} statements in compilers whose output is otherwise free of comments
1168 @dfn{Whitespace} is one or more blanks or tabs, in any order.
1169 Whitespace is used to separate symbols, and to make programs neater for
1170 people to read. Unless within character constants
1171 (@pxref{Characters,,Character Constants}), any whitespace means the same
1172 as exactly one space.
1178 There are two ways of rendering comments to @code{@value{AS}}. In both
1179 cases the comment is equivalent to one space.
1181 Anything from @samp{/*} through the next @samp{*/} is a comment.
1182 This means you may not nest these comments.
1186 The only way to include a newline ('\n') in a comment
1187 is to use this sort of comment.
1190 /* This sort of comment does not nest. */
1193 @cindex line comment character
1194 Anything from the @dfn{line comment} character to the next newline
1195 is considered a comment and is ignored. The line comment character is
1196 @c start-sanitize-arc
1198 @samp{;} on the ARC;
1202 @samp{#} on the Vax;
1205 @samp{#} on the i960;
1208 @samp{!} on the SPARC;
1211 @samp{|} on the 680x0;
1214 @samp{;} for the AMD 29K family;
1217 @samp{;} for the H8/300 family;
1220 @samp{!} for the H8/500 family;
1223 @samp{;} for the HPPA;
1226 @samp{!} for the Hitachi SH;
1229 @samp{!} for the Z8000;
1231 see @ref{Machine Dependencies}. @refill
1232 @c FIXME What about i386, m88k, i860?
1235 On some machines there are two different line comment characters. One
1236 character only begins a comment if it is the first non-whitespace character on
1237 a line, while the other always begins a comment.
1241 @cindex lines starting with @code{#}
1242 @cindex logical line numbers
1243 To be compatible with past assemblers, lines that begin with @samp{#} have a
1244 special interpretation. Following the @samp{#} should be an absolute
1245 expression (@pxref{Expressions}): the logical line number of the @emph{next}
1246 line. Then a string (@pxref{Strings,, Strings}) is allowed: if present it is a
1247 new logical file name. The rest of the line, if any, should be whitespace.
1249 If the first non-whitespace characters on the line are not numeric,
1250 the line is ignored. (Just like a comment.)
1253 # This is an ordinary comment.
1254 # 42-6 "new_file_name" # New logical file name
1255 # This is logical line # 36.
1257 This feature is deprecated, and may disappear from future versions
1258 of @code{@value{AS}}.
1263 @cindex characters used in symbols
1264 @ifclear SPECIAL-SYMS
1265 A @dfn{symbol} is one or more characters chosen from the set of all
1266 letters (both upper and lower case), digits and the three characters
1272 A @dfn{symbol} is one or more characters chosen from the set of all
1273 letters (both upper and lower case), digits and the three characters
1274 @samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in
1280 On most machines, you can also use @code{$} in symbol names; exceptions
1281 are noted in @ref{Machine Dependencies}.
1283 No symbol may begin with a digit. Case is significant.
1284 There is no length limit: all characters are significant. Symbols are
1285 delimited by characters not in that set, or by the beginning of a file
1286 (since the source program must end with a newline, the end of a file is
1287 not a possible symbol delimiter). @xref{Symbols}.
1288 @cindex length of symbols
1293 @cindex statements, structure of
1294 @cindex line separator character
1295 @cindex statement separator character
1297 @ifclear abnormal-separator
1298 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
1299 semicolon (@samp{;}). The newline or semicolon is considered part of
1300 the preceding statement. Newlines and semicolons within character
1301 constants are an exception: they do not end statements.
1303 @ifset abnormal-separator
1305 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
1306 sign (@samp{@@}). The newline or at sign is considered part of the
1307 preceding statement. Newlines and at signs within character constants
1308 are an exception: they do not end statements.
1311 A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation
1312 point (@samp{!}). The newline or exclamation point is considered part of the
1313 preceding statement. Newlines and exclamation points within character
1314 constants are an exception: they do not end statements.
1317 A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
1318 H8/300) a dollar sign (@samp{$}); or (for the
1321 (@samp{;}). The newline or separator character is considered part of
1322 the preceding statement. Newlines and separators within character
1323 constants are an exception: they do not end statements.
1328 A @dfn{statement} ends at a newline character (@samp{\n}) or line
1329 separator character. (The line separator is usually @samp{;}, unless
1330 this conflicts with the comment character; @pxref{Machine Dependencies}.) The
1331 newline or separator character is considered part of the preceding
1332 statement. Newlines and separators within character constants are an
1333 exception: they do not end statements.
1336 @cindex newline, required at file end
1337 @cindex EOF, newline must precede
1338 It is an error to end any statement with end-of-file: the last
1339 character of any input file should be a newline.@refill
1341 @cindex continuing statements
1342 @cindex multi-line statements
1343 @cindex statement on multiple lines
1344 You may write a statement on more than one line if you put a
1345 backslash (@kbd{\}) immediately in front of any newlines within the
1346 statement. When @code{@value{AS}} reads a backslashed newline both
1347 characters are ignored. You can even put backslashed newlines in
1348 the middle of symbol names without changing the meaning of your
1351 An empty statement is allowed, and may include whitespace. It is ignored.
1353 @cindex instructions and directives
1354 @cindex directives and instructions
1355 @c "key symbol" is not used elsewhere in the document; seems pedantic to
1356 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
1358 A statement begins with zero or more labels, optionally followed by a
1359 key symbol which determines what kind of statement it is. The key
1360 symbol determines the syntax of the rest of the statement. If the
1361 symbol begins with a dot @samp{.} then the statement is an assembler
1362 directive: typically valid for any computer. If the symbol begins with
1363 a letter the statement is an assembly language @dfn{instruction}: it
1364 assembles into a machine language instruction.
1366 Different versions of @code{@value{AS}} for different computers
1367 recognize different instructions. In fact, the same symbol may
1368 represent a different instruction in a different computer's assembly
1372 @cindex @code{:} (label)
1373 @cindex label (@code{:})
1374 A label is a symbol immediately followed by a colon (@code{:}).
1375 Whitespace before a label or after a colon is permitted, but you may not
1376 have whitespace between a label's symbol and its colon. @xref{Labels}.
1379 For HPPA targets, labels need not be immediately followed by a colon, but
1380 the definition of a label must begin in column zero. This also implies that
1381 only one label may be defined on each line.
1385 label: .directive followed by something
1386 another_label: # This is an empty statement.
1387 instruction operand_1, operand_2, @dots{}
1394 A constant is a number, written so that its value is known by
1395 inspection, without knowing any context. Like this:
1398 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
1399 .ascii "Ring the bell\7" # A string constant.
1400 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
1401 .float 0f-314159265358979323846264338327\
1402 95028841971.693993751E-40 # - pi, a flonum.
1407 * Characters:: Character Constants
1408 * Numbers:: Number Constants
1412 @subsection Character Constants
1414 @cindex character constants
1415 @cindex constants, character
1416 There are two kinds of character constants. A @dfn{character} stands
1417 for one character in one byte and its value may be used in
1418 numeric expressions. String constants (properly called string
1419 @emph{literals}) are potentially many bytes and their values may not be
1420 used in arithmetic expressions.
1424 * Chars:: Characters
1428 @subsubsection Strings
1430 @cindex string constants
1431 @cindex constants, string
1432 A @dfn{string} is written between double-quotes. It may contain
1433 double-quotes or null characters. The way to get special characters
1434 into a string is to @dfn{escape} these characters: precede them with
1435 a backslash @samp{\} character. For example @samp{\\} represents
1436 one backslash: the first @code{\} is an escape which tells
1437 @code{@value{AS}} to interpret the second character literally as a backslash
1438 (which prevents @code{@value{AS}} from recognizing the second @code{\} as an
1439 escape character). The complete list of escapes follows.
1441 @cindex escape codes, character
1442 @cindex character escape codes
1445 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1448 @cindex @code{\b} (backspace character)
1449 @cindex backspace (@code{\b})
1450 Mnemonic for backspace; for ASCII this is octal code 010.
1453 @c Mnemonic for EOText; for ASCII this is octal code 004.
1456 @cindex @code{\f} (formfeed character)
1457 @cindex formfeed (@code{\f})
1458 Mnemonic for FormFeed; for ASCII this is octal code 014.
1461 @cindex @code{\n} (newline character)
1462 @cindex newline (@code{\n})
1463 Mnemonic for newline; for ASCII this is octal code 012.
1466 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1469 @cindex @code{\r} (carriage return character)
1470 @cindex carriage return (@code{\r})
1471 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1474 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1475 @c other assemblers.
1478 @cindex @code{\t} (tab)
1479 @cindex tab (@code{\t})
1480 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1483 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1484 @c @item \x @var{digit} @var{digit} @var{digit}
1485 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1487 @item \ @var{digit} @var{digit} @var{digit}
1488 @cindex @code{\@var{ddd}} (octal character code)
1489 @cindex octal character code (@code{\@var{ddd}})
1490 An octal character code. The numeric code is 3 octal digits.
1491 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1492 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1495 @item \@code{x} @var{hex-digit} @var{hex-digit}
1496 @cindex @code{\@var{xdd}} (hex character code)
1497 @cindex hex character code (@code{\@var{xdd}})
1498 A hex character code. The numeric code is 2 hexadecimal digits. Either
1499 upper or lower case @code{x} works.
1503 @cindex @code{\\} (@samp{\} character)
1504 @cindex backslash (@code{\\})
1505 Represents one @samp{\} character.
1508 @c Represents one @samp{'} (accent acute) character.
1509 @c This is needed in single character literals
1510 @c (@xref{Characters,,Character Constants}.) to represent
1514 @cindex @code{\"} (doublequote character)
1515 @cindex doublequote (@code{\"})
1516 Represents one @samp{"} character. Needed in strings to represent
1517 this character, because an unescaped @samp{"} would end the string.
1519 @item \ @var{anything-else}
1520 Any other character when escaped by @kbd{\} gives a warning, but
1521 assembles as if the @samp{\} was not present. The idea is that if
1522 you used an escape sequence you clearly didn't want the literal
1523 interpretation of the following character. However @code{@value{AS}} has no
1524 other interpretation, so @code{@value{AS}} knows it is giving you the wrong
1525 code and warns you of the fact.
1528 Which characters are escapable, and what those escapes represent,
1529 varies widely among assemblers. The current set is what we think
1530 the BSD 4.2 assembler recognizes, and is a subset of what most C
1531 compilers recognize. If you are in doubt, do not use an escape
1535 @subsubsection Characters
1537 @cindex single character constant
1538 @cindex character, single
1539 @cindex constant, single character
1540 A single character may be written as a single quote immediately
1541 followed by that character. The same escapes apply to characters as
1542 to strings. So if you want to write the character backslash, you
1543 must write @kbd{'\\} where the first @code{\} escapes the second
1544 @code{\}. As you can see, the quote is an acute accent, not a
1545 grave accent. A newline
1547 @ifclear abnormal-separator
1548 (or semicolon @samp{;})
1550 @ifset abnormal-separator
1552 (or at sign @samp{@@})
1555 (or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
1561 immediately following an acute accent is taken as a literal character
1562 and does not count as the end of a statement. The value of a character
1563 constant in a numeric expression is the machine's byte-wide code for
1564 that character. @code{@value{AS}} assumes your character code is ASCII:
1565 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1568 @subsection Number Constants
1570 @cindex constants, number
1571 @cindex number constants
1572 @code{@value{AS}} distinguishes three kinds of numbers according to how they
1573 are stored in the target machine. @emph{Integers} are numbers that
1574 would fit into an @code{int} in the C language. @emph{Bignums} are
1575 integers, but they are stored in more than 32 bits. @emph{Flonums}
1576 are floating point numbers, described below.
1579 * Integers:: Integers
1584 * Bit Fields:: Bit Fields
1590 @subsubsection Integers
1592 @cindex constants, integer
1594 @cindex binary integers
1595 @cindex integers, binary
1596 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1597 the binary digits @samp{01}.
1599 @cindex octal integers
1600 @cindex integers, octal
1601 An octal integer is @samp{0} followed by zero or more of the octal
1602 digits (@samp{01234567}).
1604 @cindex decimal integers
1605 @cindex integers, decimal
1606 A decimal integer starts with a non-zero digit followed by zero or
1607 more digits (@samp{0123456789}).
1609 @cindex hexadecimal integers
1610 @cindex integers, hexadecimal
1611 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1612 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1614 Integers have the usual values. To denote a negative integer, use
1615 the prefix operator @samp{-} discussed under expressions
1616 (@pxref{Prefix Ops,,Prefix Operators}).
1619 @subsubsection Bignums
1622 @cindex constants, bignum
1623 A @dfn{bignum} has the same syntax and semantics as an integer
1624 except that the number (or its negative) takes more than 32 bits to
1625 represent in binary. The distinction is made because in some places
1626 integers are permitted while bignums are not.
1629 @subsubsection Flonums
1631 @cindex floating point numbers
1632 @cindex constants, floating point
1634 @cindex precision, floating point
1635 A @dfn{flonum} represents a floating point number. The translation is
1636 indirect: a decimal floating point number from the text is converted by
1637 @code{@value{AS}} to a generic binary floating point number of more than
1638 sufficient precision. This generic floating point number is converted
1639 to a particular computer's floating point format (or formats) by a
1640 portion of @code{@value{AS}} specialized to that computer.
1642 A flonum is written by writing (in order)
1647 (@samp{0} is optional on the HPPA.)
1651 A letter, to tell @code{@value{AS}} the rest of the number is a flonum.
1653 @kbd{e} is recommended. Case is not important.
1655 @c FIXME: verify if flonum syntax really this vague for most cases
1656 (Any otherwise illegal letter works here, but that might be changed. Vax BSD
1657 4.2 assembler seems to allow any of @samp{defghDEFGH}.)
1660 On the H8/300, H8/500,
1662 and AMD 29K architectures, the letter must be
1663 one of the letters @samp{DFPRSX} (in upper or lower case).
1665 @c start-sanitize-arc
1666 On the ARC, the letter one of the letters @samp{DFRS}
1667 (in upper or lower case).
1670 On the Intel 960 architecture, the letter must be
1671 one of the letters @samp{DFT} (in upper or lower case).
1673 On the HPPA architecture, the letter must be @samp{E} (upper case only).
1677 One of the letters @samp{DFPRSX} (in upper or lower case).
1679 @c start-sanitize-arc
1681 One of the letters @samp{DFRS} (in upper or lower case).
1685 One of the letters @samp{DFPRSX} (in upper or lower case).
1688 One of the letters @samp{DFT} (in upper or lower case).
1691 The letter @samp{E} (upper case only).
1696 An optional sign: either @samp{+} or @samp{-}.
1699 An optional @dfn{integer part}: zero or more decimal digits.
1702 An optional @dfn{fractional part}: @samp{.} followed by zero
1703 or more decimal digits.
1706 An optional exponent, consisting of:
1710 An @samp{E} or @samp{e}.
1711 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1712 @c principle this can perfectly well be different on different targets.
1714 Optional sign: either @samp{+} or @samp{-}.
1716 One or more decimal digits.
1721 At least one of the integer part or the fractional part must be
1722 present. The floating point number has the usual base-10 value.
1724 @code{@value{AS}} does all processing using integers. Flonums are computed
1725 independently of any floating point hardware in the computer running
1730 @c Bit fields are written as a general facility but are also controlled
1731 @c by a conditional-compilation flag---which is as of now (21mar91)
1732 @c turned on only by the i960 config of GAS.
1734 @subsubsection Bit Fields
1737 @cindex constants, bit field
1738 You can also define numeric constants as @dfn{bit fields}.
1739 specify two numbers separated by a colon---
1741 @var{mask}:@var{value}
1744 @code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
1747 The resulting number is then packed
1749 @c this conditional paren in case bit fields turned on elsewhere than 960
1750 (in host-dependent byte order)
1752 into a field whose width depends on which assembler directive has the
1753 bit-field as its argument. Overflow (a result from the bitwise and
1754 requiring more binary digits to represent) is not an error; instead,
1755 more constants are generated, of the specified width, beginning with the
1756 least significant digits.@refill
1758 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1759 @code{.short}, and @code{.word} accept bit-field arguments.
1764 @chapter Sections and Relocation
1769 * Secs Background:: Background
1770 * Ld Sections:: @value{LD} Sections
1771 * As Sections:: @value{AS} Internal Sections
1772 * Sub-Sections:: Sub-Sections
1776 @node Secs Background
1779 Roughly, a section is a range of addresses, with no gaps; all data
1780 ``in'' those addresses is treated the same for some particular purpose.
1781 For example there may be a ``read only'' section.
1783 @cindex linker, and assembler
1784 @cindex assembler, and linker
1785 The linker @code{@value{LD}} reads many object files (partial programs) and
1786 combines their contents to form a runnable program. When @code{@value{AS}}
1787 emits an object file, the partial program is assumed to start at address 0.
1788 @code{@value{LD}} assigns the final addresses for the partial program, so that
1789 different partial programs do not overlap. This is actually an
1790 oversimplification, but it suffices to explain how @code{@value{AS}} uses
1793 @code{@value{LD}} moves blocks of bytes of your program to their run-time
1794 addresses. These blocks slide to their run-time addresses as rigid
1795 units; their length does not change and neither does the order of bytes
1796 within them. Such a rigid unit is called a @emph{section}. Assigning
1797 run-time addresses to sections is called @dfn{relocation}. It includes
1798 the task of adjusting mentions of object-file addresses so they refer to
1799 the proper run-time addresses.
1801 For the H8/300 and H8/500,
1802 and for the Hitachi SH,
1803 @code{@value{AS}} pads sections if needed to
1804 ensure they end on a word (sixteen bit) boundary.
1807 @cindex standard @code{@value{AS}} sections
1808 An object file written by @code{@value{AS}} has at least three sections, any
1809 of which may be empty. These are named @dfn{text}, @dfn{data} and
1814 When it generates COFF output,
1816 @code{@value{AS}} can also generate whatever other named sections you specify
1817 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1818 If you do not use any directives that place output in the @samp{.text}
1819 or @samp{.data} sections, these sections still exist, but are empty.
1824 When @code{@value{AS}} generates SOM or ELF output for the HPPA,
1826 @code{@value{AS}} can also generate whatever other named sections you
1827 specify using the @samp{.space} and @samp{.subspace} directives. See
1828 @cite{HP9000 Series 800 Assembly Language Reference Manual}
1829 (HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
1830 assembler directives.
1833 Additionally, @code{@value{AS}} uses different names for the standard
1834 text, data, and bss sections when generating SOM output. Program text
1835 is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
1836 BSS into @samp{$BSS$}.
1840 Within the object file, the text section starts at address @code{0}, the
1841 data section follows, and the bss section follows the data section.
1844 When generating either SOM or ELF output files on the HPPA, the text
1845 section starts at address @code{0}, the data section at address
1846 @code{0x4000000}, and the bss section follows the data section.
1849 To let @code{@value{LD}} know which data changes when the sections are
1850 relocated, and how to change that data, @code{@value{AS}} also writes to the
1851 object file details of the relocation needed. To perform relocation
1852 @code{@value{LD}} must know, each time an address in the object
1856 Where in the object file is the beginning of this reference to
1859 How long (in bytes) is this reference?
1861 Which section does the address refer to? What is the numeric value of
1863 (@var{address}) @minus{} (@var{start-address of section})?
1866 Is the reference to an address ``Program-Counter relative''?
1869 @cindex addresses, format of
1870 @cindex section-relative addressing
1871 In fact, every address @code{@value{AS}} ever uses is expressed as
1873 (@var{section}) + (@var{offset into section})
1876 Further, most expressions @code{@value{AS}} computes have this section-relative
1879 (For some object formats, such as SOM for the HPPA, some expressions are
1880 symbol-relative instead.)
1883 In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset
1884 @var{N} into section @var{secname}.''
1886 Apart from text, data and bss sections you need to know about the
1887 @dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
1888 addresses in the absolute section remain unchanged. For example, address
1889 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
1890 @code{@value{LD}}. Although the linker never arranges two partial programs'
1891 data sections with overlapping addresses after linking, @emph{by definition}
1892 their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one
1893 part of a program is always the same address when the program is running as
1894 address @code{@{absolute@ 239@}} in any other part of the program.
1896 The idea of sections is extended to the @dfn{undefined} section. Any
1897 address whose section is unknown at assembly time is by definition
1898 rendered @{undefined @var{U}@}---where @var{U} is filled in later.
1899 Since numbers are always defined, the only way to generate an undefined
1900 address is to mention an undefined symbol. A reference to a named
1901 common block would be such a symbol: its value is unknown at assembly
1902 time so it has section @emph{undefined}.
1904 By analogy the word @emph{section} is used to describe groups of sections in
1905 the linked program. @code{@value{LD}} puts all partial programs' text
1906 sections in contiguous addresses in the linked program. It is
1907 customary to refer to the @emph{text section} of a program, meaning all
1908 the addresses of all partial programs' text sections. Likewise for
1909 data and bss sections.
1911 Some sections are manipulated by @code{@value{LD}}; others are invented for
1912 use of @code{@value{AS}} and have no meaning except during assembly.
1915 @section @value{LD} Sections
1916 @code{@value{LD}} deals with just four kinds of sections, summarized below.
1921 @cindex named sections
1922 @cindex sections, named
1923 @item named sections
1926 @cindex text section
1927 @cindex data section
1931 These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as
1932 separate but equal sections. Anything you can say of one section is
1935 When the program is running, however, it is
1936 customary for the text section to be unalterable. The
1937 text section is often shared among processes: it contains
1938 instructions, constants and the like. The data section of a running
1939 program is usually alterable: for example, C variables would be stored
1940 in the data section.
1945 This section contains zeroed bytes when your program begins running. It
1946 is used to hold unitialized variables or common storage. The length of
1947 each partial program's bss section is important, but because it starts
1948 out containing zeroed bytes there is no need to store explicit zero
1949 bytes in the object file. The bss section was invented to eliminate
1950 those explicit zeros from object files.
1952 @cindex absolute section
1953 @item absolute section
1954 Address 0 of this section is always ``relocated'' to runtime address 0.
1955 This is useful if you want to refer to an address that @code{@value{LD}} must
1956 not change when relocating. In this sense we speak of absolute
1957 addresses being ``unrelocatable'': they do not change during relocation.
1959 @cindex undefined section
1960 @item undefined section
1961 This ``section'' is a catch-all for address references to objects not in
1962 the preceding sections.
1963 @c FIXME: ref to some other doc on obj-file formats could go here.
1966 @cindex relocation example
1967 An idealized example of three relocatable sections follows.
1969 The example uses the traditional section names @samp{.text} and @samp{.data}.
1971 Memory addresses are on the horizontal axis.
1975 @c END TEXI2ROFF-KILL
1978 partial program # 1: |ttttt|dddd|00|
1985 partial program # 2: |TTT|DDD|000|
1988 +--+---+-----+--+----+---+-----+~~
1989 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1990 +--+---+-----+--+----+---+-----+~~
1992 addresses: 0 @dots{}
1999 \line{\it Partial program \#1: \hfil}
2000 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
2001 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
2003 \line{\it Partial program \#2: \hfil}
2004 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
2005 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
2007 \line{\it linked program: \hfil}
2008 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
2009 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
2010 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
2011 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
2013 \line{\it addresses: \hfil}
2017 @c END TEXI2ROFF-KILL
2020 @section @value{AS} Internal Sections
2022 @cindex internal @code{@value{AS}} sections
2023 @cindex sections in messages, internal
2024 These sections are meant only for the internal use of @code{@value{AS}}. They
2025 have no meaning at run-time. You do not really need to know about these
2026 sections for most purposes; but they can be mentioned in @code{@value{AS}}
2027 warning messages, so it might be helpful to have an idea of their
2028 meanings to @code{@value{AS}}. These sections are used to permit the
2029 value of every expression in your assembly language program to be a
2030 section-relative address.
2033 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
2034 @cindex assembler internal logic error
2035 An internal assembler logic error has been found. This means there is a
2036 bug in the assembler.
2039 @cindex expr (internal section)
2040 The assembler stores complex expression internally as combinations of
2041 symbols. When it needs to represent an expression as a symbol, it puts
2042 it in the expr section.
2044 @c FIXME item transfer[t] vector preload
2045 @c FIXME item transfer[t] vector postload
2046 @c FIXME item register
2050 @section Sub-Sections
2052 @cindex numbered subsections
2053 @cindex grouping data
2059 fall into two sections: text and data.
2061 You may have separate groups of
2063 data in named sections
2067 data in named sections
2073 that you want to end up near to each other in the object file, even though they
2074 are not contiguous in the assembler source. @code{@value{AS}} allows you to
2075 use @dfn{subsections} for this purpose. Within each section, there can be
2076 numbered subsections with values from 0 to 8192. Objects assembled into the
2077 same subsection go into the object file together with other objects in the same
2078 subsection. For example, a compiler might want to store constants in the text
2079 section, but might not want to have them interspersed with the program being
2080 assembled. In this case, the compiler could issue a @samp{.text 0} before each
2081 section of code being output, and a @samp{.text 1} before each group of
2082 constants being output.
2084 Subsections are optional. If you do not use subsections, everything
2085 goes in subsection number zero.
2088 Each subsection is zero-padded up to a multiple of four bytes.
2089 (Subsections may be padded a different amount on different flavors
2090 of @code{@value{AS}}.)
2094 On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
2095 boundary (two bytes).
2096 The same is true on the Hitachi SH.
2099 @c FIXME section padding (alignment)?
2100 @c Rich Pixley says padding here depends on target obj code format; that
2101 @c doesn't seem particularly useful to say without further elaboration,
2102 @c so for now I say nothing about it. If this is a generic BFD issue,
2103 @c these paragraphs might need to vanish from this manual, and be
2104 @c discussed in BFD chapter of binutils (or some such).
2107 On the AMD 29K family, no particular padding is added to section or
2108 subsection sizes; @value{AS} forces no alignment on this platform.
2112 Subsections appear in your object file in numeric order, lowest numbered
2113 to highest. (All this to be compatible with other people's assemblers.)
2114 The object file contains no representation of subsections; @code{@value{LD}} and
2115 other programs that manipulate object files see no trace of them.
2116 They just see all your text subsections as a text section, and all your
2117 data subsections as a data section.
2119 To specify which subsection you want subsequent statements assembled
2120 into, use a numeric argument to specify it, in a @samp{.text
2121 @var{expression}} or a @samp{.data @var{expression}} statement.
2124 When generating COFF output, you
2129 can also use an extra subsection
2130 argument with arbitrary named sections: @samp{.section @var{name},
2133 @var{Expression} should be an absolute expression.
2134 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
2135 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
2136 begins in @code{text 0}. For instance:
2138 .text 0 # The default subsection is text 0 anyway.
2139 .ascii "This lives in the first text subsection. *"
2141 .ascii "But this lives in the second text subsection."
2143 .ascii "This lives in the data section,"
2144 .ascii "in the first data subsection."
2146 .ascii "This lives in the first text section,"
2147 .ascii "immediately following the asterisk (*)."
2150 Each section has a @dfn{location counter} incremented by one for every byte
2151 assembled into that section. Because subsections are merely a convenience
2152 restricted to @code{@value{AS}} there is no concept of a subsection location
2153 counter. There is no way to directly manipulate a location counter---but the
2154 @code{.align} directive changes it, and any label definition captures its
2155 current value. The location counter of the section where statements are being
2156 assembled is said to be the @dfn{active} location counter.
2159 @section bss Section
2162 @cindex common variable storage
2163 The bss section is used for local common variable storage.
2164 You may allocate address space in the bss section, but you may
2165 not dictate data to load into it before your program executes. When
2166 your program starts running, all the contents of the bss
2167 section are zeroed bytes.
2169 Addresses in the bss section are allocated with special directives; you
2170 may not assemble anything directly into the bss section. Hence there
2171 are no bss subsections. @xref{Comm,,@code{.comm}},
2172 @pxref{Lcomm,,@code{.lcomm}}.
2178 Symbols are a central concept: the programmer uses symbols to name
2179 things, the linker uses symbols to link, and the debugger uses symbols
2183 @cindex debuggers, and symbol order
2184 @emph{Warning:} @code{@value{AS}} does not place symbols in the object file in
2185 the same order they were declared. This may break some debuggers.
2190 * Setting Symbols:: Giving Symbols Other Values
2191 * Symbol Names:: Symbol Names
2192 * Dot:: The Special Dot Symbol
2193 * Symbol Attributes:: Symbol Attributes
2200 A @dfn{label} is written as a symbol immediately followed by a colon
2201 @samp{:}. The symbol then represents the current value of the
2202 active location counter, and is, for example, a suitable instruction
2203 operand. You are warned if you use the same symbol to represent two
2204 different locations: the first definition overrides any other
2208 On the HPPA, the usual form for a label need not be immediately followed by a
2209 colon, but instead must start in column zero. Only one label may be defined on
2210 a single line. To work around this, the HPPA version of @code{@value{AS}} also
2211 provides a special directive @code{.label} for defining labels more flexibly.
2214 @node Setting Symbols
2215 @section Giving Symbols Other Values
2217 @cindex assigning values to symbols
2218 @cindex symbol values, assigning
2219 A symbol can be given an arbitrary value by writing a symbol, followed
2220 by an equals sign @samp{=}, followed by an expression
2221 (@pxref{Expressions}). This is equivalent to using the @code{.set}
2222 directive. @xref{Set,,@code{.set}}.
2225 @section Symbol Names
2227 @cindex symbol names
2228 @cindex names, symbol
2229 @ifclear SPECIAL-SYMS
2230 Symbol names begin with a letter or with one of @samp{._}. On most
2231 machines, you can also use @code{$} in symbol names; exceptions are
2232 noted in @ref{Machine Dependencies}. That character may be followed by any
2233 string of digits, letters, dollar signs (unless otherwise noted in
2234 @ref{Machine Dependencies}), and underscores.
2237 For the AMD 29K family, @samp{?} is also allowed in the
2238 body of a symbol name, though not at its beginning.
2243 Symbol names begin with a letter or with one of @samp{._}. On the
2245 H8/500, you can also use @code{$} in symbol names. That character may
2246 be followed by any string of digits, letters, dollar signs (save on the
2247 H8/300), and underscores.
2251 Case of letters is significant: @code{foo} is a different symbol name
2254 Each symbol has exactly one name. Each name in an assembly language program
2255 refers to exactly one symbol. You may use that symbol name any number of times
2258 @subheading Local Symbol Names
2260 @cindex local symbol names
2261 @cindex symbol names, local
2262 @cindex temporary symbol names
2263 @cindex symbol names, temporary
2264 Local symbols help compilers and programmers use names temporarily.
2265 There are ten local symbol names, which are re-used throughout the
2266 program. You may refer to them using the names @samp{0} @samp{1}
2267 @dots{} @samp{9}. To define a local symbol, write a label of the form
2268 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
2269 recent previous definition of that symbol write @samp{@b{N}b}, using the
2270 same digit as when you defined the label. To refer to the next
2271 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
2272 a choice of 10 forward references. The @samp{b} stands for
2273 ``backwards'' and the @samp{f} stands for ``forwards''.
2275 Local symbols are not emitted by the current @sc{gnu} C compiler.
2277 There is no restriction on how you can use these labels, but
2278 remember that at any point in the assembly you can refer to at most
2279 10 prior local labels and to at most 10 forward local labels.
2281 Local symbol names are only a notation device. They are immediately
2282 transformed into more conventional symbol names before the assembler
2283 uses them. The symbol names stored in the symbol table, appearing in
2284 error messages and optionally emitted to the object file have these
2289 All local labels begin with @samp{L}. Normally both @code{@value{AS}} and
2290 @code{@value{LD}} forget symbols that start with @samp{L}. These labels are
2291 used for symbols you are never intended to see. If you use the
2292 @samp{-L} option then @code{@value{AS}} retains these symbols in the
2293 object file. If you also instruct @code{@value{LD}} to retain these symbols,
2294 you may use them in debugging.
2297 If the label is written @samp{0:} then the digit is @samp{0}.
2298 If the label is written @samp{1:} then the digit is @samp{1}.
2299 And so on up through @samp{9:}.
2302 This unusual character is included so you do not accidentally invent
2303 a symbol of the same name. The character has ASCII value
2306 @item @emph{ordinal number}
2307 This is a serial number to keep the labels distinct. The first
2308 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
2309 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
2313 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
2314 @code{3:} is named @code{L3@ctrl{A}44}.
2317 @section The Special Dot Symbol
2319 @cindex dot (symbol)
2320 @cindex @code{.} (symbol)
2321 @cindex current address
2322 @cindex location counter
2323 The special symbol @samp{.} refers to the current address that
2324 @code{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
2325 .long .} defines @code{melvin} to contain its own address.
2326 Assigning a value to @code{.} is treated the same as a @code{.org}
2327 directive. Thus, the expression @samp{.=.+4} is the same as saying
2328 @ifclear no-space-dir
2337 @node Symbol Attributes
2338 @section Symbol Attributes
2340 @cindex symbol attributes
2341 @cindex attributes, symbol
2342 Every symbol has, as well as its name, the attributes ``Value'' and
2343 ``Type''. Depending on output format, symbols can also have auxiliary
2346 The detailed definitions are in @file{a.out.h}.
2349 If you use a symbol without defining it, @code{@value{AS}} assumes zero for
2350 all these attributes, and probably won't warn you. This makes the
2351 symbol an externally defined symbol, which is generally what you
2355 * Symbol Value:: Value
2356 * Symbol Type:: Type
2359 * a.out Symbols:: Symbol Attributes: @code{a.out}
2363 * a.out Symbols:: Symbol Attributes: @code{a.out}
2366 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
2371 * COFF Symbols:: Symbol Attributes for COFF
2374 * SOM Symbols:: Symbol Attributes for SOM
2381 @cindex value of a symbol
2382 @cindex symbol value
2383 The value of a symbol is (usually) 32 bits. For a symbol which labels a
2384 location in the text, data, bss or absolute sections the value is the
2385 number of addresses from the start of that section to the label.
2386 Naturally for text, data and bss sections the value of a symbol changes
2387 as @code{@value{LD}} changes section base addresses during linking. Absolute
2388 symbols' values do not change during linking: that is why they are
2391 The value of an undefined symbol is treated in a special way. If it is
2392 0 then the symbol is not defined in this assembler source file, and
2393 @code{@value{LD}} tries to determine its value from other files linked into the
2394 same program. You make this kind of symbol simply by mentioning a symbol
2395 name without defining it. A non-zero value represents a @code{.comm}
2396 common declaration. The value is how much common storage to reserve, in
2397 bytes (addresses). The symbol refers to the first address of the
2403 @cindex type of a symbol
2405 The type attribute of a symbol contains relocation (section)
2406 information, any flag settings indicating that a symbol is external, and
2407 (optionally), other information for linkers and debuggers. The exact
2408 format depends on the object-code output format in use.
2413 @c The following avoids a "widow" subsection title. @group would be
2414 @c better if it were available outside examples.
2417 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
2419 @cindex @code{b.out} symbol attributes
2420 @cindex symbol attributes, @code{b.out}
2421 These symbol attributes appear only when @code{@value{AS}} is configured for
2422 one of the Berkeley-descended object output formats---@code{a.out} or
2428 @subsection Symbol Attributes: @code{a.out}
2430 @cindex @code{a.out} symbol attributes
2431 @cindex symbol attributes, @code{a.out}
2437 @subsection Symbol Attributes: @code{a.out}
2439 @cindex @code{a.out} symbol attributes
2440 @cindex symbol attributes, @code{a.out}
2444 * Symbol Desc:: Descriptor
2445 * Symbol Other:: Other
2449 @subsubsection Descriptor
2451 @cindex descriptor, of @code{a.out} symbol
2452 This is an arbitrary 16-bit value. You may establish a symbol's
2453 descriptor value by using a @code{.desc} statement
2454 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
2458 @subsubsection Other
2460 @cindex other attribute, of @code{a.out} symbol
2461 This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}.
2466 @subsection Symbol Attributes for COFF
2468 @cindex COFF symbol attributes
2469 @cindex symbol attributes, COFF
2471 The COFF format supports a multitude of auxiliary symbol attributes;
2472 like the primary symbol attributes, they are set between @code{.def} and
2473 @code{.endef} directives.
2475 @subsubsection Primary Attributes
2477 @cindex primary attributes, COFF symbols
2478 The symbol name is set with @code{.def}; the value and type,
2479 respectively, with @code{.val} and @code{.type}.
2481 @subsubsection Auxiliary Attributes
2483 @cindex auxiliary attributes, COFF symbols
2484 The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
2485 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2486 information for COFF.
2491 @subsection Symbol Attributes for SOM
2493 @cindex SOM symbol attributes
2494 @cindex symbol attributes, SOM
2496 The SOM format for the HPPA supports a multitude of symbol attributes set with
2497 the @code{.EXPORT} and @code{.IMPORT} directives.
2499 The attributes are described in @cite{HP9000 Series 800 Assembly
2500 Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
2501 @code{EXPORT} assembler directive documentation.
2505 @chapter Expressions
2509 @cindex numeric values
2510 An @dfn{expression} specifies an address or numeric value.
2511 Whitespace may precede and/or follow an expression.
2513 The result of an expression must be an absolute number, or else an offset into
2514 a particular section. If an expression is not absolute, and there is not
2515 enough information when @code{@value{AS}} sees the expression to know its
2516 section, a second pass over the source program might be necessary to interpret
2517 the expression---but the second pass is currently not implemented.
2518 @code{@value{AS}} aborts with an error message in this situation.
2521 * Empty Exprs:: Empty Expressions
2522 * Integer Exprs:: Integer Expressions
2526 @section Empty Expressions
2528 @cindex empty expressions
2529 @cindex expressions, empty
2530 An empty expression has no value: it is just whitespace or null.
2531 Wherever an absolute expression is required, you may omit the
2532 expression, and @code{@value{AS}} assumes a value of (absolute) 0. This
2533 is compatible with other assemblers.
2536 @section Integer Expressions
2538 @cindex integer expressions
2539 @cindex expressions, integer
2540 An @dfn{integer expression} is one or more @emph{arguments} delimited
2541 by @emph{operators}.
2544 * Arguments:: Arguments
2545 * Operators:: Operators
2546 * Prefix Ops:: Prefix Operators
2547 * Infix Ops:: Infix Operators
2551 @subsection Arguments
2553 @cindex expression arguments
2554 @cindex arguments in expressions
2555 @cindex operands in expressions
2556 @cindex arithmetic operands
2557 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2558 contexts arguments are sometimes called ``arithmetic operands''. In
2559 this manual, to avoid confusing them with the ``instruction operands'' of
2560 the machine language, we use the term ``argument'' to refer to parts of
2561 expressions only, reserving the word ``operand'' to refer only to machine
2562 instruction operands.
2564 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2565 @var{section} is one of text, data, bss, absolute,
2566 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2569 Numbers are usually integers.
2571 A number can be a flonum or bignum. In this case, you are warned
2572 that only the low order 32 bits are used, and @code{@value{AS}} pretends
2573 these 32 bits are an integer. You may write integer-manipulating
2574 instructions that act on exotic constants, compatible with other
2577 @cindex subexpressions
2578 Subexpressions are a left parenthesis @samp{(} followed by an integer
2579 expression, followed by a right parenthesis @samp{)}; or a prefix
2580 operator followed by an argument.
2583 @subsection Operators
2585 @cindex operators, in expressions
2586 @cindex arithmetic functions
2587 @cindex functions, in expressions
2588 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2589 operators are followed by an argument. Infix operators appear
2590 between their arguments. Operators may be preceded and/or followed by
2594 @subsection Prefix Operator
2596 @cindex prefix operators
2597 @code{@value{AS}} has the following @dfn{prefix operators}. They each take
2598 one argument, which must be absolute.
2600 @c the tex/end tex stuff surrounding this small table is meant to make
2601 @c it align, on the printed page, with the similar table in the next
2602 @c section (which is inside an enumerate).
2604 \global\advance\leftskip by \itemindent
2609 @dfn{Negation}. Two's complement negation.
2611 @dfn{Complementation}. Bitwise not.
2615 \global\advance\leftskip by -\itemindent
2619 @subsection Infix Operators
2621 @cindex infix operators
2622 @cindex operators, permitted arguments
2623 @dfn{Infix operators} take two arguments, one on either side. Operators
2624 have precedence, but operations with equal precedence are performed left
2625 to right. Apart from @code{+} or @code{-}, both arguments must be
2626 absolute, and the result is absolute.
2629 @cindex operator precedence
2630 @cindex precedence of operators
2637 @dfn{Multiplication}.
2640 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2647 @dfn{Shift Left}. Same as the C operator @samp{<<}.
2651 @dfn{Shift Right}. Same as the C operator @samp{>>}.
2655 Intermediate precedence
2660 @dfn{Bitwise Inclusive Or}.
2666 @dfn{Bitwise Exclusive Or}.
2669 @dfn{Bitwise Or Not}.
2677 @cindex addition, permitted arguments
2678 @cindex plus, permitted arguments
2679 @cindex arguments for addition
2680 @dfn{Addition}. If either argument is absolute, the result has the section of
2681 the other argument. You may not add together arguments from different
2685 @cindex subtraction, permitted arguments
2686 @cindex minus, permitted arguments
2687 @cindex arguments for subtraction
2688 @dfn{Subtraction}. If the right argument is absolute, the
2689 result has the section of the left argument.
2690 If both arguments are in the same section, the result is absolute.
2691 You may not subtract arguments from different sections.
2692 @c FIXME is there still something useful to say about undefined - undefined ?
2696 In short, it's only meaningful to add or subtract the @emph{offsets} in an
2697 address; you can only have a defined section in one of the two arguments.
2700 @chapter Assembler Directives
2702 @cindex directives, machine independent
2703 @cindex pseudo-ops, machine independent
2704 @cindex machine independent directives
2705 All assembler directives have names that begin with a period (@samp{.}).
2706 The rest of the name is letters, usually in lower case.
2708 This chapter discusses directives that are available regardless of the
2709 target machine configuration for the @sc{gnu} assembler.
2711 Some machine configurations provide additional directives.
2712 @xref{Machine Dependencies}.
2715 @ifset machine-directives
2716 @xref{Machine Dependencies} for additional directives.
2721 * Abort:: @code{.abort}
2723 * ABORT:: @code{.ABORT}
2726 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2727 * App-File:: @code{.app-file @var{string}}
2728 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2729 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2730 * Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}}
2731 * Byte:: @code{.byte @var{expressions}}
2732 * Comm:: @code{.comm @var{symbol} , @var{length} }
2733 * Data:: @code{.data @var{subsection}}
2735 * Def:: @code{.def @var{name}}
2738 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2744 * Double:: @code{.double @var{flonums}}
2745 * Eject:: @code{.eject}
2746 * Else:: @code{.else}
2748 * Endef:: @code{.endef}
2751 * Endif:: @code{.endif}
2752 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2753 * Extern:: @code{.extern}
2754 @ifclear no-file-dir
2755 * File:: @code{.file @var{string}}
2758 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2759 * Float:: @code{.float @var{flonums}}
2760 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2761 * hword:: @code{.hword @var{expressions}}
2762 * Ident:: @code{.ident}
2763 * If:: @code{.if @var{absolute expression}}
2764 * Include:: @code{.include "@var{file}"}
2765 * Int:: @code{.int @var{expressions}}
2766 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2767 * Lflags:: @code{.lflags}
2768 @ifclear no-line-dir
2769 * Line:: @code{.line @var{line-number}}
2772 * Ln:: @code{.ln @var{line-number}}
2773 * List:: @code{.list}
2774 * Long:: @code{.long @var{expressions}}
2776 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2779 * Nolist:: @code{.nolist}
2780 * Octa:: @code{.octa @var{bignums}}
2781 * Org:: @code{.org @var{new-lc} , @var{fill}}
2782 * P2align:: @code{.p2align @var{abs-expr} , @var{abs-expr}}
2783 * Psize:: @code{.psize @var{lines}, @var{columns}}
2784 * Quad:: @code{.quad @var{bignums}}
2785 * Sbttl:: @code{.sbttl "@var{subheading}"}
2787 * Scl:: @code{.scl @var{class}}
2790 * Section:: @code{.section @var{name}, @var{subsection}}
2793 * Set:: @code{.set @var{symbol}, @var{expression}}
2794 * Short:: @code{.short @var{expressions}}
2795 * Single:: @code{.single @var{flonums}}
2797 * Size:: @code{.size}
2800 * Space:: @code{.space @var{size} , @var{fill}}
2802 * Stab:: @code{.stabd, .stabn, .stabs}
2805 * String:: @code{.string "@var{str}"}
2807 * Tag:: @code{.tag @var{structname}}
2810 * Text:: @code{.text @var{subsection}}
2811 * Title:: @code{.title "@var{heading}"}
2813 * Type:: @code{.type @var{int}}
2814 * Val:: @code{.val @var{addr}}
2817 * Word:: @code{.word @var{expressions}}
2818 * Deprecated:: Deprecated Directives
2822 @section @code{.abort}
2824 @cindex @code{abort} directive
2825 @cindex stopping the assembly
2826 This directive stops the assembly immediately. It is for
2827 compatibility with other assemblers. The original idea was that the
2828 assembly language source would be piped into the assembler. If the sender
2829 of the source quit, it could use this directive tells @code{@value{AS}} to
2830 quit also. One day @code{.abort} will not be supported.
2834 @section @code{.ABORT}
2836 @cindex @code{ABORT} directive
2837 When producing COFF output, @code{@value{AS}} accepts this directive as a
2838 synonym for @samp{.abort}.
2841 When producing @code{b.out} output, @code{@value{AS}} accepts this directive,
2847 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2849 @cindex padding the location counter
2850 @cindex @code{align} directive
2851 Pad the location counter (in the current subsection) to a particular
2852 storage boundary. The first expression (which must be absolute) is the
2853 alignment required, as described below.
2854 The second expression (also absolute) gives the value to be stored in
2855 the padding bytes. It (and the comma) may be omitted. If it is
2856 omitted, the padding bytes are zero.
2858 The way the required alignment is specified varies from system to system.
2859 For the a29k, HPPA, m86k, m88k, w65, sparc, and i386 using ELF format,
2860 the first expression is the
2861 alignment request in bytes. For example @samp{.align 8} advances
2862 the location counter until it is a multiple of 8. If the location counter
2863 is already a multiple of 8, no change is needed.
2865 For other systems, including the i386 using a.out format, it is the
2866 number of low-order zero bits the location counter must have after
2867 advancement. For example @samp{.align 3} advances the location
2868 counter until it a multiple of 8. If the location counter is already a
2869 multiple of 8, no change is needed.
2871 This inconsistency is due to the different behaviors of the various
2872 native assemblers for these systems which GAS must emulate.
2873 GAS also provides @code{.balign} and @code{.p2align} directives,
2874 described later, which have a consistent behavior across all
2875 architectures (but are specific to GAS).
2878 @section @code{.app-file @var{string}}
2880 @cindex logical file name
2881 @cindex file name, logical
2882 @cindex @code{app-file} directive
2884 @ifclear no-file-dir
2885 (which may also be spelled @samp{.file})
2887 tells @code{@value{AS}} that we are about to start a new
2888 logical file. @var{string} is the new file name. In general, the
2889 filename is recognized whether or not it is surrounded by quotes @samp{"};
2890 but if you wish to specify an empty file name is permitted,
2891 you must give the quotes--@code{""}. This statement may go away in
2892 future: it is only recognized to be compatible with old @code{@value{AS}}
2896 @section @code{.ascii "@var{string}"}@dots{}
2898 @cindex @code{ascii} directive
2899 @cindex string literals
2900 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2901 separated by commas. It assembles each string (with no automatic
2902 trailing zero byte) into consecutive addresses.
2905 @section @code{.asciz "@var{string}"}@dots{}
2907 @cindex @code{asciz} directive
2908 @cindex zero-terminated strings
2909 @cindex null-terminated strings
2910 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2911 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2914 @section @code{.balign @var{abs-expr} , @var{abs-expr}}
2916 @cindex padding the location counter given number of bytes
2917 @cindex @code{balign} directive
2918 Pad the location counter (in the current subsection) to a particular
2919 storage boundary. The first expression (which must be absolute) is the
2920 alignment request in bytes. For example @samp{.balign 8} advances
2921 the location counter until it is a multiple of 8. If the location counter
2922 is already a multiple of 8, no change is needed.
2924 The second expression (also absolute) gives the value to be stored in
2925 the padding bytes. It (and the comma) may be omitted. If it is
2926 omitted, the padding bytes are zero.
2929 @section @code{.byte @var{expressions}}
2931 @cindex @code{byte} directive
2932 @cindex integers, one byte
2933 @code{.byte} expects zero or more expressions, separated by commas.
2934 Each expression is assembled into the next byte.
2937 @section @code{.comm @var{symbol} , @var{length} }
2939 @cindex @code{comm} directive
2940 @cindex symbol, common
2941 @code{.comm} declares a named common area in the bss section. Normally
2942 @code{@value{LD}} reserves memory addresses for it during linking, so no partial
2943 program defines the location of the symbol. Use @code{.comm} to tell
2944 @code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}}
2945 allocates space for each @code{.comm} symbol that is at least as
2946 long as the longest @code{.comm} request in any of the partial programs
2947 linked. @var{length} is an absolute expression.
2950 The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
2951 @samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
2955 @section @code{.data @var{subsection}}
2957 @cindex @code{data} directive
2958 @code{.data} tells @code{@value{AS}} to assemble the following statements onto the
2959 end of the data subsection numbered @var{subsection} (which is an
2960 absolute expression). If @var{subsection} is omitted, it defaults
2965 @section @code{.def @var{name}}
2967 @cindex @code{def} directive
2968 @cindex COFF symbols, debugging
2969 @cindex debugging COFF symbols
2970 Begin defining debugging information for a symbol @var{name}; the
2971 definition extends until the @code{.endef} directive is encountered.
2974 This directive is only observed when @code{@value{AS}} is configured for COFF
2975 format output; when producing @code{b.out}, @samp{.def} is recognized,
2982 @section @code{.desc @var{symbol}, @var{abs-expression}}
2984 @cindex @code{desc} directive
2985 @cindex COFF symbol descriptor
2986 @cindex symbol descriptor, COFF
2987 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2988 to the low 16 bits of an absolute expression.
2991 The @samp{.desc} directive is not available when @code{@value{AS}} is
2992 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2993 object format. For the sake of compatibility, @code{@value{AS}} accepts
2994 it, but produces no output, when configured for COFF.
3000 @section @code{.dim}
3002 @cindex @code{dim} directive
3003 @cindex COFF auxiliary symbol information
3004 @cindex auxiliary symbol information, COFF
3005 This directive is generated by compilers to include auxiliary debugging
3006 information in the symbol table. It is only permitted inside
3007 @code{.def}/@code{.endef} pairs.
3010 @samp{.dim} is only meaningful when generating COFF format output; when
3011 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3017 @section @code{.double @var{flonums}}
3019 @cindex @code{double} directive
3020 @cindex floating point numbers (double)
3021 @code{.double} expects zero or more flonums, separated by commas. It
3022 assembles floating point numbers.
3024 The exact kind of floating point numbers emitted depends on how
3025 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
3029 On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
3030 in @sc{ieee} format.
3035 @section @code{.eject}
3037 @cindex @code{eject} directive
3038 @cindex new page, in listings
3039 @cindex page, in listings
3040 @cindex listing control: new page
3041 Force a page break at this point, when generating assembly listings.
3044 @section @code{.else}
3046 @cindex @code{else} directive
3047 @code{.else} is part of the @code{@value{AS}} support for conditional
3048 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
3049 of code to be assembled if the condition for the preceding @code{.if}
3053 @node End, Endef, Else, Pseudo Ops
3054 @section @code{.end}
3056 @cindex @code{end} directive
3057 This doesn't do anything---but isn't an s_ignore, so I suspect it's
3058 meant to do something eventually (which is why it isn't documented here
3059 as "for compatibility with blah").
3064 @section @code{.endef}
3066 @cindex @code{endef} directive
3067 This directive flags the end of a symbol definition begun with
3071 @samp{.endef} is only meaningful when generating COFF format output; if
3072 @code{@value{AS}} is configured to generate @code{b.out}, it accepts this
3073 directive but ignores it.
3078 @section @code{.endif}
3080 @cindex @code{endif} directive
3081 @code{.endif} is part of the @code{@value{AS}} support for conditional assembly;
3082 it marks the end of a block of code that is only assembled
3083 conditionally. @xref{If,,@code{.if}}.
3086 @section @code{.equ @var{symbol}, @var{expression}}
3088 @cindex @code{equ} directive
3089 @cindex assigning values to symbols
3090 @cindex symbols, assigning values to
3091 This directive sets the value of @var{symbol} to @var{expression}.
3092 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
3095 The syntax for @code{equ} on the HPPA is
3096 @samp{@var{symbol} .equ @var{expression}}.
3100 @section @code{.extern}
3102 @cindex @code{extern} directive
3103 @code{.extern} is accepted in the source program---for compatibility
3104 with other assemblers---but it is ignored. @code{@value{AS}} treats
3105 all undefined symbols as external.
3107 @ifclear no-file-dir
3109 @section @code{.file @var{string}}
3111 @cindex @code{file} directive
3112 @cindex logical file name
3113 @cindex file name, logical
3114 @code{.file} (which may also be spelled @samp{.app-file}) tells
3115 @code{@value{AS}} that we are about to start a new logical file.
3116 @var{string} is the new file name. In general, the filename is
3117 recognized whether or not it is surrounded by quotes @samp{"}; but if
3118 you wish to specify an empty file name, you must give the
3119 quotes--@code{""}. This statement may go away in future: it is only
3120 recognized to be compatible with old @code{@value{AS}} programs.
3122 In some configurations of @code{@value{AS}}, @code{.file} has already been
3123 removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}.
3128 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
3130 @cindex @code{fill} directive
3131 @cindex writing patterns in memory
3132 @cindex patterns, writing in memory
3133 @var{result}, @var{size} and @var{value} are absolute expressions.
3134 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
3135 may be zero or more. @var{Size} may be zero or more, but if it is
3136 more than 8, then it is deemed to have the value 8, compatible with
3137 other people's assemblers. The contents of each @var{repeat} bytes
3138 is taken from an 8-byte number. The highest order 4 bytes are
3139 zero. The lowest order 4 bytes are @var{value} rendered in the
3140 byte-order of an integer on the computer @code{@value{AS}} is assembling for.
3141 Each @var{size} bytes in a repetition is taken from the lowest order
3142 @var{size} bytes of this number. Again, this bizarre behavior is
3143 compatible with other people's assemblers.
3145 @var{size} and @var{value} are optional.
3146 If the second comma and @var{value} are absent, @var{value} is
3147 assumed zero. If the first comma and following tokens are absent,
3148 @var{size} is assumed to be 1.
3151 @section @code{.float @var{flonums}}
3153 @cindex floating point numbers (single)
3154 @cindex @code{float} directive
3155 This directive assembles zero or more flonums, separated by commas. It
3156 has the same effect as @code{.single}.
3158 The exact kind of floating point numbers emitted depends on how
3159 @code{@value{AS}} is configured.
3160 @xref{Machine Dependencies}.
3164 On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
3165 in @sc{ieee} format.
3170 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
3172 @cindex @code{global} directive
3173 @cindex symbol, making visible to linker
3174 @code{.global} makes the symbol visible to @code{@value{LD}}. If you define
3175 @var{symbol} in your partial program, its value is made available to
3176 other partial programs that are linked with it. Otherwise,
3177 @var{symbol} takes its attributes from a symbol of the same name
3178 from another file linked into the same program.
3180 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
3181 compatibility with other assemblers.
3184 On the HPPA, @code{.global} is not always enough to make it accessible to other
3185 partial programs. You may need the HPPA-only @code{.EXPORT} directive as well.
3186 @xref{HPPA Directives,, HPPA Assembler Directives}.
3190 @section @code{.hword @var{expressions}}
3192 @cindex @code{hword} directive
3193 @cindex integers, 16-bit
3194 @cindex numbers, 16-bit
3195 @cindex sixteen bit integers
3196 This expects zero or more @var{expressions}, and emits
3197 a 16 bit number for each.
3200 This directive is a synonym for @samp{.short}; depending on the target
3201 architecture, it may also be a synonym for @samp{.word}.
3205 This directive is a synonym for @samp{.short}.
3208 This directive is a synonym for both @samp{.short} and @samp{.word}.
3213 @section @code{.ident}
3215 @cindex @code{ident} directive
3216 This directive is used by some assemblers to place tags in object files.
3217 @code{@value{AS}} simply accepts the directive for source-file
3218 compatibility with such assemblers, but does not actually emit anything
3222 @section @code{.if @var{absolute expression}}
3224 @cindex conditional assembly
3225 @cindex @code{if} directive
3226 @code{.if} marks the beginning of a section of code which is only
3227 considered part of the source program being assembled if the argument
3228 (which must be an @var{absolute expression}) is non-zero. The end of
3229 the conditional section of code must be marked by @code{.endif}
3230 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
3231 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
3233 The following variants of @code{.if} are also supported:
3235 @item .ifdef @var{symbol}
3236 @cindex @code{ifdef} directive
3237 Assembles the following section of code if the specified @var{symbol}
3242 @cindex @code{ifeqs} directive
3243 Not yet implemented.
3246 @item .ifndef @var{symbol}
3247 @itemx ifnotdef @var{symbol}
3248 @cindex @code{ifndef} directive
3249 @cindex @code{ifnotdef} directive
3250 Assembles the following section of code if the specified @var{symbol}
3251 has not been defined. Both spelling variants are equivalent.
3255 Not yet implemented.
3260 @section @code{.include "@var{file}"}
3262 @cindex @code{include} directive
3263 @cindex supporting files, including
3264 @cindex files, including
3265 This directive provides a way to include supporting files at specified
3266 points in your source program. The code from @var{file} is assembled as
3267 if it followed the point of the @code{.include}; when the end of the
3268 included file is reached, assembly of the original file continues. You
3269 can control the search paths used with the @samp{-I} command-line option
3270 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
3274 @section @code{.int @var{expressions}}
3276 @cindex @code{int} directive
3277 @cindex integers, 32-bit
3278 Expect zero or more @var{expressions}, of any section, separated by commas.
3279 For each expression, emit a number that, at run time, is the value of that
3280 expression. The byte order and bit size of the number depends on what kind
3281 of target the assembly is for.
3285 On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
3286 integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits
3292 @section @code{.lcomm @var{symbol} , @var{length}}
3294 @cindex @code{lcomm} directive
3295 @cindex local common symbols
3296 @cindex symbols, local common
3297 Reserve @var{length} (an absolute expression) bytes for a local common
3298 denoted by @var{symbol}. The section and value of @var{symbol} are
3299 those of the new local common. The addresses are allocated in the bss
3300 section, so that at run-time the bytes start off zeroed. @var{Symbol}
3301 is not declared global (@pxref{Global,,@code{.global}}), so is normally
3302 not visible to @code{@value{LD}}.
3305 The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
3306 @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
3310 @section @code{.lflags}
3312 @cindex @code{lflags} directive (ignored)
3313 @code{@value{AS}} accepts this directive, for compatibility with other
3314 assemblers, but ignores it.
3316 @ifclear no-line-dir
3318 @section @code{.line @var{line-number}}
3320 @cindex @code{line} directive
3324 @section @code{.ln @var{line-number}}
3326 @cindex @code{ln} directive
3328 @cindex logical line number
3330 Change the logical line number. @var{line-number} must be an absolute
3331 expression. The next line has that logical line number. Therefore any other
3332 statements on the current line (after a statement separator character) are
3333 reported as on logical line number @var{line-number} @minus{} 1. One day
3334 @code{@value{AS}} will no longer support this directive: it is recognized only
3335 for compatibility with existing assembler programs.
3339 @emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
3340 not available; use the synonym @code{.ln} in that context.
3345 @ifclear no-line-dir
3346 Even though this is a directive associated with the @code{a.out} or
3347 @code{b.out} object-code formats, @code{@value{AS}} still recognizes it
3348 when producing COFF output, and treats @samp{.line} as though it
3349 were the COFF @samp{.ln} @emph{if} it is found outside a
3350 @code{.def}/@code{.endef} pair.
3352 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
3353 used by compilers to generate auxiliary symbol information for
3358 @section @code{.ln @var{line-number}}
3360 @cindex @code{ln} directive
3361 @ifclear no-line-dir
3362 @samp{.ln} is a synonym for @samp{.line}.
3365 Tell @code{@value{AS}} to change the logical line number. @var{line-number}
3366 must be an absolute expression. The next line has that logical
3367 line number, so any other statements on the current line (after a
3368 statement separator character @code{;}) are reported as on logical
3369 line number @var{line-number} @minus{} 1.
3372 This directive is accepted, but ignored, when @code{@value{AS}} is
3373 configured for @code{b.out}; its effect is only associated with COFF
3379 @section @code{.list}
3381 @cindex @code{list} directive
3382 @cindex listing control, turning on
3383 Control (in conjunction with the @code{.nolist} directive) whether or
3384 not assembly listings are generated. These two directives maintain an
3385 internal counter (which is zero initially). @code{.list} increments the
3386 counter, and @code{.nolist} decrements it. Assembly listings are
3387 generated whenever the counter is greater than zero.
3389 By default, listings are disabled. When you enable them (with the
3390 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
3391 the initial value of the listing counter is one.
3394 @section @code{.long @var{expressions}}
3396 @cindex @code{long} directive
3397 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
3400 @c no one seems to know what this is for or whether this description is
3401 @c what it really ought to do
3403 @section @code{.lsym @var{symbol}, @var{expression}}
3405 @cindex @code{lsym} directive
3406 @cindex symbol, not referenced in assembly
3407 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
3408 the hash table, ensuring it cannot be referenced by name during the
3409 rest of the assembly. This sets the attributes of the symbol to be
3410 the same as the expression value:
3412 @var{other} = @var{descriptor} = 0
3413 @var{type} = @r{(section of @var{expression})}
3414 @var{value} = @var{expression}
3417 The new symbol is not flagged as external.
3421 @section @code{.nolist}
3423 @cindex @code{nolist} directive
3424 @cindex listing control, turning off
3425 Control (in conjunction with the @code{.list} directive) whether or
3426 not assembly listings are generated. These two directives maintain an
3427 internal counter (which is zero initially). @code{.list} increments the
3428 counter, and @code{.nolist} decrements it. Assembly listings are
3429 generated whenever the counter is greater than zero.
3432 @section @code{.octa @var{bignums}}
3434 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
3435 @cindex @code{octa} directive
3436 @cindex integer, 16-byte
3437 @cindex sixteen byte integer
3438 This directive expects zero or more bignums, separated by commas. For each
3439 bignum, it emits a 16-byte integer.
3441 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
3442 hence @emph{octa}-word for 16 bytes.
3445 @section @code{.org @var{new-lc} , @var{fill}}
3447 @cindex @code{org} directive
3448 @cindex location counter, advancing
3449 @cindex advancing location counter
3450 @cindex current address, advancing
3451 Advance the location counter of the current section to
3452 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3453 expression with the same section as the current subsection. That is,
3454 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3455 wrong section, the @code{.org} directive is ignored. To be compatible
3456 with former assemblers, if the section of @var{new-lc} is absolute,
3457 @code{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
3458 is the same as the current subsection.
3460 @code{.org} may only increase the location counter, or leave it
3461 unchanged; you cannot use @code{.org} to move the location counter
3464 @c double negative used below "not undefined" because this is a specific
3465 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3466 @c section. pesch@cygnus.com 18feb91
3467 Because @code{@value{AS}} tries to assemble programs in one pass, @var{new-lc}
3468 may not be undefined. If you really detest this restriction we eagerly await
3469 a chance to share your improved assembler.
3471 Beware that the origin is relative to the start of the section, not
3472 to the start of the subsection. This is compatible with other
3473 people's assemblers.
3475 When the location counter (of the current subsection) is advanced, the
3476 intervening bytes are filled with @var{fill} which should be an
3477 absolute expression. If the comma and @var{fill} are omitted,
3478 @var{fill} defaults to zero.
3481 @section @code{.p2align @var{abs-expr} , @var{abs-expr}}
3483 @cindex padding the location counter given a power of two
3484 @cindex @code{p2align} directive
3485 Pad the location counter (in the current subsection) to a particular
3486 storage boundary. The first expression (which must be absolute) is the
3487 number of low-order zero bits the location counter must have after
3488 advancement. For example @samp{.p2align 3} advances the location
3489 counter until it a multiple of 8. If the location counter is already a
3490 multiple of 8, no change is needed.
3492 The second expression (also absolute) gives the value to be stored in
3493 the padding bytes. It (and the comma) may be omitted. If it is
3494 omitted, the padding bytes are zero.
3497 @section @code{.psize @var{lines} , @var{columns}}
3499 @cindex @code{psize} directive
3500 @cindex listing control: paper size
3501 @cindex paper size, for listings
3502 Use this directive to declare the number of lines---and, optionally, the
3503 number of columns---to use for each page, when generating listings.
3505 If you do not use @code{.psize}, listings use a default line-count
3506 of 60. You may omit the comma and @var{columns} specification; the
3507 default width is 200 columns.
3509 @code{@value{AS}} generates formfeeds whenever the specified number of
3510 lines is exceeded (or whenever you explicitly request one, using
3513 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3514 those explicitly specified with @code{.eject}.
3517 @section @code{.quad @var{bignums}}
3519 @cindex @code{quad} directive
3520 @code{.quad} expects zero or more bignums, separated by commas. For
3521 each bignum, it emits
3523 an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
3524 warning message; and just takes the lowest order 8 bytes of the bignum.
3525 @cindex eight-byte integer
3526 @cindex integer, 8-byte
3528 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3529 hence @emph{quad}-word for 8 bytes.
3532 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3533 warning message; and just takes the lowest order 16 bytes of the bignum.
3534 @cindex sixteen-byte integer
3535 @cindex integer, 16-byte
3539 @section @code{.sbttl "@var{subheading}"}
3541 @cindex @code{sbttl} directive
3542 @cindex subtitles for listings
3543 @cindex listing control: subtitle
3544 Use @var{subheading} as the title (third line, immediately after the
3545 title line) when generating assembly listings.
3547 This directive affects subsequent pages, as well as the current page if
3548 it appears within ten lines of the top of a page.
3552 @section @code{.scl @var{class}}
3554 @cindex @code{scl} directive
3555 @cindex symbol storage class (COFF)
3556 @cindex COFF symbol storage class
3557 Set the storage-class value for a symbol. This directive may only be
3558 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3559 whether a symbol is static or external, or it may record further
3560 symbolic debugging information.
3563 The @samp{.scl} directive is primarily associated with COFF output; when
3564 configured to generate @code{b.out} output format, @code{@value{AS}}
3565 accepts this directive but ignores it.
3571 @section @code{.section @var{name}, @var{subsection}}
3573 @cindex @code{section} directive
3574 @cindex named section (COFF)
3575 @cindex COFF named section
3576 Assemble the following code into end of subsection numbered
3577 @var{subsection} in the COFF named section @var{name}. If you omit
3578 @var{subsection}, @code{@value{AS}} uses subsection number zero.
3579 @samp{.section .text} is equivalent to the @code{.text} directive;
3580 @samp{.section .data} is equivalent to the @code{.data} directive.
3582 This directive is only supported for targets that actually support arbitrarily
3583 named sections; on @code{a.out} targets, for example, it is not accepted, even
3584 with a standard @code{a.out} section name as its parameter.
3589 @section @code{.set @var{symbol}, @var{expression}}
3591 @cindex @code{set} directive
3592 @cindex symbol value, setting
3593 Set the value of @var{symbol} to @var{expression}. This
3594 changes @var{symbol}'s value and type to conform to
3595 @var{expression}. If @var{symbol} was flagged as external, it remains
3596 flagged. (@xref{Symbol Attributes}.)
3598 You may @code{.set} a symbol many times in the same assembly.
3600 If you @code{.set} a global symbol, the value stored in the object
3601 file is the last value stored into it.
3604 The syntax for @code{set} on the HPPA is
3605 @samp{@var{symbol} .set @var{expression}}.
3609 @section @code{.short @var{expressions}}
3611 @cindex @code{short} directive
3613 @code{.short} is normally the same as @samp{.word}.
3614 @xref{Word,,@code{.word}}.
3616 In some configurations, however, @code{.short} and @code{.word} generate
3617 numbers of different lengths; @pxref{Machine Dependencies}.
3621 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3624 This expects zero or more @var{expressions}, and emits
3625 a 16 bit number for each.
3630 @section @code{.single @var{flonums}}
3632 @cindex @code{single} directive
3633 @cindex floating point numbers (single)
3634 This directive assembles zero or more flonums, separated by commas. It
3635 has the same effect as @code{.float}.
3637 The exact kind of floating point numbers emitted depends on how
3638 @code{@value{AS}} is configured. @xref{Machine Dependencies}.
3642 On the @value{TARGET} family, @code{.single} emits 32-bit floating point
3643 numbers in @sc{ieee} format.
3649 @section @code{.size}
3651 @cindex @code{size} directive
3652 This directive is generated by compilers to include auxiliary debugging
3653 information in the symbol table. It is only permitted inside
3654 @code{.def}/@code{.endef} pairs.
3657 @samp{.size} is only meaningful when generating COFF format output; when
3658 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3663 @ifclear no-space-dir
3665 @section @code{.space @var{size} , @var{fill}}
3667 @cindex @code{space} directive
3668 @cindex filling memory
3669 This directive emits @var{size} bytes, each of value @var{fill}. Both
3670 @var{size} and @var{fill} are absolute expressions. If the comma
3671 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3675 @emph{Warning:} @code{.space} has a completely different meaning for HPPA
3676 targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800
3677 Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the
3678 @code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives},
3687 @section @code{.space}
3688 @cindex @code{space} directive
3690 On the AMD 29K, this directive is ignored; it is accepted for
3691 compatibility with other AMD 29K assemblers.
3694 @emph{Warning:} In most versions of the @sc{gnu} assembler, the directive
3695 @code{.space} has the effect of @code{.block} @xref{Machine Dependencies}.
3701 @section @code{.stabd, .stabn, .stabs}
3703 @cindex symbolic debuggers, information for
3704 @cindex @code{stab@var{x}} directives
3705 There are three directives that begin @samp{.stab}.
3706 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3707 The symbols are not entered in the @code{@value{AS}} hash table: they
3708 cannot be referenced elsewhere in the source file.
3709 Up to five fields are required:
3713 This is the symbol's name. It may contain any character except
3714 @samp{\000}, so is more general than ordinary symbol names. Some
3715 debuggers used to code arbitrarily complex structures into symbol names
3719 An absolute expression. The symbol's type is set to the low 8 bits of
3720 this expression. Any bit pattern is permitted, but @code{@value{LD}}
3721 and debuggers choke on silly bit patterns.
3724 An absolute expression. The symbol's ``other'' attribute is set to the
3725 low 8 bits of this expression.
3728 An absolute expression. The symbol's descriptor is set to the low 16
3729 bits of this expression.
3732 An absolute expression which becomes the symbol's value.
3735 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3736 or @code{.stabs} statement, the symbol has probably already been created;
3737 you get a half-formed symbol in your object file. This is
3738 compatible with earlier assemblers!
3741 @cindex @code{stabd} directive
3742 @item .stabd @var{type} , @var{other} , @var{desc}
3744 The ``name'' of the symbol generated is not even an empty string.
3745 It is a null pointer, for compatibility. Older assemblers used a
3746 null pointer so they didn't waste space in object files with empty
3749 The symbol's value is set to the location counter,
3750 relocatably. When your program is linked, the value of this symbol
3751 is the address of the location counter when the @code{.stabd} was
3754 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3755 @cindex @code{stabn} directive
3756 The name of the symbol is set to the empty string @code{""}.
3758 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3759 @cindex @code{stabs} directive
3760 All five fields are specified.
3766 @section @code{.string} "@var{str}"
3768 @cindex string, copying to object file
3769 @cindex @code{string} directive
3771 Copy the characters in @var{str} to the object file. You may specify more than
3772 one string to copy, separated by commas. Unless otherwise specified for a
3773 particular machine, the assembler marks the end of each string with a 0 byte.
3774 You can use any of the escape sequences described in @ref{Strings,,Strings}.
3778 @section @code{.tag @var{structname}}
3780 @cindex COFF structure debugging
3781 @cindex structure debugging, COFF
3782 @cindex @code{tag} directive
3783 This directive is generated by compilers to include auxiliary debugging
3784 information in the symbol table. It is only permitted inside
3785 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3786 definitions in the symbol table with instances of those structures.
3789 @samp{.tag} is only used when generating COFF format output; when
3790 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3796 @section @code{.text @var{subsection}}
3798 @cindex @code{text} directive
3799 Tells @code{@value{AS}} to assemble the following statements onto the end of
3800 the text subsection numbered @var{subsection}, which is an absolute
3801 expression. If @var{subsection} is omitted, subsection number zero
3805 @section @code{.title "@var{heading}"}
3807 @cindex @code{title} directive
3808 @cindex listing control: title line
3809 Use @var{heading} as the title (second line, immediately after the
3810 source file name and pagenumber) when generating assembly listings.
3812 This directive affects subsequent pages, as well as the current page if
3813 it appears within ten lines of the top of a page.
3817 @section @code{.type @var{int}}
3819 @cindex COFF symbol type
3820 @cindex symbol type, COFF
3821 @cindex @code{type} directive
3822 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3823 records the integer @var{int} as the type attribute of a symbol table entry.
3826 @samp{.type} is associated only with COFF format output; when
3827 @code{@value{AS}} is configured for @code{b.out} output, it accepts this
3828 directive but ignores it.
3834 @section @code{.val @var{addr}}
3836 @cindex @code{val} directive
3837 @cindex COFF value attribute
3838 @cindex value attribute, COFF
3839 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3840 records the address @var{addr} as the value attribute of a symbol table
3844 @samp{.val} is used only for COFF output; when @code{@value{AS}} is
3845 configured for @code{b.out}, it accepts this directive but ignores it.
3850 @section @code{.word @var{expressions}}
3852 @cindex @code{word} directive
3853 This directive expects zero or more @var{expressions}, of any section,
3854 separated by commas.
3857 For each expression, @code{@value{AS}} emits a 32-bit number.
3860 For each expression, @code{@value{AS}} emits a 16-bit number.
3865 The size of the number emitted, and its byte order,
3866 depend on what target computer the assembly is for.
3869 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3870 @c happen---32-bit addressability, period; no long/short jumps.
3871 @ifset DIFF-TBL-KLUGE
3872 @cindex difference tables altered
3873 @cindex altered difference tables
3875 @emph{Warning: Special Treatment to support Compilers}
3879 Machines with a 32-bit address space, but that do less than 32-bit
3880 addressing, require the following special treatment. If the machine of
3881 interest to you does 32-bit addressing (or doesn't require it;
3882 @pxref{Machine Dependencies}), you can ignore this issue.
3885 In order to assemble compiler output into something that works,
3886 @code{@value{AS}} occasionlly does strange things to @samp{.word} directives.
3887 Directives of the form @samp{.word sym1-sym2} are often emitted by
3888 compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a
3889 directive of the form @samp{.word sym1-sym2}, and the difference between
3890 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}}
3891 creates a @dfn{secondary jump table}, immediately before the next label.
3892 This secondary jump table is preceded by a short-jump to the
3893 first byte after the secondary table. This short-jump prevents the flow
3894 of control from accidentally falling into the new table. Inside the
3895 table is a long-jump to @code{sym2}. The original @samp{.word}
3896 contains @code{sym1} minus the address of the long-jump to
3899 If there were several occurrences of @samp{.word sym1-sym2} before the
3900 secondary jump table, all of them are adjusted. If there was a
3901 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3902 long-jump to @code{sym4} is included in the secondary jump table,
3903 and the @code{.word} directives are adjusted to contain @code{sym3}
3904 minus the address of the long-jump to @code{sym4}; and so on, for as many
3905 entries in the original jump table as necessary.
3908 @emph{This feature may be disabled by compiling @code{@value{AS}} with the
3909 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3910 assembly language programmers.
3913 @c end DIFF-TBL-KLUGE
3916 @section Deprecated Directives
3918 @cindex deprecated directives
3919 @cindex obsolescent directives
3920 One day these directives won't work.
3921 They are included for compatibility with older assemblers.
3929 @node Machine Dependencies
3930 @chapter Machine Dependent Features
3932 @cindex machine dependencies
3933 The machine instruction sets are (almost by definition) different on
3934 each machine where @code{@value{AS}} runs. Floating point representations
3935 vary as well, and @code{@value{AS}} often supports a few additional
3936 directives or command-line options for compatibility with other
3937 assemblers on a particular platform. Finally, some versions of
3938 @code{@value{AS}} support special pseudo-instructions for branch
3941 This chapter discusses most of these differences, though it does not
3942 include details on any machine's instruction set. For details on that
3943 subject, see the hardware manufacturer's manual.
3946 @c start-sanitize-arc
3948 * ARC-Dependent:: ARC Dependent Features
3952 * Vax-Dependent:: VAX Dependent Features
3955 * AMD29K-Dependent:: AMD 29K Dependent Features
3958 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
3961 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
3964 * HPPA-Dependent:: HPPA Dependent Features
3967 * SH-Dependent:: Hitachi SH Dependent Features
3970 * i960-Dependent:: Intel 80960 Dependent Features
3973 * M68K-Dependent:: M680x0 Dependent Features
3976 * Sparc-Dependent:: SPARC Dependent Features
3979 * Z8000-Dependent:: Z8000 Dependent Features
3982 * MIPS-Dependent:: MIPS Dependent Features
3985 * i386-Dependent:: 80386 Dependent Features
3992 @c The following major nodes are *sections* in the GENERIC version, *chapters*
3993 @c in single-cpu versions. This is mainly achieved by @lowersections. There is a
3994 @c peculiarity: to preserve cross-references, there must be a node called
3995 @c "Machine Dependencies". Hence the conditional nodenames in each
3996 @c major node below. Node defaulting in makeinfo requires adjacency of
3997 @c node and sectioning commands; hence the repetition of @chapter BLAH
3998 @c in both conditional blocks.
4000 @c start-sanitize-arc
4005 @chapter ARC Dependent Features
4008 @node Machine Dependencies
4009 @chapter ARC Dependent Features
4014 * ARC-Opts:: Options
4015 * ARC-Float:: Floating Point
4016 * ARC-Directives:: Sparc Machine Directives
4022 @cindex options for ARC
4024 @cindex architectures, ARC
4025 @cindex ARC architectures
4026 The ARC chip family includes several successive levels (or other
4027 variants) of chip, using the same core instruction set, but including
4028 a few additional instructions at each level.
4030 By default, @code{@value{AS}} assumes the core instruction set (ARC
4031 base). The @code{.cpu} pseudo-op is used to select a different variant.
4034 @cindex @code{-mbig-endian} option (ARC)
4035 @cindex @code{-mlittle-endian} option (ARC)
4036 @cindex ARC big-endian output
4037 @cindex ARC little-endian output
4038 @cindex big-endian output, ARC
4039 @cindex little-endian output, ARC
4041 @itemx -mlittle-endian
4042 Any @sc{arc} configuration of @code{@value{AS}} can select big-endian or
4043 little-endian output at run time (unlike most other @sc{gnu} development
4044 tools, which must be configured for one or the other). Use
4045 @samp{-mbig-endian} to select big-endian output, and @samp{-mlittle-endian}
4050 @section Floating Point
4052 @cindex floating point, ARC (@sc{ieee})
4053 @cindex ARC floating point (@sc{ieee})
4054 The ARC cpu family currently does not have hardware floating point
4055 support. Software floating point support is provided by @code{GCC}
4056 and uses @sc{ieee} floating-point numbers.
4058 @node ARC-Directives
4059 @section ARC Machine Directives
4061 @cindex ARC machine directives
4062 @cindex machine directives, ARC
4063 The ARC version of @code{@value{AS}} supports the following additional
4068 @cindex @code{cpu} directive, SPARC
4069 This must be followed by the desired cpu. It must be one of
4070 @code{base}, @code{host}, @code{graphics}, or @code{audio}.
4080 @chapter VAX Dependent Features
4085 @node Machine Dependencies
4086 @chapter VAX Dependent Features
4092 * Vax-Opts:: VAX Command-Line Options
4093 * VAX-float:: VAX Floating Point
4094 * VAX-directives:: Vax Machine Directives
4095 * VAX-opcodes:: VAX Opcodes
4096 * VAX-branch:: VAX Branch Improvement
4097 * VAX-operands:: VAX Operands
4098 * VAX-no:: Not Supported on VAX
4103 @section VAX Command-Line Options
4105 @cindex command-line options ignored, VAX
4106 @cindex VAX command-line options ignored
4107 The Vax version of @code{@value{AS}} accepts any of the following options,
4108 gives a warning message that the option was ignored and proceeds.
4109 These options are for compatibility with scripts designed for other
4110 people's assemblers.
4113 @item @code{-D} (Debug)
4114 @itemx @code{-S} (Symbol Table)
4115 @itemx @code{-T} (Token Trace)
4116 @cindex @code{-D}, ignored on VAX
4117 @cindex @code{-S}, ignored on VAX
4118 @cindex @code{-T}, ignored on VAX
4119 These are obsolete options used to debug old assemblers.
4121 @item @code{-d} (Displacement size for JUMPs)
4122 @cindex @code{-d}, VAX option
4123 This option expects a number following the @samp{-d}. Like options
4124 that expect filenames, the number may immediately follow the
4125 @samp{-d} (old standard) or constitute the whole of the command line
4126 argument that follows @samp{-d} (@sc{gnu} standard).
4128 @item @code{-V} (Virtualize Interpass Temporary File)
4129 @cindex @code{-V}, redundant on VAX
4130 Some other assemblers use a temporary file. This option
4131 commanded them to keep the information in active memory rather
4132 than in a disk file. @code{@value{AS}} always does this, so this
4133 option is redundant.
4135 @item @code{-J} (JUMPify Longer Branches)
4136 @cindex @code{-J}, ignored on VAX
4137 Many 32-bit computers permit a variety of branch instructions
4138 to do the same job. Some of these instructions are short (and
4139 fast) but have a limited range; others are long (and slow) but
4140 can branch anywhere in virtual memory. Often there are 3
4141 flavors of branch: short, medium and long. Some other
4142 assemblers would emit short and medium branches, unless told by
4143 this option to emit short and long branches.
4145 @item @code{-t} (Temporary File Directory)
4146 @cindex @code{-t}, ignored on VAX
4147 Some other assemblers may use a temporary file, and this option
4148 takes a filename being the directory to site the temporary
4149 file. Since @code{@value{AS}} does not use a temporary disk file, this
4150 option makes no difference. @samp{-t} needs exactly one
4154 @cindex VMS (VAX) options
4155 @cindex options for VAX/VMS
4156 @cindex VAX/VMS options
4157 @cindex @code{-h} option, VAX/VMS
4158 @cindex @code{-+} option, VAX/VMS
4159 @cindex Vax-11 C compatibility
4160 @cindex symbols with lowercase, VAX/VMS
4161 @c FIXME! look into "I think" below, correct if needed, delete.
4162 The Vax version of the assembler accepts two options when
4163 compiled for VMS. They are @samp{-h}, and @samp{-+}. The
4164 @samp{-h} option prevents @code{@value{AS}} from modifying the
4165 symbol-table entries for symbols that contain lowercase
4166 characters (I think). The @samp{-+} option causes @code{@value{AS}} to
4167 print warning messages if the FILENAME part of the object file,
4168 or any symbol name is larger than 31 characters. The @samp{-+}
4169 option also inserts some code following the @samp{_main}
4170 symbol so that the object file is compatible with Vax-11
4174 @section VAX Floating Point
4176 @cindex VAX floating point
4177 @cindex floating point, VAX
4178 Conversion of flonums to floating point is correct, and
4179 compatible with previous assemblers. Rounding is
4180 towards zero if the remainder is exactly half the least significant bit.
4182 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
4185 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
4186 are rendered correctly. Again, rounding is towards zero in the
4189 @cindex @code{float} directive, VAX
4190 @cindex @code{double} directive, VAX
4191 The @code{.float} directive produces @code{f} format numbers.
4192 The @code{.double} directive produces @code{d} format numbers.
4194 @node VAX-directives
4195 @section Vax Machine Directives
4197 @cindex machine directives, VAX
4198 @cindex VAX machine directives
4199 The Vax version of the assembler supports four directives for
4200 generating Vax floating point constants. They are described in the
4203 @cindex wide floating point directives, VAX
4206 @cindex @code{dfloat} directive, VAX
4207 This expects zero or more flonums, separated by commas, and
4208 assembles Vax @code{d} format 64-bit floating point constants.
4211 @cindex @code{ffloat} directive, VAX
4212 This expects zero or more flonums, separated by commas, and
4213 assembles Vax @code{f} format 32-bit floating point constants.
4216 @cindex @code{gfloat} directive, VAX
4217 This expects zero or more flonums, separated by commas, and
4218 assembles Vax @code{g} format 64-bit floating point constants.
4221 @cindex @code{hfloat} directive, VAX
4222 This expects zero or more flonums, separated by commas, and
4223 assembles Vax @code{h} format 128-bit floating point constants.
4228 @section VAX Opcodes
4230 @cindex VAX opcode mnemonics
4231 @cindex opcode mnemonics, VAX
4232 @cindex mnemonics for opcodes, VAX
4233 All DEC mnemonics are supported. Beware that @code{case@dots{}}
4234 instructions have exactly 3 operands. The dispatch table that
4235 follows the @code{case@dots{}} instruction should be made with
4236 @code{.word} statements. This is compatible with all unix
4237 assemblers we know of.
4240 @section VAX Branch Improvement
4242 @cindex VAX branch improvement
4243 @cindex branch improvement, VAX
4244 @cindex pseudo-ops for branch, VAX
4245 Certain pseudo opcodes are permitted. They are for branch
4246 instructions. They expand to the shortest branch instruction that
4247 reaches the target. Generally these mnemonics are made by
4248 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
4249 This feature is included both for compatibility and to help
4250 compilers. If you do not need this feature, avoid these
4251 opcodes. Here are the mnemonics, and the code they can expand into.
4255 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
4257 @item (byte displacement)
4259 @item (word displacement)
4261 @item (long displacement)
4266 Unconditional branch.
4268 @item (byte displacement)
4270 @item (word displacement)
4272 @item (long displacement)
4276 @var{COND} may be any one of the conditional branches
4277 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
4278 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
4279 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
4280 @var{COND} may also be one of the bit tests
4281 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
4282 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
4283 @var{NOTCOND} is the opposite condition to @var{COND}.
4285 @item (byte displacement)
4286 @kbd{b@var{COND} @dots{}}
4287 @item (word displacement)
4288 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
4289 @item (long displacement)
4290 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
4293 @var{X} may be one of @code{b d f g h l w}.
4295 @item (word displacement)
4296 @kbd{@var{OPCODE} @dots{}}
4297 @item (long displacement)
4299 @var{OPCODE} @dots{}, foo ;
4306 @var{YYY} may be one of @code{lss leq}.
4308 @var{ZZZ} may be one of @code{geq gtr}.
4310 @item (byte displacement)
4311 @kbd{@var{OPCODE} @dots{}}
4312 @item (word displacement)
4314 @var{OPCODE} @dots{}, foo ;
4316 foo: brw @var{destination} ;
4319 @item (long displacement)
4321 @var{OPCODE} @dots{}, foo ;
4323 foo: jmp @var{destination} ;
4332 @item (byte displacement)
4333 @kbd{@var{OPCODE} @dots{}}
4334 @item (word displacement)
4336 @var{OPCODE} @dots{}, foo ;
4338 foo: brw @var{destination} ;
4341 @item (long displacement)
4343 @var{OPCODE} @dots{}, foo ;
4345 foo: jmp @var{destination} ;
4352 @section VAX Operands
4354 @cindex VAX operand notation
4355 @cindex operand notation, VAX
4356 @cindex immediate character, VAX
4357 @cindex VAX immediate character
4358 The immediate character is @samp{$} for Unix compatibility, not
4359 @samp{#} as DEC writes it.
4361 @cindex indirect character, VAX
4362 @cindex VAX indirect character
4363 The indirect character is @samp{*} for Unix compatibility, not
4364 @samp{@@} as DEC writes it.
4366 @cindex displacement sizing character, VAX
4367 @cindex VAX displacement sizing character
4368 The displacement sizing character is @samp{`} (an accent grave) for
4369 Unix compatibility, not @samp{^} as DEC writes it. The letter
4370 preceding @samp{`} may have either case. @samp{G} is not
4371 understood, but all other letters (@code{b i l s w}) are understood.
4373 @cindex register names, VAX
4374 @cindex VAX register names
4375 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
4376 pc}. Upper and lower case letters are equivalent.
4383 Any expression is permitted in an operand. Operands are comma
4386 @c There is some bug to do with recognizing expressions
4387 @c in operands, but I forget what it is. It is
4388 @c a syntax clash because () is used as an address mode
4389 @c and to encapsulate sub-expressions.
4392 @section Not Supported on VAX
4394 @cindex VAX bitfields not supported
4395 @cindex bitfields, not supported on VAX
4396 Vax bit fields can not be assembled with @code{@value{AS}}. Someone
4397 can add the required code if they really need it.
4404 @node AMD29K-Dependent
4405 @chapter AMD 29K Dependent Features
4408 @node Machine Dependencies
4409 @chapter AMD 29K Dependent Features
4412 @cindex AMD 29K support
4415 * AMD29K Options:: Options
4416 * AMD29K Syntax:: Syntax
4417 * AMD29K Floating Point:: Floating Point
4418 * AMD29K Directives:: AMD 29K Machine Directives
4419 * AMD29K Opcodes:: Opcodes
4422 @node AMD29K Options
4424 @cindex AMD 29K options (none)
4425 @cindex options for AMD29K (none)
4426 @code{@value{AS}} has no additional command-line options for the AMD
4432 * AMD29K-Chars:: Special Characters
4433 * AMD29K-Regs:: Register Names
4437 @subsection Special Characters
4439 @cindex line comment character, AMD 29K
4440 @cindex AMD 29K line comment character
4441 @samp{;} is the line comment character.
4443 @cindex line separator, AMD 29K
4444 @cindex AMD 29K line separator
4445 @cindex statement separator, AMD 29K
4446 @cindex AMD 29K statement separator
4447 @samp{@@} can be used instead of a newline to separate statements.
4449 @cindex identifiers, AMD 29K
4450 @cindex AMD 29K identifiers
4451 The character @samp{?} is permitted in identifiers (but may not begin
4455 @subsection Register Names
4457 @cindex AMD 29K register names
4458 @cindex register names, AMD 29K
4459 General-purpose registers are represented by predefined symbols of the
4460 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
4461 (for local registers), where @var{nnn} represents a number between
4462 @code{0} and @code{127}, written with no leading zeros. The leading
4463 letters may be in either upper or lower case; for example, @samp{gr13}
4464 and @samp{LR7} are both valid register names.
4466 You may also refer to general-purpose registers by specifying the
4467 register number as the result of an expression (prefixed with @samp{%%}
4468 to flag the expression as a register number):
4473 ---where @var{expression} must be an absolute expression evaluating to a
4474 number between @code{0} and @code{255}. The range [0, 127] refers to
4475 global registers, and the range [128, 255] to local registers.
4477 @cindex special purpose registers, AMD 29K
4478 @cindex AMD 29K special purpose registers
4479 @cindex protected registers, AMD 29K
4480 @cindex AMD 29K protected registers
4481 In addition, @code{@value{AS}} understands the following protected
4482 special-purpose register names for the AMD 29K family:
4492 These unprotected special-purpose register names are also recognized:
4500 @node AMD29K Floating Point
4501 @section Floating Point
4503 @cindex floating point, AMD 29K (@sc{ieee})
4504 @cindex AMD 29K floating point (@sc{ieee})
4505 The AMD 29K family uses @sc{ieee} floating-point numbers.
4507 @node AMD29K Directives
4508 @section AMD 29K Machine Directives
4510 @cindex machine directives, AMD 29K
4511 @cindex AMD 29K machine directives
4513 @item .block @var{size} , @var{fill}
4514 @cindex @code{block} directive, AMD 29K
4515 This directive emits @var{size} bytes, each of value @var{fill}. Both
4516 @var{size} and @var{fill} are absolute expressions. If the comma
4517 and @var{fill} are omitted, @var{fill} is assumed to be zero.
4519 In other versions of the @sc{gnu} assembler, this directive is called
4525 @cindex @code{cputype} directive, AMD 29K
4526 This directive is ignored; it is accepted for compatibility with other
4530 @cindex @code{file} directive, AMD 29K
4531 This directive is ignored; it is accepted for compatibility with other
4535 @emph{Warning:} in other versions of the @sc{gnu} assembler, @code{.file} is
4536 used for the directive called @code{.app-file} in the AMD 29K support.
4540 @cindex @code{line} directive, AMD 29K
4541 This directive is ignored; it is accepted for compatibility with other
4545 @c since we're ignoring .lsym...
4546 @item .reg @var{symbol}, @var{expression}
4547 @cindex @code{reg} directive, AMD 29K
4548 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
4552 @cindex @code{sect} directive, AMD 29K
4553 This directive is ignored; it is accepted for compatibility with other
4556 @item .use @var{section name}
4557 @cindex @code{use} directive, AMD 29K
4558 Establishes the section and subsection for the following code;
4559 @var{section name} may be one of @code{.text}, @code{.data},
4560 @code{.data1}, or @code{.lit}. With one of the first three @var{section
4561 name} options, @samp{.use} is equivalent to the machine directive
4562 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
4566 @node AMD29K Opcodes
4569 @cindex AMD 29K opcodes
4570 @cindex opcodes for AMD 29K
4571 @code{@value{AS}} implements all the standard AMD 29K opcodes. No
4572 additional pseudo-instructions are needed on this family.
4574 For information on the 29K machine instruction set, see @cite{Am29000
4575 User's Manual}, Advanced Micro Devices, Inc.
4580 @node Machine Dependencies
4581 @chapter Machine Dependent Features
4583 The machine instruction sets are different on each Hitachi chip family,
4584 and there are also some syntax differences among the families. This
4585 chapter describes the specific @code{@value{AS}} features for each
4589 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
4590 * H8/500-Dependent:: Hitachi H8/500 Dependent Features
4591 * SH-Dependent:: Hitachi SH Dependent Features
4601 @node H8/300-Dependent
4602 @chapter H8/300 Dependent Features
4604 @cindex H8/300 support
4606 * H8/300 Options:: Options
4607 * H8/300 Syntax:: Syntax
4608 * H8/300 Floating Point:: Floating Point
4609 * H8/300 Directives:: H8/300 Machine Directives
4610 * H8/300 Opcodes:: Opcodes
4613 @node H8/300 Options
4616 @cindex H8/300 options (none)
4617 @cindex options, H8/300 (none)
4618 @code{@value{AS}} has no additional command-line options for the Hitachi
4624 * H8/300-Chars:: Special Characters
4625 * H8/300-Regs:: Register Names
4626 * H8/300-Addressing:: Addressing Modes
4630 @subsection Special Characters
4632 @cindex line comment character, H8/300
4633 @cindex H8/300 line comment character
4634 @samp{;} is the line comment character.
4636 @cindex line separator, H8/300
4637 @cindex statement separator, H8/300
4638 @cindex H8/300 line separator
4639 @samp{$} can be used instead of a newline to separate statements.
4640 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4643 @subsection Register Names
4645 @cindex H8/300 registers
4646 @cindex register names, H8/300
4647 You can use predefined symbols of the form @samp{r@var{n}h} and
4648 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4649 general-purpose registers. @var{n} is a digit from @samp{0} to
4650 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4653 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4654 to the H8/300 registers as 16-bit registers (you must use this form for
4657 On the H8/300H, you can also use the eight predefined symbols
4658 @samp{er@var{n}} (@samp{er0} @dots{} @samp{er7}) to refer to the 32-bit
4659 general purpose registers.
4661 The two control registers are called @code{pc} (program counter; a
4662 16-bit register, except on the H8/300H where it is 24 bits) and
4663 @code{ccr} (condition code register; an 8-bit register). @code{r7} is
4664 used as the stack pointer, and can also be called @code{sp}.
4666 @node H8/300-Addressing
4667 @subsection Addressing Modes
4669 @cindex addressing modes, H8/300
4670 @cindex H8/300 addressing modes
4671 @value{AS} understands the following addressing modes for the H8/300:
4679 @item @@(@var{d}, r@var{n})
4680 @itemx @@(@var{d}:16, r@var{n})
4681 @itemx @@(@var{d}:24, r@var{n})
4682 Register indirect: 16-bit or 24-bit displacement @var{d} from register
4683 @var{n}. (24-bit displacements are only meaningful on the H8/300H.)
4686 Register indirect with post-increment
4689 Register indirect with pre-decrement
4691 @item @code{@@}@var{aa}
4692 @itemx @code{@@}@var{aa}:8
4693 @itemx @code{@@}@var{aa}:16
4694 @itemx @code{@@}@var{aa}:24
4695 Absolute address @code{aa}. (The address size @samp{:24} only makes
4696 sense on the H8/300H.)
4702 Immediate data @var{xx}. You may specify the @samp{:8}, @samp{:16}, or
4703 @samp{:32} for clarity, if you wish; but @code{@value{AS}} neither
4704 requires this nor uses it---the data size required is taken from
4707 @item @code{@@}@code{@@}@var{aa}
4708 @itemx @code{@@}@code{@@}@var{aa}:8
4709 Memory indirect. You may specify the @samp{:8} for clarity, if you
4710 wish; but @code{@value{AS}} neither requires this nor uses it.
4713 @node H8/300 Floating Point
4714 @section Floating Point
4716 @cindex floating point, H8/300 (@sc{ieee})
4717 @cindex H8/300 floating point (@sc{ieee})
4718 The H8/300 family has no hardware floating point, but the @code{.float}
4719 directive generates @sc{ieee} floating-point numbers for compatibility
4720 with other development tools.
4723 @node H8/300 Directives
4724 @section H8/300 Machine Directives
4726 @cindex H8/300 machine directives (none)
4727 @cindex machine directives, H8/300 (none)
4728 @cindex @code{word} directive, H8/300
4729 @cindex @code{int} directive, H8/300
4730 @code{@value{AS}} has only one machine-dependent directive for the
4734 @cindex H8/300H, assembling for
4736 Recognize and emit additional instructions for the H8/300H variant, and
4737 also make @code{.int} emit 32-bit numbers rather than the usual (16-bit)
4738 for the H8/300 family.
4741 On the H8/300 family (including the H8/300H) @samp{.word} directives
4742 generate 16-bit numbers.
4744 @node H8/300 Opcodes
4747 @cindex H8/300 opcode summary
4748 @cindex opcode summary, H8/300
4749 @cindex mnemonics, H8/300
4750 @cindex instruction summary, H8/300
4751 For detailed information on the H8/300 machine instruction set, see
4752 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025). For
4753 information specific to the H8/300H, see @cite{H8/300H Series
4754 Programming Manual} (Hitachi).
4756 @code{@value{AS}} implements all the standard H8/300 opcodes. No additional
4757 pseudo-instructions are needed on this family.
4760 @c this table, due to the multi-col faking and hardcoded order, looks silly
4761 @c except in smallbook. See comments below "@set SMALL" near top of this file.
4763 The following table summarizes the H8/300 opcodes, and their arguments.
4764 Entries marked @samp{*} are opcodes used only on the H8/300H.
4767 @c Using @group seems to use the normal baselineskip, not the smallexample
4768 @c baselineskip; looks approx doublespaced.
4770 Rs @r{source register}
4771 Rd @r{destination register}
4772 abs @r{absolute address}
4773 imm @r{immediate data}
4774 disp:N @r{N-bit displacement from a register}
4775 pcrel:N @r{N-bit displacement relative to program counter}
4777 add.b #imm,rd * andc #imm,ccr
4778 add.b rs,rd band #imm,rd
4779 add.w rs,rd band #imm,@@rd
4780 * add.w #imm,rd band #imm,@@abs:8
4781 * add.l rs,rd bra pcrel:8
4782 * add.l #imm,rd * bra pcrel:16
4783 adds #imm,rd bt pcrel:8
4784 addx #imm,rd * bt pcrel:16
4785 addx rs,rd brn pcrel:8
4786 and.b #imm,rd * brn pcrel:16
4787 and.b rs,rd bf pcrel:8
4788 * and.w rs,rd * bf pcrel:16
4789 * and.w #imm,rd bhi pcrel:8
4790 * and.l #imm,rd * bhi pcrel:16
4791 * and.l rs,rd bls pcrel:8
4793 * bls pcrel:16 bld #imm,rd
4794 bcc pcrel:8 bld #imm,@@rd
4795 * bcc pcrel:16 bld #imm,@@abs:8
4796 bhs pcrel:8 bnot #imm,rd
4797 * bhs pcrel:16 bnot #imm,@@rd
4798 bcs pcrel:8 bnot #imm,@@abs:8
4799 * bcs pcrel:16 bnot rs,rd
4800 blo pcrel:8 bnot rs,@@rd
4801 * blo pcrel:16 bnot rs,@@abs:8
4802 bne pcrel:8 bor #imm,rd
4803 * bne pcrel:16 bor #imm,@@rd
4804 beq pcrel:8 bor #imm,@@abs:8
4805 * beq pcrel:16 bset #imm,rd
4806 bvc pcrel:8 bset #imm,@@rd
4807 * bvc pcrel:16 bset #imm,@@abs:8
4808 bvs pcrel:8 bset rs,rd
4809 * bvs pcrel:16 bset rs,@@rd
4810 bpl pcrel:8 bset rs,@@abs:8
4811 * bpl pcrel:16 bsr pcrel:8
4812 bmi pcrel:8 bsr pcrel:16
4813 * bmi pcrel:16 bst #imm,rd
4814 bge pcrel:8 bst #imm,@@rd
4815 * bge pcrel:16 bst #imm,@@abs:8
4816 blt pcrel:8 btst #imm,rd
4817 * blt pcrel:16 btst #imm,@@rd
4818 bgt pcrel:8 btst #imm,@@abs:8
4819 * bgt pcrel:16 btst rs,rd
4820 ble pcrel:8 btst rs,@@rd
4821 * ble pcrel:16 btst rs,@@abs:8
4822 bclr #imm,rd bxor #imm,rd
4823 bclr #imm,@@rd bxor #imm,@@rd
4824 bclr #imm,@@abs:8 bxor #imm,@@abs:8
4825 bclr rs,rd cmp.b #imm,rd
4826 bclr rs,@@rd cmp.b rs,rd
4827 bclr rs,@@abs:8 cmp.w rs,rd
4828 biand #imm,rd cmp.w rs,rd
4829 biand #imm,@@rd * cmp.w #imm,rd
4830 biand #imm,@@abs:8 * cmp.l #imm,rd
4831 bild #imm,rd * cmp.l rs,rd
4832 bild #imm,@@rd daa rs
4833 bild #imm,@@abs:8 das rs
4834 bior #imm,rd dec.b rs
4835 bior #imm,@@rd * dec.w #imm,rd
4836 bior #imm,@@abs:8 * dec.l #imm,rd
4837 bist #imm,rd divxu.b rs,rd
4838 bist #imm,@@rd * divxu.w rs,rd
4839 bist #imm,@@abs:8 * divxs.b rs,rd
4840 bixor #imm,rd * divxs.w rs,rd
4841 bixor #imm,@@rd eepmov
4842 bixor #imm,@@abs:8 * eepmovw
4844 * exts.w rd mov.w rs,@@abs:16
4845 * exts.l rd * mov.l #imm,rd
4846 * extu.w rd * mov.l rs,rd
4847 * extu.l rd * mov.l @@rs,rd
4848 inc rs * mov.l @@(disp:16,rs),rd
4849 * inc.w #imm,rd * mov.l @@(disp:24,rs),rd
4850 * inc.l #imm,rd * mov.l @@rs+,rd
4851 jmp @@rs * mov.l @@abs:16,rd
4852 jmp abs * mov.l @@abs:24,rd
4853 jmp @@@@abs:8 * mov.l rs,@@rd
4854 jsr @@rs * mov.l rs,@@(disp:16,rd)
4855 jsr abs * mov.l rs,@@(disp:24,rd)
4856 jsr @@@@abs:8 * mov.l rs,@@-rd
4857 ldc #imm,ccr * mov.l rs,@@abs:16
4858 ldc rs,ccr * mov.l rs,@@abs:24
4859 * ldc @@abs:16,ccr movfpe @@abs:16,rd
4860 * ldc @@abs:24,ccr movtpe rs,@@abs:16
4861 * ldc @@(disp:16,rs),ccr mulxu.b rs,rd
4862 * ldc @@(disp:24,rs),ccr * mulxu.w rs,rd
4863 * ldc @@rs+,ccr * mulxs.b rs,rd
4864 * ldc @@rs,ccr * mulxs.w rs,rd
4865 * mov.b @@(disp:24,rs),rd neg.b rs
4866 * mov.b rs,@@(disp:24,rd) * neg.w rs
4867 mov.b @@abs:16,rd * neg.l rs
4869 mov.b @@abs:8,rd not.b rs
4870 mov.b rs,@@abs:8 * not.w rs
4871 mov.b rs,rd * not.l rs
4872 mov.b #imm,rd or.b #imm,rd
4873 mov.b @@rs,rd or.b rs,rd
4874 mov.b @@(disp:16,rs),rd * or.w #imm,rd
4875 mov.b @@rs+,rd * or.w rs,rd
4876 mov.b @@abs:8,rd * or.l #imm,rd
4877 mov.b rs,@@rd * or.l rs,rd
4878 mov.b rs,@@(disp:16,rd) orc #imm,ccr
4879 mov.b rs,@@-rd pop.w rs
4880 mov.b rs,@@abs:8 * pop.l rs
4881 mov.w rs,@@rd push.w rs
4882 * mov.w @@(disp:24,rs),rd * push.l rs
4883 * mov.w rs,@@(disp:24,rd) rotl.b rs
4884 * mov.w @@abs:24,rd * rotl.w rs
4885 * mov.w rs,@@abs:24 * rotl.l rs
4886 mov.w rs,rd rotr.b rs
4887 mov.w #imm,rd * rotr.w rs
4888 mov.w @@rs,rd * rotr.l rs
4889 mov.w @@(disp:16,rs),rd rotxl.b rs
4890 mov.w @@rs+,rd * rotxl.w rs
4891 mov.w @@abs:16,rd * rotxl.l rs
4892 mov.w rs,@@(disp:16,rd) rotxr.b rs
4893 mov.w rs,@@-rd * rotxr.w rs
4895 * rotxr.l rs * stc ccr,@@(disp:24,rd)
4897 rte * stc ccr,@@abs:16
4898 rts * stc ccr,@@abs:24
4899 shal.b rs sub.b rs,rd
4900 * shal.w rs sub.w rs,rd
4901 * shal.l rs * sub.w #imm,rd
4902 shar.b rs * sub.l rs,rd
4903 * shar.w rs * sub.l #imm,rd
4904 * shar.l rs subs #imm,rd
4905 shll.b rs subx #imm,rd
4906 * shll.w rs subx rs,rd
4907 * shll.l rs * trapa #imm
4908 shlr.b rs xor #imm,rd
4909 * shlr.w rs xor rs,rd
4910 * shlr.l rs * xor.w #imm,rd
4912 stc ccr,rd * xor.l #imm,rd
4913 * stc ccr,@@rs * xor.l rs,rd
4914 * stc ccr,@@(disp:16,rd) xorc #imm,ccr
4918 @cindex size suffixes, H8/300
4919 @cindex H8/300 size suffixes
4920 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4921 @code{sub}) are defined with variants using the suffixes @samp{.b},
4922 @samp{.w}, and @samp{.l} to specify the size of a memory operand.
4923 @code{@value{AS}} supports these suffixes, but does not require them;
4924 since one of the operands is always a register, @code{@value{AS}} can
4925 deduce the correct size.
4927 For example, since @code{r0} refers to a 16-bit register,
4930 @exdent is equivalent to
4934 If you use the size suffixes, @code{@value{AS}} issues a warning when
4935 the suffix and the register size do not match.
4940 @node H8/500-Dependent
4941 @chapter H8/500 Dependent Features
4943 @cindex H8/500 support
4945 * H8/500 Options:: Options
4946 * H8/500 Syntax:: Syntax
4947 * H8/500 Floating Point:: Floating Point
4948 * H8/500 Directives:: H8/500 Machine Directives
4949 * H8/500 Opcodes:: Opcodes
4952 @node H8/500 Options
4955 @cindex H8/500 options (none)
4956 @cindex options, H8/500 (none)
4957 @code{@value{AS}} has no additional command-line options for the Hitachi
4964 * H8/500-Chars:: Special Characters
4965 * H8/500-Regs:: Register Names
4966 * H8/500-Addressing:: Addressing Modes
4970 @subsection Special Characters
4972 @cindex line comment character, H8/500
4973 @cindex H8/500 line comment character
4974 @samp{!} is the line comment character.
4976 @cindex line separator, H8/500
4977 @cindex statement separator, H8/500
4978 @cindex H8/500 line separator
4979 @samp{;} can be used instead of a newline to separate statements.
4981 @cindex symbol names, @samp{$} in
4982 @cindex @code{$} in symbol names
4983 Since @samp{$} has no special meaning, you may use it in symbol names.
4986 @subsection Register Names
4988 @cindex H8/500 registers
4989 @cindex registers, H8/500
4990 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
4991 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, and @samp{r7} to refer to
4992 the H8/500 registers.
4994 The H8/500 also has these control registers:
5016 condition code register
5019 All registers are 16 bits long. To represent 32 bit numbers, use two
5020 adjacent registers; for distant memory addresses, use one of the segment
5021 pointers (@code{cp} for the program counter; @code{dp} for
5022 @code{r0}--@code{r3}; @code{ep} for @code{r4} and @code{r5}; and
5023 @code{tp} for @code{r6} and @code{r7}.
5025 @node H8/500-Addressing
5026 @subsection Addressing Modes
5028 @cindex addressing modes, H8/500
5029 @cindex H8/500 addressing modes
5030 @value{AS} understands the following addressing modes for the H8/500:
5038 @item @@(d:8, R@var{n})
5039 Register indirect with 8 bit signed displacement
5041 @item @@(d:16, R@var{n})
5042 Register indirect with 16 bit signed displacement
5045 Register indirect with pre-decrement
5048 Register indirect with post-increment
5051 8 bit absolute address
5054 16 bit absolute address
5063 @node H8/500 Floating Point
5064 @section Floating Point
5066 @cindex floating point, H8/500 (@sc{ieee})
5067 @cindex H8/500 floating point (@sc{ieee})
5068 The H8/500 family has no hardware floating point, but the @code{.float}
5069 directive generates @sc{ieee} floating-point numbers for compatibility
5070 with other development tools.
5072 @node H8/500 Directives
5073 @section H8/500 Machine Directives
5075 @cindex H8/500 machine directives (none)
5076 @cindex machine directives, H8/500 (none)
5077 @cindex @code{word} directive, H8/500
5078 @cindex @code{int} directive, H8/500
5079 @code{@value{AS}} has no machine-dependent directives for the H8/500.
5080 However, on this platform the @samp{.int} and @samp{.word} directives
5081 generate 16-bit numbers.
5083 @node H8/500 Opcodes
5086 @cindex H8/500 opcode summary
5087 @cindex opcode summary, H8/500
5088 @cindex mnemonics, H8/500
5089 @cindex instruction summary, H8/500
5090 For detailed information on the H8/500 machine instruction set, see
5091 @cite{H8/500 Series Programming Manual} (Hitachi M21T001).
5093 @code{@value{AS}} implements all the standard H8/500 opcodes. No additional
5094 pseudo-instructions are needed on this family.
5097 @c this table, due to the multi-col faking and hardcoded order, looks silly
5098 @c except in smallbook. See comments below "@set SMALL" near top of this file.
5100 The following table summarizes H8/500 opcodes and their operands:
5102 @c Use @group if it ever works, instead of @page
5106 abs8 @r{8-bit absolute address}
5107 abs16 @r{16-bit absolute address}
5108 abs24 @r{24-bit absolute address}
5109 crb @r{@code{ccr}, @code{br}, @code{ep}, @code{dp}, @code{tp}, @code{dp}}
5110 disp8 @r{8-bit displacement}
5111 ea @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
5112 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16},}
5113 @r{@code{#xx:8}, @code{#xx:16}}
5114 ea_mem @r{@code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
5115 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
5116 ea_noimm @r{@code{rn}, @code{@@rn}, @code{@@(d:8, rn)}, @code{@@(d:16, rn)},}
5117 @r{@code{@@-rn}, @code{@@rn+}, @code{@@aa:8}, @code{@@aa:16}}
5119 imm4 @r{4-bit immediate data}
5120 imm8 @r{8-bit immediate data}
5121 imm16 @r{16-bit immediate data}
5122 pcrel8 @r{8-bit offset from program counter}
5123 pcrel16 @r{16-bit offset from program counter}
5124 qim @r{@code{-2}, @code{-1}, @code{1}, @code{2}}
5126 rs @r{a register distinct from rd}
5127 rlist @r{comma-separated list of registers in parentheses;}
5128 @r{register ranges @code{rd-rs} are allowed}
5129 sp @r{stack pointer (@code{r7})}
5130 sr @r{status register}
5131 sz @r{size; @samp{.b} or @samp{.w}. If omitted, default @samp{.w}}
5133 ldc[.b] ea,crb bcc[.w] pcrel16
5134 ldc[.w] ea,sr bcc[.b] pcrel8
5135 add[:q] sz qim,ea_noimm bhs[.w] pcrel16
5136 add[:g] sz ea,rd bhs[.b] pcrel8
5137 adds sz ea,rd bcs[.w] pcrel16
5138 addx sz ea,rd bcs[.b] pcrel8
5139 and sz ea,rd blo[.w] pcrel16
5140 andc[.b] imm8,crb blo[.b] pcrel8
5141 andc[.w] imm16,sr bne[.w] pcrel16
5143 bra[.w] pcrel16 beq[.w] pcrel16
5144 bra[.b] pcrel8 beq[.b] pcrel8
5145 bt[.w] pcrel16 bvc[.w] pcrel16
5146 bt[.b] pcrel8 bvc[.b] pcrel8
5147 brn[.w] pcrel16 bvs[.w] pcrel16
5148 brn[.b] pcrel8 bvs[.b] pcrel8
5149 bf[.w] pcrel16 bpl[.w] pcrel16
5150 bf[.b] pcrel8 bpl[.b] pcrel8
5151 bhi[.w] pcrel16 bmi[.w] pcrel16
5152 bhi[.b] pcrel8 bmi[.b] pcrel8
5153 bls[.w] pcrel16 bge[.w] pcrel16
5154 bls[.b] pcrel8 bge[.b] pcrel8
5156 blt[.w] pcrel16 mov[:g][.b] imm8,ea_mem
5157 blt[.b] pcrel8 mov[:g][.w] imm16,ea_mem
5158 bgt[.w] pcrel16 movfpe[.b] ea,rd
5159 bgt[.b] pcrel8 movtpe[.b] rs,ea_noimm
5160 ble[.w] pcrel16 mulxu sz ea,rd
5161 ble[.b] pcrel8 neg sz ea
5162 bclr sz imm4,ea_noimm nop
5163 bclr sz rs,ea_noimm not sz ea
5164 bnot sz imm4,ea_noimm or sz ea,rd
5165 bnot sz rs,ea_noimm orc[.b] imm8,crb
5166 bset sz imm4,ea_noimm orc[.w] imm16,sr
5167 bset sz rs,ea_noimm pjmp abs24
5168 bsr[.b] pcrel8 pjmp @@rd
5169 bsr[.w] pcrel16 pjsr abs24
5170 btst sz imm4,ea_noimm pjsr @@rd
5171 btst sz rs,ea_noimm prtd imm8
5172 clr sz ea prtd imm16
5173 cmp[:e][.b] imm8,rd prts
5174 cmp[:i][.w] imm16,rd rotl sz ea
5175 cmp[:g].b imm8,ea_noimm rotr sz ea
5176 cmp[:g][.w] imm16,ea_noimm rotxl sz ea
5177 Cmp[:g] sz ea,rd rotxr sz ea
5179 divxu sz ea,rd rtd imm16
5181 exts[.b] rd scb/f rs,pcrel8
5182 extu[.b] rd scb/ne rs,pcrel8
5183 jmp @@rd scb/eq rs,pcrel8
5184 jmp @@(imm8,rd) shal sz ea
5185 jmp @@(imm16,rd) shar sz ea
5186 jmp abs16 shll sz ea
5188 jsr @@(imm8,rd) sleep
5189 jsr @@(imm16,rd) stc[.b] crb,ea_noimm
5190 jsr abs16 stc[.w] sr,ea_noimm
5191 ldm @@sp+,(rlist) stm (rlist),@@-sp
5192 link fp,imm8 sub sz ea,rd
5193 link fp,imm16 subs sz ea,rd
5194 mov[:e][.b] imm8,rd subx sz ea,rd
5195 mov[:i][.w] imm16,rd swap[.b] rd
5196 mov[:l][.w] abs8,rd tas[.b] ea
5197 mov[:l].b abs8,rd trapa imm4
5198 mov[:s][.w] rs,abs8 trap/vs
5199 mov[:s].b rs,abs8 tst sz ea
5200 mov[:f][.w] @@(disp8,fp),rd unlk fp
5201 mov[:f][.w] rs,@@(disp8,fp) xch[.w] rs,rd
5202 mov[:f].b @@(disp8,fp),rd xor sz ea,rd
5203 mov[:f].b rs,@@(disp8,fp) xorc.b imm8,crb
5204 mov[:g] sz rs,ea_mem xorc.w imm16,sr
5212 @node HPPA-Dependent
5213 @chapter HPPA Dependent Features
5217 * HPPA Notes:: Notes
5218 * HPPA Options:: Options
5219 * HPPA Syntax:: Syntax
5220 * HPPA Floating Point:: Floating Point
5221 * HPPA Directives:: HPPA Machine Directives
5222 * HPPA Opcodes:: Opcodes
5227 As a back end for @sc{gnu} @sc{cc} @code{@value{AS}} has been throughly tested and should
5228 work extremely well. We have tested it only minimally on hand written assembly
5229 code and no one has tested it much on the assembly output from the HP
5232 The format of the debugging sections has changed since the original
5233 @code{@value{AS}} port (version 1.3X) was released; therefore,
5234 you must rebuild all HPPA objects and libraries with the new
5235 assembler so that you can debug the final executable.
5237 The HPPA @code{@value{AS}} port generates a small subset of the relocations
5238 available in the SOM and ELF object file formats. Additional relocation
5239 support will be added as it becomes necessary.
5243 @code{@value{AS}} has no machine-dependent command-line options for the HPPA.
5248 The assembler syntax closely follows the HPPA instruction set
5249 reference manual; assembler directives and general syntax closely follow the
5250 HPPA assembly language reference manual, with a few noteworthy differences.
5252 First, a colon may immediately follow a label definition. This is
5253 simply for compatibility with how most assembly language programmers
5256 Some obscure expression parsing problems may affect hand written code which
5257 uses the @code{spop} instructions, or code which makes significant
5258 use of the @code{!} line separator.
5260 @code{@value{AS}} is much less forgiving about missing arguments and other
5261 similar oversights than the HP assembler. @code{@value{AS}} notifies you
5262 of missing arguments as syntax errors; this is regarded as a feature, not a
5265 Finally, @code{@value{AS}} allows you to use an external symbol without
5266 explicitly importing the symbol. @emph{Warning:} in the future this will be
5267 an error for HPPA targets.
5269 Special characters for HPPA targets include:
5271 @samp{;} is the line comment character.
5273 @samp{!} can be used instead of a newline to separate statements.
5275 Since @samp{$} has no special meaning, you may use it in symbol names.
5277 @node HPPA Floating Point
5278 @section Floating Point
5279 @cindex floating point, HPPA (@sc{ieee})
5280 @cindex HPPA floating point (@sc{ieee})
5281 The HPPA family uses @sc{ieee} floating-point numbers.
5283 @node HPPA Directives
5284 @section HPPA Assembler Directives
5286 @code{@value{AS}} for the HPPA supports many additional directives for
5287 compatibility with the native assembler. This section describes them only
5288 briefly. For detailed information on HPPA-specific assembler directives, see
5289 @cite{HP9000 Series 800 Assembly Language Reference Manual} (HP 92432-90001).
5291 @cindex HPPA directives not supported
5292 @code{@value{AS}} does @emph{not} support the following assembler directives
5293 described in the HP manual:
5302 @cindex @code{.param} on HPPA
5303 Beyond those implemented for compatibility, @code{@value{AS}} supports one
5304 additional assembler directive for the HPPA: @code{.param}. It conveys
5305 register argument locations for static functions. Its syntax closely follows
5306 the @code{.export} directive.
5308 @cindex HPPA-only directives
5309 These are the additional directives in @code{@value{AS}} for the HPPA:
5312 @item .block @var{n}
5313 @itemx .blockz @var{n}
5314 Reserve @var{n} bytes of storage, and initialize them to zero.
5317 Mark the beginning of a procedure call. Only the special case with @emph{no
5318 arguments} is allowed.
5320 @item .callinfo [ @var{param}=@var{value}, @dots{} ] [ @var{flag}, @dots{} ]
5321 Specify a number of parameters and flags that define the environment for a
5324 @var{param} may be any of @samp{frame} (frame size), @samp{entry_gr} (end of
5325 general register range), @samp{entry_fr} (end of float register range),
5326 @samp{entry_sr} (end of space register range).
5328 The values for @var{flag} are @samp{calls} or @samp{caller} (proc has
5329 subroutines), @samp{no_calls} (proc does not call subroutines), @samp{save_rp}
5330 (preserve return pointer), @samp{save_sp} (proc preserves stack pointer),
5331 @samp{no_unwind} (do not unwind this proc), @samp{hpux_int} (proc is interrupt
5335 Assemble into the standard section called @samp{$TEXT$}, subsection
5339 @item .copyright "@var{string}"
5340 In the SOM object format, insert @var{string} into the object code, marked as a
5345 @item .copyright "@var{string}"
5346 In the ELF object format, insert @var{string} into the object code, marked as a
5351 Not yet supported; the assembler rejects programs containing this directive.
5354 Mark the beginning of a procedure.
5357 Mark the end of a procedure.
5359 @item .export @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5360 Make a procedure @var{name} available to callers. @var{typ}, if present, must
5361 be one of @samp{absolute}, @samp{code} (ELF only, not SOM), @samp{data},
5362 @samp{entry}, @samp{data}, @samp{entry}, @samp{millicode}, @samp{plabel},
5363 @samp{pri_prog}, or @samp{sec_prog}.
5365 @var{param}, if present, provides either relocation information for the
5366 procedure arguments and result, or a privilege level. @var{param} may be
5367 @samp{argw@var{n}} (where @var{n} ranges from @code{0} to @code{3}, and
5368 indicates one of four one-word arguments); @samp{rtnval} (the procedure's
5369 result); or @samp{priv_lev} (privilege level). For arguments or the result,
5370 @var{r} specifies how to relocate, and must be one of @samp{no} (not
5371 relocatable), @samp{gr} (argument is in general register), @samp{fr} (in
5372 floating point register), or @samp{fu} (upper half of float register).
5373 For @samp{priv_lev}, @var{r} is an integer.
5376 Define a two-byte integer constant @var{n}; synonym for the portable
5377 @code{@value{AS}} directive @code{.short}.
5379 @item .import @var{name} [ ,@var{typ} ]
5380 Converse of @code{.export}; make a procedure available to call. The arguments
5381 use the same conventions as the first two arguments for @code{.export}.
5383 @item .label @var{name}
5384 Define @var{name} as a label for the current assembly location.
5387 Not yet supported; the assembler rejects programs containing this directive.
5389 @item .origin @var{lc}
5390 Advance location counter to @var{lc}. Synonym for the @code{@value{as}}
5391 portable directive @code{.org}.
5393 @item .param @var{name} [ ,@var{typ} ] [ ,@var{param}=@var{r} ]
5394 @c Not in HP manual; GNU HPPA extension
5395 Similar to @code{.export}, but used for static procedures.
5398 Use preceding the first statement of a procedure.
5401 Use following the last statement of a procedure.
5403 @item @var{label} .reg @var{expr}
5404 @c ?? Not in HP manual (Jan 1988 vn)
5405 Synonym for @code{.equ}; define @var{label} with the absolute expression
5406 @var{expr} as its value.
5408 @item .space @var{secname} [ ,@var{params} ]
5409 Switch to section @var{secname}, creating a new section by that name if
5410 necessary. You may only use @var{params} when creating a new section, not
5411 when switching to an existing one. @var{secname} may identify a section by
5412 number rather than by name.
5414 If specified, the list @var{params} declares attributes of the section,
5415 identified by keywords. The keywords recognized are @samp{spnum=@var{exp}}
5416 (identify this section by the number @var{exp}, an absolute expression),
5417 @samp{sort=@var{exp}} (order sections according to this sort key when linking;
5418 @var{exp} is an absolute expression), @samp{unloadable} (section contains no
5419 loadable data), @samp{notdefined} (this section defined elsewhere), and
5420 @samp{private} (data in this section not available to other programs).
5422 @item .spnum @var{secnam}
5423 @c ?? Not in HP manual (Jan 1988)
5424 Allocate four bytes of storage, and initialize them with the section number of
5425 the section named @var{secnam}. (You can define the section number with the
5426 HPPA @code{.space} directive.)
5428 @item .string "@var{str}"
5429 @cindex @code{string} directive on HPPA
5430 Copy the characters in the string @var{str} to the object file.
5431 @xref{Strings,,Strings}, for information on escape sequences you can use in
5432 @code{@value{AS}} strings.
5434 @emph{Warning!} The HPPA version of @code{.string} differs from the
5435 usual @code{@value{AS}} definition: it does @emph{not} write a zero byte
5436 after copying @var{str}.
5438 @item .stringz "@var{str}"
5439 Like @code{.string}, but appends a zero byte after copying @var{str} to object
5442 @item .subspa @var{name} [ ,@var{params} ]
5443 Similar to @code{.space}, but selects a subsection @var{name} within the
5444 current section. You may only specify @var{params} when you create a
5445 subsection (in the first instance of @code{.subspa} for this @var{name}).
5447 If specified, the list @var{params} declares attributes of the subsection,
5448 identified by keywords. The keywords recognized are @samp{quad=@var{expr}}
5449 (``quadrant'' for this subsection), @samp{align=@var{expr}} (alignment for
5450 beginning of this subsection; a power of two), @samp{access=@var{expr}} (value
5451 for ``access rights'' field), @samp{sort=@var{expr}} (sorting order for this
5452 subspace in link), @samp{code_only} (subsection contains only code),
5453 @samp{unloadable} (subsection cannot be loaded into memory), @samp{common}
5454 (subsection is common block), @samp{dup_comm} (initialized data may have
5455 duplicate names), or @samp{zero} (subsection is all zeros, do not write in
5458 @item .version "@var{str}"
5459 Write @var{str} as version identifier in object code.
5464 For detailed information on the HPPA machine instruction set, see
5465 @cite{PA-RISC Architecture and Instruction Set Reference Manual}
5472 @chapter Hitachi SH Dependent Features
5476 * SH Options:: Options
5477 * SH Syntax:: Syntax
5478 * SH Floating Point:: Floating Point
5479 * SH Directives:: SH Machine Directives
5480 * SH Opcodes:: Opcodes
5486 @cindex SH options (none)
5487 @cindex options, SH (none)
5488 @code{@value{AS}} has no additional command-line options for the Hitachi
5495 * SH-Chars:: Special Characters
5496 * SH-Regs:: Register Names
5497 * SH-Addressing:: Addressing Modes
5501 @subsection Special Characters
5503 @cindex line comment character, SH
5504 @cindex SH line comment character
5505 @samp{!} is the line comment character.
5507 @cindex line separator, SH
5508 @cindex statement separator, SH
5509 @cindex SH line separator
5510 You can use @samp{;} instead of a newline to separate statements.
5512 @cindex symbol names, @samp{$} in
5513 @cindex @code{$} in symbol names
5514 Since @samp{$} has no special meaning, you may use it in symbol names.
5517 @subsection Register Names
5519 @cindex SH registers
5520 @cindex registers, SH
5521 You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2},
5522 @samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, @samp{r7}, @samp{r8},
5523 @samp{r9}, @samp{r10}, @samp{r11}, @samp{r12}, @samp{r13}, @samp{r14},
5524 and @samp{r15} to refer to the SH registers.
5526 The SH also has these control registers:
5530 procedure register (holds return address)
5537 high and low multiply accumulator registers
5543 global base register
5546 vector base register (for interrupt vectors)
5550 @subsection Addressing Modes
5552 @cindex addressing modes, SH
5553 @cindex SH addressing modes
5554 @code{@value{AS}} understands the following addressing modes for the SH.
5555 @code{R@var{n}} in the following refers to any of the numbered
5556 registers, but @emph{not} the control registers.
5566 Register indirect with pre-decrement
5569 Register indirect with post-increment
5571 @item @@(@var{disp}, R@var{n})
5572 Register indirect with displacement
5574 @item @@(R0, R@var{n})
5577 @item @@(@var{disp}, GBR)
5584 @itemx @@(@var{disp}, PC)
5585 PC relative address (for branch or for addressing memory). The
5586 @code{@value{AS}} implementation allows you to use the simpler form
5587 @var{addr} anywhere a PC relative address is called for; the alternate
5588 form is supported for compatibility with other assemblers.
5594 @node SH Floating Point
5595 @section Floating Point
5597 @cindex floating point, SH (@sc{ieee})
5598 @cindex SH floating point (@sc{ieee})
5599 The SH family has no hardware floating point, but the @code{.float}
5600 directive generates @sc{ieee} floating-point numbers for compatibility
5601 with other development tools.
5604 @section SH Machine Directives
5606 @cindex SH machine directives (none)
5607 @cindex machine directives, SH (none)
5608 @cindex @code{word} directive, SH
5609 @cindex @code{int} directive, SH
5610 @code{@value{AS}} has no machine-dependent directives for the SH.
5615 @cindex SH opcode summary
5616 @cindex opcode summary, SH
5617 @cindex mnemonics, SH
5618 @cindex instruction summary, SH
5619 For detailed information on the SH machine instruction set, see
5620 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
5622 @code{@value{AS}} implements all the standard SH opcodes. No additional
5623 pseudo-instructions are needed on this family. Note, however, that
5624 because @code{@value{AS}} supports a simpler form of PC-relative
5625 addressing, you may simply write (for example)
5632 where other assemblers might require an explicit displacement to
5633 @code{bar} from the program counter:
5636 mov.l @@(@var{disp}, PC)
5640 @c this table, due to the multi-col faking and hardcoded order, looks silly
5641 @c except in smallbook. See comments below "@set SMALL" near top of this file.
5643 Here is a summary of SH opcodes:
5648 Rn @r{a numbered register}
5649 Rm @r{another numbered register}
5650 #imm @r{immediate data}
5651 disp @r{displacement}
5652 disp8 @r{8-bit displacement}
5653 disp12 @r{12-bit displacement}
5655 add #imm,Rn lds.l @@Rn+,PR
5656 add Rm,Rn mac.w @@Rm+,@@Rn+
5657 addc Rm,Rn mov #imm,Rn
5658 addv Rm,Rn mov Rm,Rn
5659 and #imm,R0 mov.b Rm,@@(R0,Rn)
5660 and Rm,Rn mov.b Rm,@@-Rn
5661 and.b #imm,@@(R0,GBR) mov.b Rm,@@Rn
5662 bf disp8 mov.b @@(disp,Rm),R0
5663 bra disp12 mov.b @@(disp,GBR),R0
5664 bsr disp12 mov.b @@(R0,Rm),Rn
5665 bt disp8 mov.b @@Rm+,Rn
5666 clrmac mov.b @@Rm,Rn
5667 clrt mov.b R0,@@(disp,Rm)
5668 cmp/eq #imm,R0 mov.b R0,@@(disp,GBR)
5669 cmp/eq Rm,Rn mov.l Rm,@@(disp,Rn)
5670 cmp/ge Rm,Rn mov.l Rm,@@(R0,Rn)
5671 cmp/gt Rm,Rn mov.l Rm,@@-Rn
5672 cmp/hi Rm,Rn mov.l Rm,@@Rn
5673 cmp/hs Rm,Rn mov.l @@(disp,Rn),Rm
5674 cmp/pl Rn mov.l @@(disp,GBR),R0
5675 cmp/pz Rn mov.l @@(disp,PC),Rn
5676 cmp/str Rm,Rn mov.l @@(R0,Rm),Rn
5677 div0s Rm,Rn mov.l @@Rm+,Rn
5679 div1 Rm,Rn mov.l R0,@@(disp,GBR)
5680 exts.b Rm,Rn mov.w Rm,@@(R0,Rn)
5681 exts.w Rm,Rn mov.w Rm,@@-Rn
5682 extu.b Rm,Rn mov.w Rm,@@Rn
5683 extu.w Rm,Rn mov.w @@(disp,Rm),R0
5684 jmp @@Rn mov.w @@(disp,GBR),R0
5685 jsr @@Rn mov.w @@(disp,PC),Rn
5686 ldc Rn,GBR mov.w @@(R0,Rm),Rn
5687 ldc Rn,SR mov.w @@Rm+,Rn
5688 ldc Rn,VBR mov.w @@Rm,Rn
5689 ldc.l @@Rn+,GBR mov.w R0,@@(disp,Rm)
5690 ldc.l @@Rn+,SR mov.w R0,@@(disp,GBR)
5691 ldc.l @@Rn+,VBR mova @@(disp,PC),R0
5693 lds Rn,MACL muls Rm,Rn
5694 lds Rn,PR mulu Rm,Rn
5695 lds.l @@Rn+,MACH neg Rm,Rn
5696 lds.l @@Rn+,MACL negc Rm,Rn
5699 not Rm,Rn stc.l GBR,@@-Rn
5700 or #imm,R0 stc.l SR,@@-Rn
5701 or Rm,Rn stc.l VBR,@@-Rn
5702 or.b #imm,@@(R0,GBR) sts MACH,Rn
5703 rotcl Rn sts MACL,Rn
5705 rotl Rn sts.l MACH,@@-Rn
5706 rotr Rn sts.l MACL,@@-Rn
5711 shar Rn swap.b Rm,Rn
5712 shll Rn swap.w Rm,Rn
5713 shll16 Rn tas.b @@Rn
5715 shll8 Rn tst #imm,R0
5717 shlr16 Rn tst.b #imm,@@(R0,GBR)
5718 shlr2 Rn xor #imm,R0
5720 sleep xor.b #imm,@@(R0,GBR)
5721 stc GBR,Rn xtrct Rm,Rn
5736 @node i960-Dependent
5737 @chapter Intel 80960 Dependent Features
5740 @node Machine Dependencies
5741 @chapter Intel 80960 Dependent Features
5744 @cindex i960 support
5746 * Options-i960:: i960 Command-line Options
5747 * Floating Point-i960:: Floating Point
5748 * Directives-i960:: i960 Machine Directives
5749 * Opcodes for i960:: i960 Opcodes
5752 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
5753 @c long as they're not turned on for other machines than 960.
5757 @section i960 Command-line Options
5759 @cindex i960 options
5760 @cindex options, i960
5763 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
5764 @cindex i960 architecture options
5765 @cindex architecture options, i960
5766 @cindex @code{-A} options, i960
5767 Select the 80960 architecture. Instructions or features not supported
5768 by the selected architecture cause fatal errors.
5770 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
5771 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
5773 If you do not specify any of these options, @code{@value{AS}} generates code
5774 for any instruction or feature that is supported by @emph{some} version of the
5775 960 (even if this means mixing architectures!). In principle,
5776 @code{@value{AS}} attempts to deduce the minimal sufficient processor type if
5777 none is specified; depending on the object code format, the processor type may
5778 be recorded in the object file. If it is critical that the @code{@value{AS}}
5779 output match a specific architecture, specify that architecture explicitly.
5782 @cindex @code{-b} option, i960
5783 @cindex branch recording, i960
5784 @cindex i960 branch recording
5785 Add code to collect information about conditional branches taken, for
5786 later optimization using branch prediction bits. (The conditional branch
5787 instructions have branch prediction bits in the CA, CB, and CC
5788 architectures.) If @var{BR} represents a conditional branch instruction,
5789 the following represents the code generated by the assembler when
5790 @samp{-b} is specified:
5793 call @var{increment routine}
5794 .word 0 # pre-counter
5796 call @var{increment routine}
5797 .word 0 # post-counter
5800 The counter following a branch records the number of times that branch
5801 was @emph{not} taken; the differenc between the two counters is the
5802 number of times the branch @emph{was} taken.
5804 @cindex @code{gbr960}, i960 postprocessor
5805 @cindex branch statistics table, i960
5806 A table of every such @code{Label} is also generated, so that the
5807 external postprocessor @code{gbr960} (supplied by Intel) can locate all
5808 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
5809 this is a local symbol to permit collecting statistics for many separate
5810 object files. The table is word aligned, and begins with a two-word
5811 header. The first word, initialized to 0, is used in maintaining linked
5812 lists of branch tables. The second word is a count of the number of
5813 entries in the table, which follow immediately: each is a word, pointing
5814 to one of the labels illustrated above.
5818 @c END TEXI2ROFF-KILL
5820 +------------+------------+------------+ ... +------------+
5822 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
5824 +------------+------------+------------+ ... +------------+
5826 __BRANCH_TABLE__ layout
5833 \line{\leftskip=0pt\hskip\tableindent
5834 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
5835 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
5836 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
5838 @c END TEXI2ROFF-KILL
5840 The first word of the header is used to locate multiple branch tables,
5841 since each object file may contain one. Normally the links are
5842 maintained with a call to an initialization routine, placed at the
5843 beginning of each function in the file. The @sc{gnu} C compiler
5844 generates these calls automatically when you give it a @samp{-b} option.
5845 For further details, see the documentation of @samp{gbr960}.
5848 @cindex @code{-no-relax} option, i960
5849 Normally, Compare-and-Branch instructions with targets that require
5850 displacements greater than 13 bits (or that have external targets) are
5851 replaced with the corresponding compare (or @samp{chkbit}) and branch
5852 instructions. You can use the @samp{-no-relax} option to specify that
5853 @code{@value{AS}} should generate errors instead, if the target displacement
5854 is larger than 13 bits.
5856 This option does not affect the Compare-and-Jump instructions; the code
5857 emitted for them is @emph{always} adjusted when necessary (depending on
5858 displacement size), regardless of whether you use @samp{-no-relax}.
5861 @node Floating Point-i960
5862 @section Floating Point
5864 @cindex floating point, i960 (@sc{ieee})
5865 @cindex i960 floating point (@sc{ieee})
5866 @code{@value{AS}} generates @sc{ieee} floating-point numbers for the directives
5867 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
5869 @node Directives-i960
5870 @section i960 Machine Directives
5872 @cindex machine directives, i960
5873 @cindex i960 machine directives
5876 @cindex @code{bss} directive, i960
5877 @item .bss @var{symbol}, @var{length}, @var{align}
5878 Reserve @var{length} bytes in the bss section for a local @var{symbol},
5879 aligned to the power of two specified by @var{align}. @var{length} and
5880 @var{align} must be positive absolute expressions. This directive
5881 differs from @samp{.lcomm} only in that it permits you to specify
5882 an alignment. @xref{Lcomm,,@code{.lcomm}}.
5886 @item .extended @var{flonums}
5887 @cindex @code{extended} directive, i960
5888 @code{.extended} expects zero or more flonums, separated by commas; for
5889 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
5890 floating-point number.
5892 @item .leafproc @var{call-lab}, @var{bal-lab}
5893 @cindex @code{leafproc} directive, i960
5894 You can use the @samp{.leafproc} directive in conjunction with the
5895 optimized @code{callj} instruction to enable faster calls of leaf
5896 procedures. If a procedure is known to call no other procedures, you
5897 may define an entry point that skips procedure prolog code (and that does
5898 not depend on system-supplied saved context), and declare it as the
5899 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
5900 entry point that goes through the normal prolog, you can specify that
5901 entry point as @var{call-lab}.
5903 A @samp{.leafproc} declaration is meant for use in conjunction with the
5904 optimized call instruction @samp{callj}; the directive records the data
5905 needed later to choose between converting the @samp{callj} into a
5906 @code{bal} or a @code{call}.
5908 @var{call-lab} is optional; if only one argument is present, or if the
5909 two arguments are identical, the single argument is assumed to be the
5910 @code{bal} entry point.
5912 @item .sysproc @var{name}, @var{index}
5913 @cindex @code{sysproc} directive, i960
5914 The @samp{.sysproc} directive defines a name for a system procedure.
5915 After you define it using @samp{.sysproc}, you can use @var{name} to
5916 refer to the system procedure identified by @var{index} when calling
5917 procedures with the optimized call instruction @samp{callj}.
5919 Both arguments are required; @var{index} must be between 0 and 31
5923 @node Opcodes for i960
5924 @section i960 Opcodes
5926 @cindex opcodes, i960
5927 @cindex i960 opcodes
5928 All Intel 960 machine instructions are supported;
5929 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
5930 selecting the instruction subset for a particular 960
5931 architecture.@refill
5933 Some opcodes are processed beyond simply emitting a single corresponding
5934 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
5935 instructions with target displacements larger than 13 bits.
5938 * callj-i960:: @code{callj}
5939 * Compare-and-branch-i960:: Compare-and-Branch
5943 @subsection @code{callj}
5945 @cindex @code{callj}, i960 pseudo-opcode
5946 @cindex i960 @code{callj} pseudo-opcode
5947 You can write @code{callj} to have the assembler or the linker determine
5948 the most appropriate form of subroutine call: @samp{call},
5949 @samp{bal}, or @samp{calls}. If the assembly source contains
5950 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
5951 defining the operand---then @code{@value{AS}} translates the
5952 @code{callj}; if not, it simply emits the @code{callj}, leaving it
5953 for the linker to resolve.
5955 @node Compare-and-branch-i960
5956 @subsection Compare-and-Branch
5958 @cindex i960 compare/branch instructions
5959 @cindex compare/branch instructions, i960
5960 The 960 architectures provide combined Compare-and-Branch instructions
5961 that permit you to store the branch target in the lower 13 bits of the
5962 instruction word itself. However, if you specify a branch target far
5963 enough away that its address won't fit in 13 bits, the assembler can
5964 either issue an error, or convert your Compare-and-Branch instruction
5965 into separate instructions to do the compare and the branch.
5967 @cindex compare and jump expansions, i960
5968 @cindex i960 compare and jump expansions
5969 Whether @code{@value{AS}} gives an error or expands the instruction depends
5970 on two choices you can make: whether you use the @samp{-no-relax} option,
5971 and whether you use a ``Compare and Branch'' instruction or a ``Compare
5972 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
5973 expanded if necessary; the ``Branch'' instructions are expanded when
5974 necessary @emph{unless} you specify @code{-no-relax}---in which case
5975 @code{@value{AS}} gives an error instead.
5977 These are the Compare-and-Branch instructions, their ``Jump'' variants,
5978 and the instruction pairs they may expand into:
5982 @c END TEXI2ROFF-KILL
5985 Branch Jump Expanded to
5986 ------ ------ ------------
5989 cmpibe cmpije cmpi; be
5990 cmpibg cmpijg cmpi; bg
5991 cmpibge cmpijge cmpi; bge
5992 cmpibl cmpijl cmpi; bl
5993 cmpible cmpijle cmpi; ble
5994 cmpibno cmpijno cmpi; bno
5995 cmpibne cmpijne cmpi; bne
5996 cmpibo cmpijo cmpi; bo
5997 cmpobe cmpoje cmpo; be
5998 cmpobg cmpojg cmpo; bg
5999 cmpobge cmpojge cmpo; bge
6000 cmpobl cmpojl cmpo; bl
6001 cmpoble cmpojle cmpo; ble
6002 cmpobne cmpojne cmpo; bne
6008 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
6009 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
6010 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
6011 bbc& & chkbit; bno\cr
6012 bbs& & chkbit; bo\cr
6013 cmpibe& cmpije& cmpi; be\cr
6014 cmpibg& cmpijg& cmpi; bg\cr
6015 cmpibge& cmpijge& cmpi; bge\cr
6016 cmpibl& cmpijl& cmpi; bl\cr
6017 cmpible& cmpijle& cmpi; ble\cr
6018 cmpibno& cmpijno& cmpi; bno\cr
6019 cmpibne& cmpijne& cmpi; bne\cr
6020 cmpibo& cmpijo& cmpi; bo\cr
6021 cmpobe& cmpoje& cmpo; be\cr
6022 cmpobg& cmpojg& cmpo; bg\cr
6023 cmpobge& cmpojge& cmpo; bge\cr
6024 cmpobl& cmpojl& cmpo; bl\cr
6025 cmpoble& cmpojle& cmpo; ble\cr
6026 cmpobne& cmpojne& cmpo; bne\cr}
6028 @c END TEXI2ROFF-KILL
6034 @node M68K-Dependent
6035 @chapter M680x0 Dependent Features
6038 @node Machine Dependencies
6039 @chapter M680x0 Dependent Features
6042 @cindex M680x0 support
6044 * M68K-Opts:: M680x0 Options
6045 * M68K-Syntax:: Syntax
6046 * M68K-Moto-Syntax:: Motorola Syntax
6047 * M68K-Float:: Floating Point
6048 * M68K-Directives:: 680x0 Machine Directives
6049 * M68K-opcodes:: Opcodes
6053 @section M680x0 Options
6055 @cindex options, M680x0
6056 @cindex M680x0 options
6057 The Motorola 680x0 version of @code{@value{AS}} has two machine dependent options.
6058 One shortens undefined references from 32 to 16 bits, while the
6059 other is used to tell @code{@value{AS}} what kind of machine it is
6062 @cindex @code{-l} option, M680x0
6063 You can use the @samp{-l} option to shorten the size of references to undefined
6064 symbols. If you do not use the @samp{-l} option, references to undefined
6065 symbols are wide enough for a full @code{long} (32 bits). (Since
6066 @code{@value{AS}} cannot know where these symbols end up, @code{@value{AS}} can
6067 only allocate space for the linker to fill in later. Since @code{@value{AS}}
6068 does not know how far away these symbols are, it allocates as much space as it
6069 can.) If you use this option, the references are only one word wide (16 bits).
6070 This may be useful if you want the object file to be as small as possible, and
6071 you know that the relevant symbols are always less than 17 bits away.
6073 @cindex @code{-m68000} and related options
6074 @cindex architecture options, M680x0
6075 @cindex M680x0 architecture options
6076 The 680x0 version of @code{@value{AS}} is most frequently used to assemble
6077 programs for the Motorola MC68020 microprocessor. Occasionally it is
6078 used to assemble programs for the mostly similar, but slightly different
6079 MC68000 or MC68010 microprocessors. You can give @code{@value{AS}} the options
6080 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
6081 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
6088 This syntax for the Motorola 680x0 was developed at @sc{mit}.
6090 @cindex M680x0 syntax
6091 @cindex syntax, M680x0
6092 @cindex M680x0 size modifiers
6093 @cindex size modifiers, M680x0
6094 The 680x0 version of @code{@value{AS}} uses syntax compatible with the Sun
6095 assembler. Intervening periods are ignored; for example, @samp{movl} is
6096 equivalent to @samp{move.l}.
6099 If @code{@value{AS}} is compiled with SUN_ASM_SYNTAX defined, it
6100 also allows Sun-style local labels of the form @samp{1$} through
6104 In the following table @dfn{apc} stands for any of the address
6105 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
6106 Program Counter (@samp{pc}), or the zero-address relative to the
6107 program counter (@samp{zpc}).
6109 @cindex M680x0 addressing modes
6110 @cindex addressing modes, M680x0
6111 The following addressing modes are understood:
6114 @samp{#@var{digits}}
6117 @samp{%d0} through @samp{%d7}
6119 @item Address Register
6120 @samp{%a0} through @samp{%a7}@*
6121 @samp{%a7} is also known as @samp{%sp}, i.e. the Stack Pointer. @code{%a6}
6122 is also known as @samp{%fp}, the Frame Pointer.
6124 @item Address Register Indirect
6125 @samp{%a0@@} through @samp{%a7@@}
6127 @item Address Register Postincrement
6128 @samp{%a0@@+} through @samp{%a7@@+}
6130 @item Address Register Predecrement
6131 @samp{%a0@@-} through @samp{%a7@@-}
6133 @item Indirect Plus Offset
6134 @samp{%@var{apc}@@(@var{digits})}
6137 @samp{%@var{apc}@@(@var{digits},%@var{register}:@var{size}:@var{scale})}
6139 or @samp{%@var{apc}@@(%@var{register}:@var{size}:@var{scale})}
6142 @samp{%@var{apc}@@(@var{digits})@@(@var{digits},%@var{register}:@var{size}:@var{scale})}
6144 or @samp{%@var{apc}@@(@var{digits})@@(%@var{register}:@var{size}:@var{scale})}
6147 @samp{%@var{apc}@@(@var{digits},%@var{register}:@var{size}:@var{scale})@@(@var{digits})}
6149 or @samp{%@var{apc}@@(%@var{register}:@var{size}:@var{scale})@@(@var{digits})}
6151 @item Memory Indirect
6152 @samp{%@var{apc}@@(@var{digits})@@(@var{digits})}
6155 @samp{@var{symbol}}, or @samp{@var{digits}}
6157 @c pesch@cygnus.com: gnu, rich concur the following needs careful
6158 @c research before documenting.
6159 , or either of the above followed
6160 by @samp{:b}, @samp{:w}, or @samp{:l}.
6164 For some configurations, especially those where the compiler normally does not
6165 prepend an underscore to the names of user variables, the assembler requires a
6166 @samp{%} before any use of a register name. This is intended to let the
6167 assembler distinguish between C variables and registers named @samp{a0} through
6168 @samp{a7}, and so on. The @samp{%} is always accepted, but is not required for
6169 certain configurations, notably @samp{sun3}.
6171 @node M68K-Moto-Syntax
6172 @section Motorola Syntax
6174 @cindex Motorola syntax for the 680x0
6175 @cindex alternate syntax for the 680x0
6177 The standard Motorola syntax for this chip differs from the syntax already
6178 discussed (@pxref{M68K-Syntax,,Syntax}). @code{@value{AS}} can accept some
6179 forms of Motorola syntax for operands, even if @sc{mit} syntax is used for
6180 other operands in the same instruction. The two kinds of syntax are fully
6181 compatible; our support for Motorola syntax is simply incomplete at present.
6183 @cindex M680x0 syntax
6184 @cindex syntax, M680x0
6185 In particular, you may write or generate M68K assembler with the
6186 following conventions:
6188 (In the following table @dfn{%apc} stands for any of the address registers
6189 (@samp{%a0} through @samp{%a7}), nothing (@samp{}), the Program Counter
6190 (@samp{%pc}), or the zero-address relative to the program counter
6193 @cindex M680x0 addressing modes
6194 @cindex addressing modes, M680x0
6195 The following additional addressing modes are understood:
6197 @item Address Register Indirect
6198 @samp{%a0} through @samp{%a7}@*
6199 @samp{%a7} is also known as @samp{%sp}, i.e. the Stack Pointer. @code{%a6}
6200 is also known as @samp{%fp}, the Frame Pointer.
6202 @item Address Register Postincrement
6203 @samp{(%a0)+} through @samp{(%a7)+}
6205 @item Address Register Predecrement
6206 @samp{-(%a0)} through @samp{-(%a7)}
6208 @item Indirect Plus Offset
6209 @samp{@var{digits}(%@var{apc})}
6212 @samp{@var{digits}(%@var{apc},(%@var{register}.@var{size}*@var{scale}))}@*
6213 or @samp{(%@var{apc},%@var{register}.@var{size}*@var{scale})}@*
6214 In either case, @var{size} and @var{scale} are optional
6215 (@var{scale} defaults to @samp{1}, @var{size} defaults to @samp{l}).
6216 @var{scale} can be @samp{1}, @samp{2}, @samp{4}, or @samp{8}.
6217 @var{size} can be @samp{w} or @samp{l}. @var{scale} is only supported
6218 on the 68020 and greater.
6221 Other, more complex addressing modes permitted in Motorola syntax are not
6225 @section Floating Point
6227 @cindex floating point, M680x0
6228 @cindex M680x0 floating point
6229 @c FIXME is this "not too well tested" crud STILL true?
6230 The floating point code is not too well tested, and may have
6233 Packed decimal (P) format floating literals are not supported.
6234 Feel free to add the code!
6236 The floating point formats generated by directives are these.
6240 @cindex @code{float} directive, M680x0
6241 @code{Single} precision floating point constants.
6244 @cindex @code{double} directive, M680x0
6245 @code{Double} precision floating point constants.
6248 There is no directive to produce regions of memory holding
6249 extended precision numbers, however they can be used as
6250 immediate operands to floating-point instructions. Adding a
6251 directive to create extended precision numbers would not be
6252 hard, but it has not yet seemed necessary.
6254 @node M68K-Directives
6255 @section 680x0 Machine Directives
6257 @cindex M680x0 directives
6258 @cindex directives, M680x0
6259 In order to be compatible with the Sun assembler the 680x0 assembler
6260 understands the following directives.
6264 @cindex @code{data1} directive, M680x0
6265 This directive is identical to a @code{.data 1} directive.
6268 @cindex @code{data2} directive, M680x0
6269 This directive is identical to a @code{.data 2} directive.
6272 @cindex @code{even} directive, M680x0
6273 This directive is identical to a @code{.align 1} directive.
6274 @c Is this true? does it work???
6277 @cindex @code{skip} directive, M680x0
6278 This directive is identical to a @code{.space} directive.
6285 @cindex M680x0 opcodes
6286 @cindex opcodes, M680x0
6287 @cindex instruction set, M680x0
6288 @c pesch@cygnus.com: I don't see any point in the following
6289 @c paragraph. Bugs are bugs; how does saying this
6292 Danger: Several bugs have been found in the opcode table (and
6293 fixed). More bugs may exist. Be careful when using obscure
6298 * M68K-Branch:: Branch Improvement
6299 * M68K-Chars:: Special Characters
6303 @subsection Branch Improvement
6305 @cindex pseudo-opcodes, M680x0
6306 @cindex M680x0 pseudo-opcodes
6307 @cindex branch improvement, M680x0
6308 @cindex M680x0 branch improvement
6309 Certain pseudo opcodes are permitted for branch instructions.
6310 They expand to the shortest branch instruction that reach the
6311 target. Generally these mnemonics are made by substituting @samp{j} for
6312 @samp{b} at the start of a Motorola mnemonic.
6314 The following table summarizes the pseudo-operations. A @code{*} flags
6315 cases that are more fully described after the table:
6319 +-------------------------------------------------
6321 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
6322 +-------------------------------------------------
6323 jbsr |bsrs bsr bsrl jsr jsr
6324 jra |bras bra bral jmp jmp
6325 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
6326 * dbXX |dbXX dbXX dbXX; bra; jmpl
6327 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
6330 NX: negative of condition XX
6333 @center @code{*}---see full description below
6338 These are the simplest jump pseudo-operations; they always map to one
6339 particular machine instruction, depending on the displacement to the
6343 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
6344 where @var{XX} is a conditional branch or condition-code test. The full
6345 list of pseudo-ops in this family is:
6347 jhi jls jcc jcs jne jeq jvc
6348 jvs jpl jmi jge jlt jgt jle
6351 For the cases of non-PC relative displacements and long displacements on
6352 the 68000 or 68010, @code{@value{AS}} issues a longer code fragment in terms of
6353 @var{NX}, the opposite condition to @var{XX}. For example, for the
6354 non-PC relative case:
6366 The full family of pseudo-operations covered here is
6368 dbhi dbls dbcc dbcs dbne dbeq dbvc
6369 dbvs dbpl dbmi dbge dblt dbgt dble
6373 Other than for word and byte displacements, when the source reads
6374 @samp{db@var{XX} foo}, @code{@value{AS}} emits
6383 This family includes
6385 fjne fjeq fjge fjlt fjgt fjle fjf
6386 fjt fjgl fjgle fjnge fjngl fjngle fjngt
6387 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
6388 fjor fjseq fjsf fjsne fjst fjueq fjuge
6389 fjugt fjule fjult fjun
6392 For branch targets that are not PC relative, @code{@value{AS}} emits
6398 when it encounters @samp{fj@var{XX} foo}.
6403 @subsection Special Characters
6405 @cindex special characters, M680x0
6406 @cindex M680x0 immediate character
6407 @cindex immediate character, M680x0
6408 @cindex M680x0 line comment character
6409 @cindex line comment character, M680x0
6410 @cindex comments, M680x0
6411 The immediate character is @samp{#} for Sun compatibility. The
6412 line-comment character is @samp{|}. If a @samp{#} appears at the
6413 beginning of a line, it is treated as a comment unless it looks like
6414 @samp{# line file}, in which case it is treated normally.
6418 @c FIXME! Stop ignoring when filled in.
6423 The 32x32 version of @code{@value{AS}} accepts a @samp{-m32032} option to
6424 specify thiat it is compiling for a 32032 processor, or a
6425 @samp{-m32532} to specify that it is compiling for a 32532 option.
6426 The default (if neither is specified) is chosen when the assembler
6430 I don't know anything about the 32x32 syntax assembled by
6431 @code{@value{AS}}. Someone who undersands the processor (I've never seen
6432 one) and the possible syntaxes should write this section.
6434 @section Floating Point
6435 The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{AS}}
6436 only creates single or double precision values. I don't know if the
6437 32x32 understands extended precision numbers.
6439 @section 32x32 Machine Directives
6440 The 32x32 has no machine dependent directives.
6446 @node Sparc-Dependent
6447 @chapter SPARC Dependent Features
6450 @node Machine Dependencies
6451 @chapter SPARC Dependent Features
6454 @cindex SPARC support
6456 * Sparc-Opts:: Options
6457 * Sparc-Float:: Floating Point
6458 * Sparc-Directives:: Sparc Machine Directives
6464 @cindex options for SPARC
6465 @cindex SPARC options
6466 @cindex architectures, SPARC
6467 @cindex SPARC architectures
6468 The SPARC chip family includes several successive levels (or other
6469 variants) of chip, using the same core instruction set, but including
6470 a few additional instructions at each level.
6472 By default, @code{@value{AS}} assumes the core instruction set (SPARC
6473 v6), but ``bumps'' the architecture level as needed: it switches to
6474 successively higher architectures as it encounters instructions that
6475 only exist in the higher levels.
6478 @item -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite
6484 Use one of the @samp{-A} options to select one of the SPARC
6485 architectures explicitly. If you select an architecture explicitly,
6486 @code{@value{AS}} reports a fatal error if it encounters an instruction
6487 or feature requiring a higher level.
6490 Permit the assembler to ``bump'' the architecture level as required, but
6491 warn whenever it is necessary to switch to another level.
6495 @c FIXME: (sparc) Fill in "syntax" section!
6496 @c subsection syntax
6497 I don't know anything about Sparc syntax. Someone who does
6498 will have to write this section.
6502 @section Floating Point
6504 @cindex floating point, SPARC (@sc{ieee})
6505 @cindex SPARC floating point (@sc{ieee})
6506 The Sparc uses @sc{ieee} floating-point numbers.
6508 @node Sparc-Directives
6509 @section Sparc Machine Directives
6511 @cindex SPARC machine directives
6512 @cindex machine directives, SPARC
6513 The Sparc version of @code{@value{AS}} supports the following additional
6518 @cindex @code{align} directive, SPARC
6519 This must be followed by the desired alignment in bytes.
6522 @cindex @code{common} directive, SPARC
6523 This must be followed by a symbol name, a positive number, and
6524 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
6525 syntax is different.
6528 @cindex @code{half} directive, SPARC
6529 This is functionally identical to @code{.short}.
6532 @cindex @code{proc} directive, SPARC
6533 This directive is ignored. Any text following it on the same
6534 line is also ignored.
6537 @cindex @code{reserve} directive, SPARC
6538 This must be followed by a symbol name, a positive number, and
6539 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
6540 syntax is different.
6543 @cindex @code{seg} directive, SPARC
6544 This must be followed by @code{"text"}, @code{"data"}, or
6545 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
6549 @cindex @code{skip} directive, SPARC
6550 This is functionally identical to the @code{.space} directive.
6553 @cindex @code{word} directive, SPARC
6554 On the Sparc, the @code{.word} directive produces 32 bit values,
6555 instead of the 16 bit values it produces on many other machines.
6558 @cindex @code{xword} directive, SPARC
6559 On the Sparc V9 processor, the @code{.xword} directive produces
6567 @node i386-Dependent
6568 @chapter 80386 Dependent Features
6571 @node Machine Dependencies
6572 @chapter 80386 Dependent Features
6575 @cindex i386 support
6576 @cindex i80306 support
6578 * i386-Options:: Options
6579 * i386-Syntax:: AT&T Syntax versus Intel Syntax
6580 * i386-Opcodes:: Opcode Naming
6581 * i386-Regs:: Register Naming
6582 * i386-prefixes:: Opcode Prefixes
6583 * i386-Memory:: Memory References
6584 * i386-jumps:: Handling of Jump Instructions
6585 * i386-Float:: Floating Point
6586 * i386-16bit:: Writing 16-bit Code
6587 * i386-Notes:: Notes
6593 @cindex options for i386 (none)
6594 @cindex i386 options (none)
6595 The 80386 has no machine dependent options.
6598 @section AT&T Syntax versus Intel Syntax
6600 @cindex i386 syntax compatibility
6601 @cindex syntax compatibility, i386
6602 In order to maintain compatibility with the output of @code{@value{GCC}},
6603 @code{@value{AS}} supports AT&T System V/386 assembler syntax. This is quite
6604 different from Intel syntax. We mention these differences because
6605 almost all 80386 documents used only Intel syntax. Notable differences
6606 between the two syntaxes are:
6610 @cindex immediate operands, i386
6611 @cindex i386 immediate operands
6612 @cindex register operands, i386
6613 @cindex i386 register operands
6614 @cindex jump/call operands, i386
6615 @cindex i386 jump/call operands
6616 @cindex operand delimiters, i386
6617 AT&T immediate operands are preceded by @samp{$}; Intel immediate
6618 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
6619 AT&T register operands are preceded by @samp{%}; Intel register operands
6620 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
6621 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
6624 @cindex i386 source, destination operands
6625 @cindex source, destination operands; i386
6626 AT&T and Intel syntax use the opposite order for source and destination
6627 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
6628 @samp{source, dest} convention is maintained for compatibility with
6629 previous Unix assemblers.
6632 @cindex opcode suffixes, i386
6633 @cindex sizes operands, i386
6634 @cindex i386 size suffixes
6635 In AT&T syntax the size of memory operands is determined from the last
6636 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
6637 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
6638 memory references. Intel syntax accomplishes this by prefixes memory
6639 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
6640 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
6641 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
6644 @cindex return instructions, i386
6645 @cindex i386 jump, call, return
6646 Immediate form long jumps and calls are
6647 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
6649 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
6651 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
6652 @samp{ret far @var{stack-adjust}}.
6655 @cindex sections, i386
6656 @cindex i386 sections
6657 The AT&T assembler does not provide support for multiple section
6658 programs. Unix style systems expect all programs to be single sections.
6662 @section Opcode Naming
6664 @cindex i386 opcode naming
6665 @cindex opcode naming, i386
6666 Opcode names are suffixed with one character modifiers which specify the
6667 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
6668 byte, word, and long operands. If no suffix is specified by an
6669 instruction and it contains no memory operands then @code{@value{AS}} tries to
6670 fill in the missing suffix based on the destination register operand
6671 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
6672 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
6673 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
6674 assembler which assumes that a missing opcode suffix implies long
6675 operand size. (This incompatibility does not affect compiler output
6676 since compilers always explicitly specify the opcode suffix.)
6678 Almost all opcodes have the same names in AT&T and Intel format. There
6679 are a few exceptions. The sign extend and zero extend instructions need
6680 two sizes to specify them. They need a size to sign/zero extend
6681 @emph{from} and a size to zero extend @emph{to}. This is accomplished
6682 by using two opcode suffixes in AT&T syntax. Base names for sign extend
6683 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
6684 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
6685 suffixes are tacked on to this base name, the @emph{from} suffix before
6686 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
6687 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
6688 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
6689 and @samp{wl} (from word to long).
6691 @cindex conversion instructions, i386
6692 @cindex i386 conversion instructions
6693 The Intel-syntax conversion instructions
6697 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
6700 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
6703 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
6706 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
6710 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
6711 AT&T naming. @code{@value{AS}} accepts either naming for these instructions.
6713 @cindex jump instructions, i386
6714 @cindex call instructions, i386
6715 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
6716 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
6720 @section Register Naming
6722 @cindex i386 registers
6723 @cindex registers, i386
6724 Register operands are always prefixes with @samp{%}. The 80386 registers
6729 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
6730 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
6731 frame pointer), and @samp{%esp} (the stack pointer).
6734 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
6735 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
6738 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
6739 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
6740 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
6741 @samp{%cx}, and @samp{%dx})
6744 the 6 section registers @samp{%cs} (code section), @samp{%ds}
6745 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
6749 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
6753 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
6754 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
6757 the 2 test registers @samp{%tr6} and @samp{%tr7}.
6760 the 8 floating point register stack @samp{%st} or equivalently
6761 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
6762 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
6766 @section Opcode Prefixes
6768 @cindex i386 opcode prefixes
6769 @cindex opcode prefixes, i386
6770 @cindex prefixes, i386
6771 Opcode prefixes are used to modify the following opcode. They are used
6772 to repeat string instructions, to provide section overrides, to perform
6773 bus lock operations, and to give operand and address size (16-bit
6774 operands are specified in an instruction by prefixing what would
6775 normally be 32-bit operands with a ``operand size'' opcode prefix).
6776 Opcode prefixes are usually given as single-line instructions with no
6777 operands, and must directly precede the instruction they act upon. For
6778 example, the @samp{scas} (scan string) instruction is repeated with:
6784 Here is a list of opcode prefixes:
6788 @cindex section override prefixes, i386
6789 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
6790 @samp{fs}, @samp{gs}. These are automatically added by specifying
6791 using the @var{section}:@var{memory-operand} form for memory references.
6794 @cindex size prefixes, i386
6795 Operand/Address size prefixes @samp{data16} and @samp{addr16}
6796 change 32-bit operands/addresses into 16-bit operands/addresses. Note
6797 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
6798 are not supported (yet).
6801 @cindex bus lock prefixes, i386
6802 @cindex inhibiting interrupts, i386
6803 The bus lock prefix @samp{lock} inhibits interrupts during
6804 execution of the instruction it precedes. (This is only valid with
6805 certain instructions; see a 80386 manual for details).
6808 @cindex coprocessor wait, i386
6809 The wait for coprocessor prefix @samp{wait} waits for the
6810 coprocessor to complete the current instruction. This should never be
6811 needed for the 80386/80387 combination.
6814 @cindex repeat prefixes, i386
6815 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
6816 to string instructions to make them repeat @samp{%ecx} times.
6820 @section Memory References
6822 @cindex i386 memory references
6823 @cindex memory references, i386
6824 An Intel syntax indirect memory reference of the form
6827 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
6831 is translated into the AT&T syntax
6834 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
6838 where @var{base} and @var{index} are the optional 32-bit base and
6839 index registers, @var{disp} is the optional displacement, and
6840 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
6841 to calculate the address of the operand. If no @var{scale} is
6842 specified, @var{scale} is taken to be 1. @var{section} specifies the
6843 optional section register for the memory operand, and may override the
6844 default section register (see a 80386 manual for section register
6845 defaults). Note that section overrides in AT&T syntax @emph{must} have
6846 be preceded by a @samp{%}. If you specify a section override which
6847 coincides with the default section register, @code{@value{AS}} does @emph{not}
6848 output any section register override prefixes to assemble the given
6849 instruction. Thus, section overrides can be specified to emphasize which
6850 section register is used for a given memory operand.
6852 Here are some examples of Intel and AT&T style memory references:
6855 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
6856 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
6857 missing, and the default section is used (@samp{%ss} for addressing with
6858 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
6860 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
6861 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
6862 @samp{foo}. All other fields are missing. The section register here
6863 defaults to @samp{%ds}.
6865 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
6866 This uses the value pointed to by @samp{foo} as a memory operand.
6867 Note that @var{base} and @var{index} are both missing, but there is only
6868 @emph{one} @samp{,}. This is a syntactic exception.
6870 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
6871 This selects the contents of the variable @samp{foo} with section
6872 register @var{section} being @samp{%gs}.
6875 Absolute (as opposed to PC relative) call and jump operands must be
6876 prefixed with @samp{*}. If no @samp{*} is specified, @code{@value{AS}}
6877 always chooses PC relative addressing for jump/call labels.
6879 Any instruction that has a memory operand @emph{must} specify its size (byte,
6880 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
6884 @section Handling of Jump Instructions
6886 @cindex jump optimization, i386
6887 @cindex i386 jump optimization
6888 Jump instructions are always optimized to use the smallest possible
6889 displacements. This is accomplished by using byte (8-bit) displacement
6890 jumps whenever the target is sufficiently close. If a byte displacement
6891 is insufficient a long (32-bit) displacement is used. We do not support
6892 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
6893 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
6894 @samp{%eip} to 16 bits after the word displacement is added.
6896 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
6897 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in byte
6898 displacements, so that if you use these instructions (@code{@value{GCC}} does
6899 not use them) you may get an error message (and incorrect code). The AT&T
6900 80386 assembler tries to get around this problem by expanding @samp{jcxz foo}
6911 @section Floating Point
6913 @cindex i386 floating point
6914 @cindex floating point, i386
6915 All 80387 floating point types except packed BCD are supported.
6916 (BCD support may be added without much difficulty). These data
6917 types are 16-, 32-, and 64- bit integers, and single (32-bit),
6918 double (64-bit), and extended (80-bit) precision floating point.
6919 Each supported type has an opcode suffix and a constructor
6920 associated with it. Opcode suffixes specify operand's data
6921 types. Constructors build these data types into memory.
6925 @cindex @code{float} directive, i386
6926 @cindex @code{single} directive, i386
6927 @cindex @code{double} directive, i386
6928 @cindex @code{tfloat} directive, i386
6929 Floating point constructors are @samp{.float} or @samp{.single},
6930 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
6931 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
6932 @samp{t} stands for temporary real, and that the 80387 only supports
6933 this format via the @samp{fldt} (load temporary real to stack top) and
6934 @samp{fstpt} (store temporary real and pop stack) instructions.
6937 @cindex @code{word} directive, i386
6938 @cindex @code{long} directive, i386
6939 @cindex @code{int} directive, i386
6940 @cindex @code{quad} directive, i386
6941 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
6942 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
6943 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
6944 (quad). As with the temporary real format the 64-bit @samp{q} format is
6945 only present in the @samp{fildq} (load quad integer to stack top) and
6946 @samp{fistpq} (store quad integer and pop stack) instructions.
6949 Register to register operations do not require opcode suffixes,
6950 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
6952 @cindex i386 @code{fwait} instruction
6953 @cindex @code{fwait instruction}, i386
6954 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
6955 instructions are almost never needed (this is not the case for the
6956 80286/80287 and 8086/8087 combinations). Therefore, @code{@value{AS}} suppresses
6957 the @samp{fwait} instruction whenever it is implicitly selected by one
6958 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
6959 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
6960 instructions are made equivalent to @samp{f@dots{}} instructions. If
6961 @samp{fwait} is desired it must be explicitly coded.
6964 @section Writing 16-bit Code
6966 @cindex i386 16-bit code
6967 @cindex 16-bit code, i386
6968 @cindex real-mode code, i386
6969 @cindex @code{code16} directive, i386
6970 @cindex @code{code32} directive, i386
6971 While GAS normally writes only ``pure'' 32-bit i386 code, it has limited
6972 support for writing code to run in real mode or in 16-bit protected mode
6973 code segments. To do this, insert a @samp{.code16} directive before the
6974 assembly language instructions to be run in 16-bit mode. You can switch
6975 GAS back to writing normal 32-bit code with the @samp{.code32} directive.
6977 GAS understands exactly the same assembly language syntax in 16-bit mode as
6978 in 32-bit mode. The function of any given instruction is exactly the same
6979 regardless of mode, as long as the resulting object code is executed in the
6980 mode for which GAS wrote it. So, for example, the @samp{ret} mnemonic
6981 produces a 32-bit return instruction regardless of whether it is to be run
6982 in 16-bit or 32-bit mode. (If GAS is in 16-bit mode, it will add an
6983 operand size prefix to the instruction to force it to be a 32-bit return.)
6985 This means, for one thing, that you can use GNU CC to write code to be run
6986 in real mode or 16-bit protected mode. Just insert the statement
6987 @samp{asm(".code16");} at the beginning of your C source file, and while
6988 GNU CC will still be generating 32-bit code, GAS will automatically add all
6989 the necessary size prefixes to make that code run in 16-bit mode. Of
6990 course, since GNU CC only writes small-model code (it doesn't know how to
6991 attach segment selectors to pointers like native x86 compilers do), any
6992 16-bit code you write with GNU CC will essentially be limited to a 64K
6993 address space. Also, there will be a code size and performance penalty
6994 due to all the extra address and operand size prefixes GAS has to add to
6997 Note that placing GAS in 16-bit mode does not mean that the resulting
6998 code will necessarily run on a 16-bit pre-80386 processor. To write code
6999 that runs on such a processor, you would have to refrain from using
7000 @emph{any} 32-bit constructs which require GAS to output address or
7001 operand size prefixes. At the moment this would be rather difficult,
7002 because GAS currently supports @emph{only} 32-bit addressing modes: when
7003 writing 16-bit code, it @emph{always} outputs address size prefixes for any
7004 instruction that uses a non-register addressing mode. So you can write
7005 code that runs on 16-bit processors, but only if that code never references
7011 @cindex i386 @code{mul}, @code{imul} instructions
7012 @cindex @code{mul} instruction, i386
7013 @cindex @code{imul} instruction, i386
7014 There is some trickery concerning the @samp{mul} and @samp{imul}
7015 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
7016 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
7017 for @samp{imul}) can be output only in the one operand form. Thus,
7018 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
7019 the expanding multiply would clobber the @samp{%edx} register, and this
7020 would confuse @code{@value{GCC}} output. Use @samp{imul %ebx} to get the
7021 64-bit product in @samp{%edx:%eax}.
7023 We have added a two operand form of @samp{imul} when the first operand
7024 is an immediate mode expression and the second operand is a register.
7025 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
7026 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
7033 @node Z8000-Dependent
7034 @chapter Z8000 Dependent Features
7037 @node Machine Dependencies
7038 @chapter Z8000 Dependent Features
7041 @cindex Z8000 support
7042 The Z8000 @value{AS} supports both members of the Z8000 family: the
7043 unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with
7046 When the assembler is in unsegmented mode (specified with the
7047 @code{unsegm} directive), an address takes up one word (16 bit)
7048 sized register. When the assembler is in segmented mode (specified with
7049 the @code{segm} directive), a 24-bit address takes up a long (32 bit)
7050 register. @xref{Z8000 Directives,,Assembler Directives for the Z8000},
7051 for a list of other Z8000 specific assembler directives.
7054 * Z8000 Options:: No special command-line options for Z8000
7055 * Z8000 Syntax:: Assembler syntax for the Z8000
7056 * Z8000 Directives:: Special directives for the Z8000
7057 * Z8000 Opcodes:: Opcodes
7063 @cindex Z8000 options
7064 @cindex options, Z8000
7065 @code{@value{AS}} has no additional command-line options for the Zilog
7071 * Z8000-Chars:: Special Characters
7072 * Z8000-Regs:: Register Names
7073 * Z8000-Addressing:: Addressing Modes
7077 @subsection Special Characters
7079 @cindex line comment character, Z8000
7080 @cindex Z8000 line comment character
7081 @samp{!} is the line comment character.
7083 @cindex line separator, Z8000
7084 @cindex statement separator, Z8000
7085 @cindex Z8000 line separator
7086 You can use @samp{;} instead of a newline to separate statements.
7089 @subsection Register Names
7091 @cindex Z8000 registers
7092 @cindex registers, Z8000
7093 The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer
7094 to different sized groups of registers by register number, with the
7095 prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and
7096 @samp{rq} for 64 bit registers. You can also refer to the contents of
7097 the first eight (of the sixteen 16 bit registers) by bytes. They are
7098 named @samp{r@var{n}h} and @samp{r@var{n}l}.
7101 @exdent @emph{byte registers}
7102 r0l r0h r1h r1l r2h r2l r3h r3l
7103 r4h r4l r5h r5l r6h r6l r7h r7l
7105 @exdent @emph{word registers}
7106 r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15
7108 @exdent @emph{long word registers}
7109 rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14
7111 @exdent @emph{quad word registers}
7115 @node Z8000-Addressing
7116 @subsection Addressing Modes
7118 @cindex addressing modes, Z8000
7119 @cindex Z800 addressing modes
7120 @value{AS} understands the following addressing modes for the Z8000:
7130 Direct: the 16 bit or 24 bit address (depending on whether the assembler
7131 is in segmented or unsegmented mode) of the operand is in the instruction.
7133 @item address(r@var{n})
7134 Indexed: the 16 or 24 bit address is added to the 16 bit register to produce
7135 the final address in memory of the operand.
7137 @item r@var{n}(#@var{imm})
7138 Base Address: the 16 or 24 bit register is added to the 16 bit sign
7139 extended immediate displacement to produce the final address in memory
7142 @item r@var{n}(r@var{m})
7143 Base Index: the 16 or 24 bit register r@var{n} is added to the sign
7144 extended 16 bit index register r@var{m} to produce the final address in
7145 memory of the operand.
7148 Immediate data @var{xx}.
7151 @node Z8000 Directives
7152 @section Assembler Directives for the Z8000
7154 @cindex Z8000 directives
7155 @cindex directives, Z8000
7156 The Z8000 port of @value{AS} includes these additional assembler directives,
7157 for compatibility with other Z8000 assemblers. As shown, these do not
7158 begin with @samp{.} (unlike the ordinary @value{AS} directives).
7163 Generates code for the segmented Z8001.
7167 Generates code for the unsegmented Z8002.
7171 Synonym for @code{.file}
7175 Synonum for @code{.global}
7179 Synonym for @code{.word}
7183 Synonym for @code{.long}
7187 Synonym for @code{.byte}
7191 Assemble a string. @code{sval} expects one string literal, delimited by
7192 single quotes. It assembles each byte of the string into consecutive
7193 addresses. You can use the escape sequence @samp{%@var{xx}} (where
7194 @var{xx} represents a two-digit hexadecimal number) to represent the
7195 character whose @sc{ascii} value is @var{xx}. Use this feature to
7196 describe single quote and other characters that may not appear in string
7197 literals as themselves. For example, the C statement @w{@samp{char *a =
7198 "he said \"it's 50% off\"";}} is represented in Z8000 assembly language
7199 (shown with the assembler output in hex at the left) as
7203 @let@nonarrowing=@comment
7206 68652073 sval 'he said %22it%27s 50%25 off%22%00'
7219 synonym for @code{.section}
7223 synonym for @code{.space}
7227 synonym for @code{.align 1}
7233 @cindex Z8000 opcode summary
7234 @cindex opcode summary, Z8000
7235 @cindex mnemonics, Z8000
7236 @cindex instruction summary, Z8000
7237 For detailed information on the Z8000 machine instruction set, see
7238 @cite{Z8000 Technical Manual}.
7241 @c this table, due to the multi-col faking and hardcoded order, looks silly
7242 @c except in smallbook. See comments below "@set SMALL" near top of this file.
7244 The following table summarizes the opcodes and their arguments:
7247 @let@nonarrowing=@comment
7251 rs @r{16 bit source register}
7252 rd @r{16 bit destination register}
7253 rbs @r{8 bit source register}
7254 rbd @r{8 bit destination register}
7255 rrs @r{32 bit source register}
7256 rrd @r{32 bit destination register}
7257 rqs @r{64 bit source register}
7258 rqd @r{64 bit destination register}
7259 addr @r{16/24 bit address}
7260 imm @r{immediate data}
7262 adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc
7263 adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc
7264 add rd,@@rs clrb rbd dab rbd
7265 add rd,addr com @@rd dbjnz rbd,disp7
7266 add rd,addr(rs) com addr dec @@rd,imm4m1
7267 add rd,imm16 com addr(rd) dec addr(rd),imm4m1
7268 add rd,rs com rd dec addr,imm4m1
7269 addb rbd,@@rs comb @@rd dec rd,imm4m1
7270 addb rbd,addr comb addr decb @@rd,imm4m1
7271 addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1
7272 addb rbd,imm8 comb rbd decb addr,imm4m1
7273 addb rbd,rbs comflg flags decb rbd,imm4m1
7274 addl rrd,@@rs cp @@rd,imm16 di i2
7275 addl rrd,addr cp addr(rd),imm16 div rrd,@@rs
7276 addl rrd,addr(rs) cp addr,imm16 div rrd,addr
7277 addl rrd,imm32 cp rd,@@rs div rrd,addr(rs)
7278 addl rrd,rrs cp rd,addr div rrd,imm16
7279 and rd,@@rs cp rd,addr(rs) div rrd,rs
7280 and rd,addr cp rd,imm16 divl rqd,@@rs
7281 and rd,addr(rs) cp rd,rs divl rqd,addr
7282 and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs)
7283 and rd,rs cpb addr(rd),imm8 divl rqd,imm32
7284 andb rbd,@@rs cpb addr,imm8 divl rqd,rrs
7285 andb rbd,addr cpb rbd,@@rs djnz rd,disp7
7286 andb rbd,addr(rs) cpb rbd,addr ei i2
7287 andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs
7288 andb rbd,rbs cpb rbd,imm8 ex rd,addr
7289 bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs)
7290 bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs
7291 bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs
7292 bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr
7293 bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs)
7294 bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs
7295 bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8
7296 bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8
7297 bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8
7298 bitb rbd,rs cpl rrd,@@rs ext8f imm8
7299 bpt cpl rrd,addr exts rrd
7300 call @@rd cpl rrd,addr(rs) extsb rd
7301 call addr cpl rrd,imm32 extsl rqd
7302 call addr(rd) cpl rrd,rrs halt
7303 calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs
7304 clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16
7305 clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs
7306 clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16
7307 clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1
7308 clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1
7309 inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs)
7310 inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16
7311 incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs
7312 incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs
7313 incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr
7314 incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs)
7315 ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32
7316 indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs
7317 inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd
7318 inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr
7319 iret ldib @@rd,@@rs,rr neg addr(rd)
7320 jp cc,@@rd ldir @@rd,@@rs,rr neg rd
7321 jp cc,addr ldirb @@rd,@@rs,rr negb @@rd
7322 jp cc,addr(rd) ldk rd,imm4 negb addr
7323 jr cc,disp8 ldl @@rd,rrs negb addr(rd)
7324 ld @@rd,imm16 ldl addr(rd),rrs negb rbd
7325 ld @@rd,rs ldl addr,rrs nop
7326 ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs
7327 ld addr(rd),rs ldl rd(rx),rrs or rd,addr
7328 ld addr,imm16 ldl rrd,@@rs or rd,addr(rs)
7329 ld addr,rs ldl rrd,addr or rd,imm16
7330 ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs
7331 ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs
7332 ld rd,@@rs ldl rrd,rrs orb rbd,addr
7333 ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs)
7334 ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8
7335 ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs
7336 ld rd,rs ldm addr(rd),rs,n out @@rd,rs
7337 ld rd,rs(imm16) ldm addr,rs,n out imm16,rs
7338 ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs
7339 lda rd,addr ldm rd,addr(rs),n outb imm16,rbs
7340 lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra
7341 lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba
7342 lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra
7343 ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra
7344 ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs
7345 ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs
7346 ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs
7347 ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs
7348 ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs
7349 ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs
7350 ldb rbd,@@rs mbit popl addr,@@rs
7351 ldb rbd,addr mreq rd popl rrd,@@rs
7352 ldb rbd,addr(rs) mres push @@rd,@@rs
7353 ldb rbd,imm8 mset push @@rd,addr
7354 ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs)
7355 ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16
7356 push @@rd,rs set addr,imm4 subl rrd,imm32
7357 pushl @@rd,@@rs set rd,imm4 subl rrd,rrs
7358 pushl @@rd,addr set rd,rs tcc cc,rd
7359 pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd
7360 pushl @@rd,rrs setb addr(rd),imm4 test @@rd
7361 res @@rd,imm4 setb addr,imm4 test addr
7362 res addr(rd),imm4 setb rbd,imm4 test addr(rd)
7363 res addr,imm4 setb rbd,rs test rd
7364 res rd,imm4 setflg imm4 testb @@rd
7365 res rd,rs sinb rbd,imm16 testb addr
7366 resb @@rd,imm4 sinb rd,imm16 testb addr(rd)
7367 resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd
7368 resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd
7369 resb rbd,imm4 sinib @@rd,@@rs,ra testl addr
7370 resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd)
7371 resflg imm4 sla rd,imm8 testl rrd
7372 ret cc slab rbd,imm8 trdb @@rd,@@rs,rba
7373 rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba
7374 rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr
7375 rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr
7376 rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr
7377 rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr
7378 rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr
7379 rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr
7380 rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd
7381 rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr
7382 rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd)
7383 rsvd36 sra rd,imm8 tset rd
7384 rsvd38 srab rbd,imm8 tsetb @@rd
7385 rsvd78 sral rrd,imm8 tsetb addr
7386 rsvd7e srl rd,imm8 tsetb addr(rd)
7387 rsvd9d srlb rbd,imm8 tsetb rbd
7388 rsvd9f srll rrd,imm8 xor rd,@@rs
7389 rsvdb9 sub rd,@@rs xor rd,addr
7390 rsvdbf sub rd,addr xor rd,addr(rs)
7391 sbc rd,rs sub rd,addr(rs) xor rd,imm16
7392 sbcb rbd,rbs sub rd,imm16 xor rd,rs
7393 sc imm8 sub rd,rs xorb rbd,@@rs
7394 sda rd,rs subb rbd,@@rs xorb rbd,addr
7395 sdab rbd,rs subb rbd,addr xorb rbd,addr(rs)
7396 sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8
7397 sdl rd,rs subb rbd,imm8 xorb rbd,rbs
7398 sdlb rbd,rs subb rbd,rbs xorb rbd,rbs
7399 sdll rrd,rs subl rrd,@@rs
7400 set @@rd,imm4 subl rrd,addr
7401 set addr(rd),imm4 subl rrd,addr(rs)
7413 @node MIPS-Dependent
7414 @chapter MIPS Dependent Features
7417 @node Machine Dependencies
7418 @chapter MIPS Dependent Features
7425 @sc{gnu} @code{@value{AS}} for @sc{mips} architectures supports the @sc{mips}
7426 @sc{r2000}, @sc{r3000}, @sc{r4000} and @sc{r6000} processors. For information
7427 about the @sc{mips} instruction set, see @cite{MIPS RISC Architecture}, by Kane
7428 and Heindrich (Prentice-Hall). For an overview of @sc{mips} assembly
7429 conventions, see ``Appendix D: Assembly Language Programming'' in the same
7433 * MIPS Opts:: Assembler options
7434 * MIPS Object:: ECOFF object code
7435 * MIPS Stabs:: Directives for debugging information
7436 * MIPS ISA:: Directives to override the ISA level
7440 @section Assembler options
7442 The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support these
7446 @cindex @code{-G} option (MIPS)
7448 This option sets the largest size of an object that can be referenced
7449 implicitly with the @code{gp} register. It is only accepted for targets
7450 that use @sc{ecoff} format. The default value is 8.
7452 @cindex @code{-EB} option (MIPS)
7453 @cindex @code{-EL} option (MIPS)
7454 @cindex MIPS big-endian output
7455 @cindex MIPS little-endian output
7456 @cindex big-endian output, MIPS
7457 @cindex little-endian output, MIPS
7460 Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or
7461 little-endian output at run time (unlike the other @sc{gnu} development
7462 tools, which must be configured for one or the other). Use @samp{-EB}
7463 to select big-endian output, and @samp{-EL} for little-endian.
7465 @cindex MIPS architecture options
7469 Generate code for a particular MIPS Instruction Set Architecture level.
7470 @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
7471 @samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000}
7472 processor. You can also switch instruction sets during the assembly; see
7473 @ref{MIPS ISA,, Directives to override the ISA level}.
7477 Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept
7478 the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
7479 instructions around accesses to the @samp{HI} and @samp{LO} registers.
7480 @samp{-no-m4650} turns off this option.
7482 @item -mcpu=@var{CPU}
7483 Generate code for a particular MIPS cpu. This has little effect on the
7484 assembler, but it is passed by @code{@value{GCC}}.
7486 @cindex @code{-nocpp} ignored (MIPS)
7488 This option is ignored. It is accepted for command-line compatibility with
7489 other assemblers, which use it to turn off C style preprocessing. With
7490 @sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the
7491 @sc{gnu} assembler itself never runs the C preprocessor.
7495 @c FIXME! (1) reflect these options (next item too) in option summaries;
7496 @c (2) stop teasing, say _which_ instructions expanded _how_.
7497 @code{@value{AS}} automatically macro expands certain division and
7498 multiplication instructions to check for overflow and division by zero. This
7499 option causes @code{@value{AS}} to generate code to take a trap exception
7500 rather than a break exception when an error is detected. The trap instructions
7501 are only supported at Instruction Set Architecture level 2 and higher.
7505 Generate code to take a break exception rather than a trap exception when an
7506 error is detected. This is the default.
7510 @section MIPS ECOFF object code
7512 @cindex ECOFF sections
7513 @cindex MIPS ECOFF sections
7514 Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections
7515 besides the usual @code{.text}, @code{.data} and @code{.bss}. The
7516 additional sections are @code{.rdata}, used for read-only data,
7517 @code{.sdata}, used for small data, and @code{.sbss}, used for small
7520 @cindex small objects, MIPS ECOFF
7521 @cindex @code{gp} register, MIPS
7522 When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28})
7523 register to form the address of a ``small object''. Any object in the
7524 @code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense.
7525 For external objects, or for objects in the @code{.bss} section, you can use
7526 the @code{@value{GCC}} @samp{-G} option to control the size of objects addressed via
7527 @code{$gp}; the default value is 8, meaning that a reference to any object
7528 eight bytes or smaller uses @code{$gp}. Passing @samp{-G 0} to
7529 @code{@value{AS}} prevents it from using the @code{$gp} register on the basis
7530 of object size (but the assembler uses @code{$gp} for objects in @code{.sdata}
7531 or @code{sbss} in any case). The size of an object in the @code{.bss} section
7532 is set by the @code{.comm} or @code{.lcomm} directive that defines it. The
7533 size of an external object may be set with the @code{.extern} directive. For
7534 example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes
7535 in length, whie leaving @code{sym} otherwise undefined.
7537 Using small @sc{ecoff} objects requires linker support, and assumes that the
7538 @code{$gp} register is correctly initialized (normally done automatically by
7539 the startup code). @sc{mips} @sc{ecoff} assembly code must not modify the
7540 @code{$gp} register.
7543 @section Directives for debugging information
7545 @cindex MIPS debugging directives
7546 @sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for
7547 generating debugging information which are not support by traditional @sc{mips}
7548 assemblers. These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file},
7549 @code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val},
7550 @code{.stabd}, @code{.stabn}, and @code{.stabs}. The debugging information
7551 generated by the three @code{.stab} directives can only be read by @sc{gdb},
7552 not by traditional @sc{mips} debuggers (this enhancement is required to fully
7553 support C++ debugging). These directives are primarily used by compilers, not
7554 assembly language programmers!
7557 @section Directives to override the ISA level
7559 @cindex MIPS ISA override
7560 @kindex @code{.set mips@var{n}}
7561 @sc{gnu} @code{@value{AS}} supports an additional directive to change the
7562 @sc{mips} Instruction Set Architecture level on the fly: @code{.set
7563 mips@var{n}}. @var{n} should be a number from 0 to 3. A value from 1 to 3
7564 makes the assembler accept instructions for the corresponding @sc{isa} level,
7565 from that point on in the assembly. @code{.set mips@var{n}} affects not only
7566 which instructions are permitted, but also how certain macros are expanded.
7567 @code{.set mips0} restores the @sc{isa} level to its original level: either the
7568 level you selected with command line options, or the default for your
7569 configuration. You can use this feature to permit specific @sc{r4000}
7570 instructions while assembling in 32 bit mode. Use this directive with care!
7572 Traditional @sc{mips} assemblers do not support this directive.
7576 @c reverse effect of @down at top of generic Machine-Dep chapter
7580 @node Acknowledgements
7581 @chapter Acknowledgements
7583 If you have contributed to @code{@value{AS}} and your name isn't listed here,
7584 it is not meant as a slight. We just don't know about it. Send mail to the
7585 maintainer, and we'll correct the situation. Currently (January 1994), the
7586 maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
7588 Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any more
7591 Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
7592 information and the 68k series machines, most of the preprocessing pass, and
7593 extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}.
7595 K. Richard Pixley maintained GAS for a while, adding various enhancements and
7596 many bug fixes, including merging support for several processors, breaking GAS
7597 up to handle multiple object file format back ends (including heavy rewrite,
7598 testing, an integration of the coff and b.out back ends), adding configuration
7599 including heavy testing and verification of cross assemblers and file splits
7600 and renaming, converted GAS to strictly ANSI C including full prototypes, added
7601 support for m680[34]0 and cpu32, did considerable work on i960 including a COFF
7602 port (including considerable amounts of reverse engineering), a SPARC opcode
7603 file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know''
7604 assertions and made them work, much other reorganization, cleanup, and lint.
7606 Ken Raeburn wrote the high-level BFD interface code to replace most of the code
7607 in format-specific I/O modules.
7609 The original VMS support was contributed by David L. Kashtan. Eric Youngdale
7610 has done much work with it since.
7612 The Intel 80386 machine description was written by Eliot Dresselhaus.
7614 Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
7616 The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
7617 University and Torbjorn Granlund of the Swedish Institute of Computer Science.
7619 Keith Knowles at the Open Software Foundation wrote the original MIPS back end
7620 (@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support
7621 (which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to
7622 support a.out format.
7624 Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k,
7625 tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
7626 Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
7627 use BFD for some low-level operations, for use with the H8/300 and AMD 29k
7630 John Gilmore built the AMD 29000 support, added @code{.include} support, and
7631 simplified the configuration of which versions accept which directives. He
7632 updated the 68k machine description so that Motorola's opcodes always produced
7633 fixed-size instructions (e.g. @code{jsr}), while synthetic instructions
7634 remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested
7635 cross-compilation support, and one bug in relaxation that took a week and
7636 required the proverbial one-bit fix.
7638 Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
7639 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
7640 added support for MIPS ECOFF and ELF targets, and made a few other minor
7643 Steve Chamberlain made @code{@value{AS}} able to generate listings.
7645 Hewlett-Packard contributed support for the HP9000/300.
7647 Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
7648 along with a fairly extensive HPPA testsuite (for both SOM and ELF object
7649 formats). This work was supported by both the Center for Software Science at
7650 the University of Utah and Cygnus Support.
7652 Support for ELF format files has been worked on by Mark Eichin of Cygnus
7653 Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
7654 Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
7655 Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
7656 and some initial 64-bit support).
7658 Several engineers at Cygnus Support have also provided many small bug fixes and
7659 configuration enhancements.
7661 Many others have contributed large or small bugfixes and enhancements. If
7662 you have contributed significant work and are not mentioned on this list, and
7663 want to be, let us know. Some of the history has been lost; we are not
7664 intentionally leaving anyone out.